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 |
SEE ALSO
Books
Intel CDSA Application Developer's Guide
