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 ALSO
Books
Intel CDSA Application Developer's Guide
Online Help
Functions: CSSM_SPI_ModuleDetach, CSSM_SPI_ModuleLoad
