CSSM_Introduce(3)CSSM_Introduce(3)NAMECSSM_Introduce - Identify an executable module (CDSA)
SYNOPSIS
# include <cdsa/cssm.h>
CSSM_RETURN CSSMAPI CSSM_Introduce (const CSSM_GUID *ModuleID,
CSSM_KEY_HIERARCHY KeyHierarchy)
LIBRARY
Common Security Services Manager library (libcssm.so)
PARAMETERS
The CSSM_GUID of the calling library or other library that might call
CDSA interfaces. The GUID is used to locate the signed manifest creden‐
tials of the named module to calculate module integrity information.
The CSSM_KEY_HIERARCHY option directing CSSM what embedded key to use
when verifying integrity of the named module.
DESCRIPTION
The CSSM_Introduce() function identifies a dynamically loadable exe‐
cutable module (for example, DLL) to the CSSM framework. CSSM uses the
ModuleID information to locate the signed manifest and library on the
host platform. The Module Directory Service (MDS) should be used to
obtain the information. CSSM performs an integrity cross-check on the
module identified by ModuleID and caches the result in an internal
structure. The integrity cross-check uses the KeyHierarchy information
to determine which classes of embedded public keys must serve as
anchors when doing certificate path validation. If the export key hier‐
archy is specified, the set of export privileges contained in the mani‐
fest are retrieved from the manifest and saved with the integrity state
information in the cache. Privileges granted to a module are accepted
only if the manifest sections containing the privilege set have been
signed by a principal in the export key hierarchy class and that hash
of the module binary is part of the hash of the privilege attributes.
The CSSM_Introduce() can be called at any time after CSSM_Init(), by
any module, on behalf of any module.
Once a module is introduced into CSSM the load location of the module
must not change. If the load location changes then the module must be
reintroduced. Once introduced, the module load location, integrity,
and privilege information is held until CSSM_Terminate() is called or
the process terminates. Initialization of internal data structures
maintaining the table of introductions is performed when CSSM_Init() is
called.
If CSSM_Introduce() is called on behalf of another module, then the
caller needs to make sure that the other module is loaded into the
process address space. If the library is already loaded into process
address space, but a reference to the library cannot be obtained, a
different error is returned (CSSMERR_CSSM_LIB_REF_NOT_FOUND).
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_INVALID_KEY_HIERARCHY CSS‐
MERR_CSSM_LIB_REF_NOT_FOUND
SEE ALSO
Intel CDSA Application Developer's Guide (see CDSA_intro(3))
CSSM_Introduce(3)
