NAME
CSSM_Introduce — Identify an executable module (CDSA)
SYNOPSIS
# include <cssm.h>
CSSM_RETURN CSSMAPI CSSM_Introduce
(const CSSM_GUID *ModuleID,
CSSM_KEY_HIERARCHY KeyHierarchy) |
LIBRARY
Common Security Services Manager library (cdsa$incssm300_shr.exe)
PARAMETERS
| ModuleID (input) | | The CSSM_GUID of the calling library or other library
that might call CDSA interfaces. The GUID is used to locate the
signed manifest credentials of the named module to calculate module
integrity information. |
| KeyHierarchy (input) |
| | | 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 executable
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
hierarchy is specified, the set of export privileges contained in
the manifest 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 represent an error condition.
ERRORS
Errors are described in the CDSA Technical Standard.
CSSMERR_CSSM_INVALID_KEY_HIERARCHY
CSSMERR_CSSM_LIB_REF_NOT_FOUND |
SEE ALSO
Intel CDSA Application Developer's Guide
