CSSM_Init

NAME

CSSM_Init — Initialize CSSM (CDSA)

SYNOPSIS

# include <cssm.h>

CSSM_RETURN CSSMAPI CSSM_Init(
const CSSM_VERSION *Version,
CSSM_PRIVILEGE_SCOPE Scope,
const CSSM_GUID * CallerGuid,
CSSM_KEY_HIERARCHY KeyHierarchy,
CSSM_PVC_MODE *PvcPolicy,
const void *Reserved)

LIBRARY

Common Security Services Manager library (cdsa$incssm300_shr.exe)

PARAMETERS

Version (input)

The major and minor version number of the CSSM release the application is compatible with.

Scope (input)

The scope of the global privilege value. The scope may either process scope wide (CSSM_PRIVILEGE_SCOPE_PROCESS) or thread wide (CSSM_PRIVILEGE_SCOPE_THREAD). This parameter is ignored after the first call to CSSM_Init().

CallerGuid (input)

The GUID associated with the caller. This GUID is used to locate the caller's credentials when evaluating the request for privileges.

KeyHierarchy (input)

The CSSM_KEY_HIERARCHY option directing CSSM what embedded key to use when verifying integrity of the named module.

PvcPolicy (input/output)

Configures the way in which pointer validation checks will be performed. If not the first call to CSSM_Init(), the previously configured policy is returned in the PvcPolicy bitmask and the CSSM_Init() call continues processing. If successfully completed, the error code CSSMERR_CSSM_PVC_ALREADY_CONFIGURED is returned.

Value	Description
0	PVC validation is not performed
1	PVC validation is performed on application modules
2	PVC validation is performed on service provider modules
3	Both types of PVC validations are performed

Reserved (input)

A reserved input.

DESCRIPTION

This function initializes CSSM and verifies that the version of CSSM expected by the application is compatible with the version of CSSM on the system. This function should be called at least once by the application. It is an error to call any function of the CSSM API other than CSSM_Init() before a call to CSSM_Init() has returned successfully (that is, with CSSM_OK).

Implementations of CSSM might have platform specific characteristics associated with the implementation of CSSM_SetPrivilege() API. The privilege value might have thread specific scope or process specific scope. The application can specify the anticipated scope at CSSM_Init(). If the anticipated scope is not appropriate for the implementation, an error is returned. The scope can be configured only once. Subsequent attempts to configure scope are ignored.

CSSM integrity model includes the ability to make and check assertions about trusted dynamically loaded libraries. Checking assertions happens while the program executes. It is known as Pointer Validation Checking (PVC). Pointer validation checking can be applied every time execution flow crosses the CSSM API or SPI interfaces.

Performing pointer validation checks has two purposes:

It allows exportation of CSSM.
It aids in detering unanticipated run-time modification of the program.

The CSSM can be configured to bypass pointer validation under some circumstances. Pointer validation cannot be bypassed when privileged operations are being performed.

The prerequisites for performing PVC on another module, be it service provider, CSSM, or other library, are:

The module must have been signed and have an accompanying signed manifest.
The module must be loaded into process address space.
An entry-point into the module must be available.

Typically, the entry points are discovered when a module's functions are called by another module. The CSSM performs pointer validation checks based on the configured checking policy. Checking policies are established by the manufacturers of CSSM and other libraries. The checking policy to be applied during execution is configured using the CSSM_Init() call. The policy can be configured once during the life of the process and occurs the first time CSSM_Init() is called.

PVC POLICY CONFIGURATION OPTIONS

Pointer validation checking can be applied at the CSSM API interface, the CSSM SPI interface, or both. The CSSM vendor can configure a default policy through instructions contained in the CSSM signed manifest. Manifest attributes pertaining to pointer validation checking are defined as follows:

Module	Tag	Value	Description
CSSM	CDSA_PVC_API	unspecified	CSSM will perform PVC checks at the API boundary.
CSSM	CDSA_PVC_API	OFF	CSSM will not perform PVC checks at the API boundary.
CSSM	CDSA_PVC_SPI	unspecified	CSSM will perform PVC checks at the SPI boundary.
CSSM	CDSA_PVC_SPI	OFF	CSSM will not perform PVC checks at the SPI boundary.
App	CDSA_PVC_API	EXEMPT	The calling module is allowed to override the CSSM policy for the API boundary.
App	CDSA_PVC_API	unspecified	The calling module cannot weaken the CSSM API policy.
App	CDSA_PVC_SPI	EXEMPT	The calling module is allowed to override the CSSM policy for the SPI boundary.
App	CDSA_PVC_SPI	unspecified	The calling module cannot weaken the CSSM SPI policy.

The PvcPolicy parameter to CSSM_Init() configures the run-time policy for the process. The PvcPolicy parameter is a bitmask allowing both API and SPI policies to be specified simultaneously. Unspecified policies default to the most conservative operational mode. CSSM performs pointer validation checks unless explicitly disabled. Application modules cannot override CSSM policy unless exemptions are explicitly granted. The following table shows the what policies can be configured for various manifest attribute values:

CSSM Manifest	Calling Module Manifest	Acceptable PvcPolicy Values
CDSA_PVC_API=<n/a>	CDSA_PVC_API=EXEMPT	API checks: off (0) or on (1)
CDSA_PVC_API=OFF	CDSA_PVC_API=EXEMPT	API checks: off (0) or on (1)
CDSA_PVC_API=<n/a>	CDSA_PVC_API=<n/a>	API checks: on (1)
CDSA_PVC_API=OFF	CDSA_PVC_API=<n/a>	API checks: off (0) or on (1)

The following table shows the PvcPolicy configuations available for the SPI:

SSM Manifest	Calling Module Manifest	Acceptable PvcPolicy Values
CDSA_PVC_SPI=<n/a>	CDSA_PVC_SPI=EXEMPT	SPI checks: off (0) or on (2)
CDSA_PVC_SPI=OFF	CDSA_PVC_SPI=EXEMPT	SPI checks: off (0) or on (2)
CDSA_PVC_SPI=<n/a>	CDSA_PVC_SPI=<n/a>	SPI checks: on (2)
CDSA_PVC_SPI=OFF	CDSA_PVC_SPI=<n/a>	SPI checks: off (0) or on (2)

If an application module does not have a manifest and CSSM requires the application module be subject to pointer validation checks, then pointer validation checks fail and CSSM will not operate with the anonymous module. All service provider modules are expected to have signed manifests.

RETURN VALUE

A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK indicates success. All other values represent an error condition.

ERRORS

Errors are described in the CDSA Technical Standard.

CSSMERR_CSSM_SCOPE_NOT_SUPPORTED
CSSMERR_CSSM_PVC_ALREADY_CONFIGURED
CSSMERR_CSSM_INVALID_PVC

CSSM_Init

» Table of Contents

» Glossary

» Index