CSSM_SPI_ModuleAttach

If both a Table of Contents and Search form are not displayed in separate frames along with this one, you may wish to redisplay this book in a frameset, beginning with the first page.

HP Open Source Security for OpenVMS Volume 1:...

API Functions

CSSM_SetPrivilege

CSSM_SPI_ModuleDetach

CSSM_SPI_ModuleAttach

Library
Description
Errors

Parameters
Return Value
See Also

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 requiredlevel of system services and features. The service module must determinewhether its services are compatible with the required version.
`SubserviceId` (input)
		The identifier for the requested subservice withinthis module. If only one service is provided by the module, then `subserviceId` canbe zero.
`SubServiceType` (output)
		A CSSM_SERVICE_MASK indicating the type of servicesprovided by the service module and the ordering of the functiontable returned in the output parameter `FuncTbl`.
`AttachFlags` (input)
		A mask representing the caller's request for session-specificservices.
`ModuleHandle` (input)
		The CSSM_HANDLE value assigned by CSSM and associatedwith the attach session being created by this function.
`KeyHierarchy` (input)
		The CSSM_KEY_HIERARCHY option directing CSSM whichembedded key or keys to use when verifying integrity of the namedmodules.
`CssmGuid` (input)
		The CSSM_GUID of the CSSM invoking this function.
`ModuleManagerGuid` (input)
		The CSSM_GUID of the module that will route callsto 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 mustuse to obtain selected CSSM services and to manage application memory.The memory management functions are provided when the applicationinvokes `CSSM_ModuleAttach()`. CSSM forwards these function pointers with CSSM servicefunction pointers to the module.
`FuncTbl` (output)
		A CSSM_MODULE_FUNCS table containing pointers tothe service module functions the caller can use. CSSM uses thistable to proxy calls from an application caller to the add-in servicemodule.

DESCRIPTION

This function is invoked by CSSM once for each invocationof CSSM_ModuleAttach(), specifying the module identified by ModuleGuid.Four entities are stakeholders in this function and each is identifiedby 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 isidentified by `CssmGuid`.
`ModuleManagerGuid`
		The module that will be routing calls to the serviceprovider. This value will be the same as `CssmGuid` ifCSSM 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 checkof CSSM. CssmGuid can be used to locate CSSM'ssigned manifest credentials. The service provider can require anintegrity check of the Caller. The CallerGuid parametercan be used to locate the Caller's signed manifest credentials.The KeyHierarchy flag identifies the class ofembedded public keys CSSM will use to check the integrity of theservice provider. If the manifest for the target module does notencounter an embedded key for all the key classes in KeyHierarchy, theintegrity cross-check fails.

The service module must verify compatibility with the systemversion level specified by Version. If the versionis not compatible, then this function fails. The service moduleshould perform all initializations required to support the new attachedsession and should return a function table for the SPI entry pointsthat can be invoked by CSSM in response to API invocations by CallerGuid.CSSM uses this function table to dispatch requests for the attachsession created by this function. Each attach session has its ownfunction table.

RETURN VALUE

A CSSM_RETURN value indicating success or specifying a particularerror condition. The value CSSM_OK indicates success. All othervalues represent an error condition.

ERRORS

Errors are described in the CDSA Technical Standard.