Add-In Module Interface Functions

NAME

CSSM_SPI_ModuleLoad

SYNOPSIS

CSSM_RETURN CSSMSPI CSSM_SPI_ModuleLoad
    (const CSSM_GUID *CssmGuid, 
    const CSSM_GUID *ModuleGuid, 
    CSSM_SPI_ModuleEventHandler CssmNotifyCallback,
    void* CssmNotifyCallbackCtx)

DESCRIPTION

This function completes the module initialization process between CSSM and the add-in service module. Before invoking this function, CSSM verifies the add-in service module's manifest credentials. If the credentials verify this module is loaded (physically if required) and CSSM_SPI_ModuleLoad() is invoked.

The CssmGuid identifies the caller and should be used by the module to locate the caller's signed manifest credentials and to complete integrity verification and secure linkage checks on the caller. The ModuleGuid identifies the invoked module and should be used by the module to locate its credentials and to complete an integrity self-check.

The CssmNotifyCallback and CssmNotifyCallbackCtx defines a callback and callback context respectively. The module must retain this information for later use. The module should use the callback to notify CSSM of module events of type CSSM_MODULE_EVENT in any ongoing, attached sessions.

PARAMETERS

CssmGuid (input)

The CSSM_GUID of the caller. Used to locate the caller's signed manifest credentials.

ModuleGuid (input)

The CSSM_GUID of the invoked service provider module. Used to locate the module's signed manifest credentials.

CssmNotifyCallback (input)

A function pointer for the CSSM event handler that manages events of type CSSM_MODULE_EVENT.

CssmNotifyCallbackCtx (input)

The context to be returned to CSSM as input on each callback to the event handler defined by CssmNotifyCallback.

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

Refer to the error codes defined in Part 2.

SEE ALSO

CSSM_SPI_ModuleUnload()
CSSM_SPI_ModuleAttach()

NAME

CSSM_SPI_ModuleUnload

SYNOPSIS

CSSM_RETURN CSSMSPI CSSM_SPI_ModuleUnload
    (const CSSM_GUID *CssmGuid, 
    const CSSM_GUID *ModuleGuid, 
    CSSM_SPI_ModuleEventHandler CssmNotifyCallback,
    void* CssmNotifyCallbackCtx)

DESCRIPTION

This function disables events and de-registers the CSSM event-notification function. The add-in service module may perform cleanup operations, reversing the initialization performed in CSSM_SPI_ModuleLoad().

PARAMETERS

CssmGuid (input)

The CSSM_GUID of the caller.

ModuleGuid (input)

The CSSM_GUID of the invoked service provider module.

CssmNotifyCallback (input)

A function pointer for the CSSM event handler that manages events of type CSSM_MODULE_EVENT.

CssmNotifyCallbackCtx (input)

The context to be returned to CSSM as input on each callback to the event handler defined by CssmNotifyCallback.

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

Refer to the error codes defined in Part 2.

SEE ALSO

CSSM_SPI_ModuleLoad()
CSSM_SPI_ModuleDetach()

NAME

CSSM_SPI_ModuleAttach

SYNOPSIS

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)

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 who invoked CSSM through the function CSSM_ModuleAttach(). 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. CallerGuid 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, 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 Caller. CSSM uses this function table to dispatch requests on for the attach session created by this function. Each attach session has its own function table.

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 (noutput)

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 flag directing CSSM which embedded key(s) 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 by the application invoking 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.

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

Refer to the error codes in Part 2.

SEE ALSO

CSSM_SPI_ModuleDetach()
CSSM_SPI_ModuleLoad()

NAME

CSSM_SPI_ModuleDetach

SYNOPSIS

CSSM_RETURN CSSMSPI CSSM_SPI_ModuleDetach
    (CSSM_MODULE_HANDLE ModuleHandle)

DESCRIPTION

This function is invoked by CSSM once for each invocation of CSSM_ModuleDetach() specifying the attach-session identified by ModuleHandle. The function entry point for CSSM_SPI_ModuleDetach is included in the module function table CSSM_MODULE_FUNCS returned to CSSM as output of a successful CSSM_SPI_ModuleAttach.

The service module must perform all cleanup operations associated with the specified attach handle.

PARAMETERS

ModuleHandle (input)

The CSSM_HANDLE value associated with the attach session being terminated by this function.

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

Refer to the error codes in Part 2.

SEE ALSO

CSSM_SPI_ModuleAttach()
CSSM_SPI_ModuleUnload()