NAME
CSSM_ModuleAttach — Attach and verify a service provider module (CDSA)
SYNOPSIS
# include <cssm.h>
CSSM_RETURN CSSMAPI CSSM_ModuleAttach
(const CSSM_GUID *ModuleGuid,
const CSSM_VERSION *Version,
const CSSM_API_MEMORY_FUNCS *MemoryFuncs,
uint32 SubserviceID,
CSSM_SERVICE_TYPE SubServiceType,
CSSM_ATTACH_FLAGS AttachFlags,
CSSM_KEY_HIERARCHY KeyHierarchy,
CSSM_FUNC_NAME_ADDR *FunctionTable,
uint32 NumFunctionTable,
const void *Reserved,
CSSM_MODULE_HANDLE_PTR NewModuleHandle) |
LIBRARY
Common Security Services Manager library (cdsa$incssm300_shr.exe)
PARAMETERS
| ModuleGuid (input) |
| | | A pointer to the CSSM_GUID structure containing
the global unique identifier for the CSP module. |
| Version (input) | | The major and minor version number of CDSA that
the application is compatible with. |
| MemoryFuncs (input) |
| | | A structure containing pointers to the memory routines. |
| SubserviceID (input) |
| | | A SubServiceID identifying a
particular subservice within the module. Subservice IDs can be obtained
from MDS or gleaned from insertion events reported through the callback function
installed through CSSM_ModuleLoad(). Modules that provide only one service can use zero
as their subservice ID. |
| SubServiceType (input) |
| | | A service mask describing the type of service the
caller is requesting of the service provider module. |
| AttachFlags (input) |
| | | A mask representing the caller's request for session-specific
services. |
| KeyHierarchy (input) |
| | | The CSSM_KEY_HIERARCHY option directing CSSM what
embedded key to use when verifying integrity of the named module. |
| FunctionTable (input/output/optional) |
| | | A table of function-name and API function-pointer
pairs. The caller provides the name of the functions as input. The
corresponding API function pointers are returned on output. The
function table allows dynamic linking of CDSA interfaces, including
interfaces to Elective Module Managers (EMMs), which are transparently
loaded by CSSM during CSSM_ModuleAttach(). |
| NumFunctionTable (input) |
| | | The number of entries in the FunctionTable parameter.
If no FunctionTable is provided, this value must
be zero. |
| Reserved (input) | | This field is reserved for future use. It should
always be set to zero |
| NewModuleHandle (output) |
| | | A new module handle that can be used to interact
with the requested service provider. The value will be set to CSSM_INVALID_HANDLE
if the function fails. |
DESCRIPTION
This function attaches the service provider module and verifies
that the version of the module expected by the application is compatible
with the version on the system. The module can implement subservices
(described in your service provider's documentation). The caller
can specify a specific subservice provided by the module.
If the subservice is supported as part of the CSSM framework
as well as by an EMM, ModuleAttach attaches the
Service Provider to the CSSM framework. If the subservice is supported
only by an EMM, ModuleAttach loads the appropriate
EMM. The service provider is given an indication of whether it is
being attached to the CSSM framework or an EMM.
The caller can provide a function table containing function
names for the desired services. On output each function name is
matched with an API function pointer. The caller can use the pointers
to invoke service module operations through CSSM.
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_ADDIN_FUNCTION_TABLE
CSSMERR_CSSM_EMM_AUTHENTICATE_FAILED
CSSMERR_CSSM_ADDIN_AUTHENTICATE_FAILED
CSSMERR_CSSM_INVALID_SERVICE_MASK
CSSMERR_CSSM_MODULE_NOT_LOADED
CSSMERR_CSSM_INVALID_SUBSERVICEID
CSSMERR_CSSM_INVALID_KEY_HIERARCHY
CSSMERR_CSSM_INVALID_GUID |
SEE ALSO
Books
Intel CDSA Application Developer's Guide
Online Help
Functions: CSSM_ModuleDetach
