CSSM_Introduce

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.  See CDSA.

       CSSMERR_CSSM_INVALID_KEY_HIERARCHY
       CSSMERR_CSSM_LIB_REF_NOT_FOUND

SEE ALSO
  Intel CDSA Application Developer's Guide (see CDSA)