CSSM_SPI_ModuleAttach

NAME
  CSSM_SPI_ModuleAttach - Attach a service provider module(CDSA)

SYNOPSIS
  # include <cssm.h>

       CSSM_RETURN CSSMSPI CSSM_SPI_ModuleAttach
       (const CSSM_GUID *ModuleGuid,
       const CSSM_VERSION *Version,
       uint32 SubserviceID,
       CSSM_SERVICE_TYPE SubServiceType,
       CSSM_ATTACH_FLAGS AttachFlags,
       CSSM_MODULE_HANDLE ModuleHandle,
       CSSM_KEY_HIERARCHY KeyHierarchy,
       const CSSM_GUID *CssmGuid,
       const CSSM_GUID *ModuleManagerGuid,
       const CSSM_GUID *CallerGuid,
       const CSSM_UPCALLS *Upcalls,
       CSSM_MODULE_FUNCS_PTR *FuncTbl)

LIBRARY
  Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE)

PARAMETERS
  ModuleGuid (input)
          The CSSM_GUID of the invoked service provider module.

  Version (input)
          The major and minor version number of the required level of
          system services and features. The service module must
          determine whether its services are compatible with the
          required version.

  SubserviceId (input)
          The identifier for the requested subservice within this
          module.  If only one service is provided by the module,
          then subserviceId can be zero.

  SubServiceType (output)
          A CSSM_SERVICE_MASK indicating the type of services provided
          by the service module and the ordering of the function table
          returned in the output parameter FuncTbl.

  AttachFlags (input)
          A mask representing the caller's request for session-specific
          services.

  ModuleHandle (input)
          The CSSM_HANDLE value assigned by CSSM and associated with the
          attach session being created by this function.

  KeyHierarchy (input)
          The CSSM_KEY_HIERARCHY option directing CSSM which embedded key
          or keys to use when verifying integrity of the named modules.

  CssmGuid (input)
          The CSSM_GUID of the CSSM invoking this function.

  ModuleManagerGuid (input)
          The CSSM_GUID of the module that will route calls to the
          service provider.

  CallerGuid (input)
          The CSSM_GUID of the caller who invoked CSSM_ModuleAttach(),
          which resulted in CSSM invoking this function.

  Upcalls (input)
          A set of function pointers the service module must use to
          obtain selected CSSM services and to manage application
          memory. The memory management functions are provided when the
          application invokes CSSM_ModuleAttach(). CSSM forwards these
          function pointers with CSSM service function pointers to the
          module.

  FuncTbl (output)
          A CSSM_MODULE_FUNCS table containing pointers to the service
          module functions the caller can use. CSSM uses this table to
          proxy calls from an application caller to the add-in service
          module.

DESCRIPTION
  This function is invoked by CSSM once for each invocation of
  CSSM_ModuleAttach(), specifying the module identified by ModuleGuid.
  Four entities are stakeholders in this function and each is identified
  by a CSSM_GUID value:

  Service Module
          The executing service provider performing the
          CSSM_SPI_ModuleAttach() operation. The module is identified by
          ModuleGuid.

  CSSM    The CSSM that invoked the service module.  CSSM is identified
          by CssmGuid.

  ModuleManagerGuid
          The module that will be routing calls to the service provider.
          This value will be the same as CssmGuid if CSSM is managing
          the calls to this service provider.

  Caller  The entity that invoked CSSM through the CSSM_ModuleAttach()
          function. The caller is identified by CallerGuid.

  The service provider module should perform an integrity check of CSSM.
  CssmGuid can be used to locate CSSM's signed manifest credentials.
  The service provider can require an integrity check of the Caller. The
  CallerGuid parameter can be used to locate the Caller's signed manifest
  credentials. The KeyHierarchy flag identifies the class of embedded
  public keys CSSM will use to check the integrity of the service
  provider. If the manifest for the target module does not encounter an
  embedded key for all the key classes in KeyHierarchy, the integrity
  cross-check fails.

  The service module must verify compatibility with the system version
  level specified by Version. If the version is not compatible, then this
  function fails. The service module should perform all initializations
  required to support the new attached session and should return a
  function table for the SPI entry points that can be invoked by CSSM in
  response to API invocations by CallerGuid. CSSM uses this function
  table to dispatch requests for the attach session created by this
  function. Each attach session has its own function table.

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.

SEE ALSO
  Books

  Intel CDSA Application Developer's Guide (see CDSA)

  Other Help Topics

  Functions: CSSM_SPI_ModuleDetach
             CSSM_SPI_ModuleLoad