CSSM Upcalls for Service Provider Modules

Four upcall functions not included in this section are malloc, free, calloc, and realloc. CSSM provides these memory management functions so that service provider modules can use the application's memory to exchange data.

NAME

cssm_CcToHandle

SYNOPSIS

CSSM_RETURN CSSMAPI cssm_CcToHandle
    (CSSM_CC_HANDLE Cc,
    CSSM_MODULE_HANDLE_PTR ModuleHandle)

DESCRIPTION

This function returns the module attach handle identifying the service module that is managing the specified cryptographic context.

The entry point to this function is provided to a service module in a table of upcall functions passed to the service provider during module attach processing.

If the PVC checking for service providers is on, the service provider has to introduce itself before calling this function.

PARAMETERS

Cc (input)

A handle identifying a cryptographic context.

ModuleHandle (output)

A service provider's module attach handle. This value will be set to CSSM_INVALID_HANDLE if the function fails.

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

See the General Error Codes and Common Error Codes and Values.

NAME

cssm_GetModuleInfo

SYNOPSIS

CSSM_RETURN CSSMAPI cssm_GetModuleInfo
    (CSSM_MODULE_HANDLE Module,
    CSSM_GUID_PTR Guid, 
    CSSM_VERSION_PTR Version, 
    uint32 *SubServiceId, 
    CSSM_SERVICE_TYPE *SubServiceType, 
    CSSM_ATTACH_FLAGS *AttachFlags,
    CSSM_KEY_HIERARCHY *KeyHierarchy, 
    CSSM_API_MEMORY_FUNCS_PTR AttachedMemFuncs,
    CSSM_FUNC_NAME_ADDR_PTR FunctionTable, 
    uint32 NumFunctionTable)

DESCRIPTION

This function returns the state information associated with the module handle. The information returned by this function is that set by the call to CSSM_ModuleAttach(). The entry point to this function is provided to a service module in a table of upcall functions passed to the service provider during module attach processing.

If the PVC checking for service providers is on, the service provider has to introduce itself before calling this function.

PARAMETERS

Module (input)

The handle to a service provider module.

Guid (output)

A CSSM_GUID associated with the module handle.

Version (output)

The version number set on ModuleAttach.

SubServiceId (output)

The slot number of the reader to which the module is attached.

SubServiceType (output)

A CSSM_SERVICE_TYPE value identifying the class of security service

AttachFlags (output)

This parameter provides the caller with session specific information associated with the module handle.

KeyHierarchy (output)

The key hierarchy supplied when the module was attached.

AttachedMemFuncs (output)

The memory functions supplied when the module was attached.

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, which are transparently loaded by CSSM during CSSM_ModuleAttach(). The caller of this function should allocate the memory for the number of slots required.

NumFunctionTable (input)

The number of entries in the FunctionTable parameter. If no FunctionTable is provided, this value must be zero.

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

See General Error Codes and Common Error Codes and Values.