CSSM_Init(3)CSSM_Init(3)NAMECSSM_Init - Initialize CSSM (CDSA)
SYNOPSIS
# include <cdsa/cssm.h>
CSSM_RETURN CSSMAPI CSSM_Init( const CSSM_VERSION *Version, CSSM_PRIVI‐
LEGE_SCOPE Scope, const CSSM_GUID * CallerGuid, CSSM_KEY_HIERARCHY Key‐
Hierarchy, CSSM_PVC_MODE *PvcPolicy, const void *Reserved)
LIBRARY
Common Security Services Manager library (libcssm.so)
PARAMETERS
The major and minor version number of the CSSM release the application
is compatible with. 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(). The GUID associated with the caller.
This GUID is used to locate the caller's credentials when evaluating
the request for privileges. The CSSM_KEY_HIERARCHY option directing
CSSM what embedded key to use when verifying integrity of the named
module. Configures the way in which pointer validation checks will be
performed. If not the first call to CSSM_Init(), the previously config‐
ured 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
────────────────────────────────────────────────────────────────
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 appli‐
cation. 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 imple‐
mentation, 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 expor‐
tation of CSSM. It aids in detering unanticipated run-time modifica‐
tion of the program.
The CSSM can be configured to bypass pointer validation under some cir‐
cumstances. 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 mani‐
fest. Manifest attributes pertaining to pointer validation checking are
defined as follows:
Module Tag Value Description
CSSM CDSA_PVC_API unspecified CSSM will per‐
form 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 per‐
form 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 bound‐
ary.
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 bound‐
ary.
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 mod‐
ules 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 Mani‐ Acceptable PvcPolicy Values
fest
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 repre‐
sent an error condition.
ERRORS
Errors are described in the CDSA technical standard. See
CDSA_intro(3). CSSMERR_CSSM_SCOPE_NOT_SUPPORTED CSS‐
MERR_CSSM_PVC_ALREADY_CONFIGURED CSSMERR_CSSM_INVALID_PVC
SEE ALSO
Books
Intel CDSA Application Developer's Guide (see CDSA_intro(3))
Reference Pages
CSSM_Init(3)
