NAME    [Toc]    [Back]

       CSSM_Introduce - Identify an executable module (CDSA)

SYNOPSIS    [Toc]    [Back]

       # include <cdsa/cssm.h>

       CSSM_RETURN  CSSMAPI CSSM_Introduce (const CSSM_GUID *ModuleID,
 CSSM_KEY_HIERARCHY KeyHierarchy)

LIBRARY    [Toc]    [Back]

       Common Security Services Manager library (libcssm.so)

PARAMETERS    [Toc]    [Back]

       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.  The CSSM_KEY_HIERARCHY
       option directing CSSM what embedded key to use when  verifying
 integrity of the named module.

DESCRIPTION    [Toc]    [Back]

       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    [Toc]    [Back]

       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    [Toc]    [Back]

       Errors are described in the CDSA technical standard.   See
       CDSA_intro(3).    CSSMERR_CSSM_INVALID_KEY_HIERARCHY  CSSMERR_CSSM_LIB_REF_NOT_FOUND

SEE ALSO    [Toc]    [Back]

       Intel   CDSA   Application    Developer's    Guide    (see
       CDSA_intro(3))



                                                CSSM_Introduce(3)