CSSM_Init - Initialize CSSM (CDSA)
# include <cdsa/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)
Common Security Services Manager library (libcssm.so)
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
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
----------------------------------------------------------------
A reserved input.
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 [Toc] [Back] 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 runtime
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 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.
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 are described in the CDSA technical standard. See
CDSA_intro(3). CSSMERR_CSSM_SCOPE_NOT_SUPPORTED CSSMERR_CSSM_PVC_ALREADY_CONFIGURED
CSSMERR_CSSM_INVALID_PVC
Books
Intel CDSA Application Developer's Guide (see
CDSA_intro(3))
Reference Pages [Toc] [Back]
CSSM_Init(3)
[ Back ] | 