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 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.