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. See CDSA.
CSSMERR_CSSM_SCOPE_NOT_SUPPORTED
CSSMERR_CSSM_PVC_ALREADY_CONFIGURED
CSSMERR_CSSM_INVALID_PVC
SEE ALSO
Books
Intel CDSA Application Developer's Guide (see CDSA)