Previous section.

Common Security: CDSA and CSSM, Version 2 (with corrigenda)
Copyright © 2000 The Open Group

Elective Module Manager Operations

Data Structures

CSSM_STATE_FUNCS

This structure is used by CSSM to provide function pointers to an elective module manager. An EMM uses these pointers to access services provided by the CSSM. 

#define CSSM_HINT_CALLBACK (1)
typedef struct cssm_state_funcs {
    CSSM_RETURN (CSSMAPI *cssm_GetAttachFunctions)
        (CSSM_MODULE_HANDLE hAddIn,
        CSSM_SERVICE_MASK AddinType,
        void **SPFunctions,
        CSSM_GUID_PTR Guid);
    CSSM_RETURN (CSSMAPI *cssm_ReleaseAttachFunctions)
        (CSSM_MODULE_HANDLE hAddIn);
    CSSM_RETURN (CSSMAPI * cssm_GetAppMemoryFunctions)
        (CSSM_MODULE_HANDLE hAddIn,
        CSSM_UPCALLS_PTR UpcallTable);
    CSSM_RETURN (CSSMAPI * cssm_IsFuncCallValid)
        (CSSM_MODULE_HANDLE hAddin,
        CSSM_PROC_ADDR SrcAddress, 
        CSSM_PROC_ADDR DestAddress,
        CSSM_PRIVILEGE InPriv,
        CSSM_PRIVILEGE *OutPriv,
        CSSM_BITMASK Hints,
        CSSM_BOOL* IsOK);
    CSSM_RETURN (CSSMAPI * cssm_DeregisterManagerServices)
        (const CSSM_GUID *GUID);
    CSSM_RETURN (CSSMAPI * cssm_DeliverModuleManagerEvent)
        (const CSSM_MANAGER_EVENT_NOTIFICATION *EventDescription); 
} CSSM_STATE_FUNCS, *CSSM_STATE_FUNCS_PTR;

CSSM_MANAGER_EVENT_TYPES

This list defines a minimal set of event types used by communicating module managers. It is assumed that module managers may define their own protocols for interacting with other managers. Request and Reply messages are generic message categories to support simple message exchange protocols. 

typedef uint32 CSSM_MANAGER_EVENT_TYPES;

#define CSSM_MANAGER_SERVICE_REQUEST 1
#define CSSM_MANAGER_REPLY 2

CSSM_MANAGER_EVENT_NOTIFICATION

This structure contains all the information about a notification event between two module managers. 

typedef struct cssm_manager_event_notification {
    CSSM_SERVICE_MASK DestinationModuleManagerType;
    CSSM_SERVICE_MASK SourceModuleManagerType;
    CSSM_MANAGER_EVENT_TYPES Event;
    uint32 EventId;
    CSSM_DATA EventData;
    } CSSM_MANAGER_EVENT_NOTIFICATION,
*CSSM_MANAGER_EVENT_NOTIFICATION_PTR;
Definition

DestinationModuleManagerType

A service mask identifying the module manager to receive the event notification.

SourceModuleManagerType

A service mask identifying the module manager that initiated the event notification.

Event

An identifier specifying the type of event that has taken place or will take place.

EventId

A unique identifier associated with this event notification. It must be used in any reply notification that results from this event notification.

EventData

Arbitrary data (required or information) for this event.

CSSM_MANAGER_REGISTRATION_INFO

This structure defines the function prototypes that an elective module manager must implement to be dynamically loaded by CSSM. 

typedef struct cssm_manager_registration_info {
/* loading, unloading, dispatch table, and event notification */
    CSSM_RETURN (CSSMAPI *Initialize) 
        (uint32 VerMajor,
        uint32 VerMinor);
    CSSM_RETURN (CSSMAPI *Terminate) (void);
    CSSM_RETURN (CSSMAPI *RegisterDispatchTable)
        (CSSM_STATE_FUNCS_PTR CssmStateCallTable);
    CSSM_RETURN (CSSMAPI *DeregisterDispatchTable) (void);
    CSSM_RETURN (CSSMAPI *EventNotifyManager)
        (const CSSM_MANAGER_EVENT_NOTIFICATION *EventDescription);
    CSSM_RETURN (CSSMAPI *RefreshFunctionTable)
        (CSSM_FUNC_NAME_ADDR_PTR FuncNameAddrPtr, 
        uint32 NumOfFuncNameAddr);
} CSSM_MANAGER_REGISTRATION_INFO, *CSSM_MANAGER_REGISTRATION_INFO_PTR;
Definition

Initialize

Function invoked by CSSM to initialize an elective module manager.

Terminate

Function invoked by CSSM before unloading an elective module manager.

RegisterDispatchTable

Function invoked by CSSM to pass a CSSM function table to an elective module manager. The elective module manager must use these functions to obtain information about the service module and calling application, and to initiate state changes in the application and service module session.

DeregisterDispatchTable

Function invoked by CSSM to inform an elective module manager that an application and add-in module session is no longer active and the CSSM function table for that add-in module should not be used.

EventNotifyManager

Function invoked by CSSM forwarding an event notification from one module manager to another target module manager.

RefreshFunctionTable

Function invoked by CSSM to obtain an initialized API function table corresponding to the service interfaces implemented by a particular EMM service provider module. CSSM forwards this function table to the application that invoked the ModuleAttach operation.

CSSM_HINT_xxx Parameter

These are hints that help CSSM to look for the state information about integrity and privilege. 

#define CSSM_HINT_NONE (0)
#define CSSM_HINT_ADDRESS_APP (1)
#define CSSM_HINT_ADDRESS_SP (2)

Elective Module Manager Functions

The man-page definitions for Elective Module Manager functions, accessible only to CSSM, are presented in this section.
Previous section.

NAME

Initialize

SYNOPSIS


CSSM_RETURN CSSMAPI Initialize
    (uint32 VerMajor,
    uint32 VerMinor)

DESCRIPTION

This function checks whether the current version of the module is compatible with the CSSM version specified as input and performs any module-manager-specific setup activities.

PARAMETERS

VerMajor (input)

The major version number of the CSSM that is invoking this module manager.

VerMinor (input)

The minor version number of the CSSM that is invoking this module manager.

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 also General Error Codes and Common Error Codes and Values.

CSSMERR_CSSM_MODULE_MANAGER_INITIALIZE_FAIL.

SEE ALSO

Terminate()
Previous section.

NAME

Terminate

SYNOPSIS


CSSM_RETURN CSSMAPI Terminate
    (void)

DESCRIPTION

This function performs any module-manager-specific cleanup activities in preparation for unloading of the elective module manager.

PARAMETERS

None.

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 also the general error codes and common error code and values section.

CSSMERR_CSSM_EMM_AUTHENTICATE_FAILED.

SEE ALSO

Initialize()
Previous section.

NAME

ModuleManagerAuthenticate

SYNOPSIS


CSSM_RETURN CSSMAPI ModuleManagerAuthenticate
    (CSSM_KEY_HIERARCHY KeyHierarchy,
    const CSSM_GUID *CssmGuid, 
    const CSSM_GUID *AppGuid,
    CSSM_MANAGER_REGISTRATION_INFO_PTR FunctionTable)

DESCRIPTION

This function should perform the elective module manager's half of the bilateral authentication procedure with CSSM. The CssmGuid is used to locate the CSSM's credentials to be verified. The credentials are a zipped, signed manifest.

The KeyHierarchy indicates which public key should be used as the root when checking the integrity of the module manager. The AppGuid is used to locate the application's signed manifest credentials. The elective module manager must check the application's credentials to verify the application's authorization. If no privileges are requested, then the application is not required to provide a GUID nor a set of signed manifest credentials.

Upon successful completion, the elective module manager returns its function table to the calling CSSM. The EMM function table contains the set of EMM entry points that CSSM uses to notify the module manager of significant events such as module attach and module detach requests issued by an application, and event notifications issued by other module managers.

This function symbol must be exported by the elective module manager, so CSSM can invoke this function upon completion of the loading process.

This function is the first module manager interface invoked by CSSM after loading and invoking the main entry point. In particular, the elective module manager's initialize function is invoked by CSSM after this function has successfully completed execution.

PARAMETERS

KeyHierarchy (input)

The CSSM_KEY_HIERARCHY flag indicating which embedded key(s) CSSM should use when verifying the integrity of the module manager.

CssmGuid (input)

A CSSM_GUID value identifying the calling CSSM. The elective module manager can use this value to locate the signed manifest credentials for CSSM.

AppGuid (input/optional)

A CSSM_GUID value identifying the application who invoked the calling CSSM. The elective module manager can use this value to locate the signed manifest credentials for the application.

FunctionTable (output)

A set of function pointers for EMM-defined functions used by CSSM to communicate state changes related to module attach and module detach operations.

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

NAME

RegisterDispatchTable

SYNOPSIS


CSSM_RETURN CSSMAPI RegisterDispatchTable
    (CSSM_STATE_FUNCS_PTR CssmStateCallTable)

DESCRIPTION

This EMM-defined function is invoked by CSSM once for each CSSM_ModuleAttach() operation requesting a service provider of the type managed by the EMM. CSSM uses this function to provide the EMM with a set of CSSM function pointers. The EMM invokes these functions at anytime during the life cycle of the attach-session to obtain information about the current state and to modify the current state of the attach session.

When the attach-session is terminated, CSSM informs the module manager by invoking the EMM function DeregisterDispatchTable(). The corresponding set of CSSM state functions become invalid at that time.

PARAMETERS

CssmStateCallTable (input)

A table of function pointers for the set of CSSM-defined functions the elective module manager can use to query and control the state of an attach-session between an application and a service provider managed by the module manager.

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 code and values section.

SEE ALSO

DeregisterDispatchTable()
Previous section.

NAME

DeregisterDispatchTable

SYNOPSIS


CSSM_RETURN (CSSMAPI DeregisterDispatchTable) 
    (void)

DESCRIPTION

This EMM-defined function is invoked by CSSM once for each CSSM_ModuleDetach() operation issued against a service provider of the type managed by the EMM. CSSM uses this function to inform the EMM that the set of CSSM function pointers provided to the EMM when the session was attached are no longer valid.

PARAMETERS

None.

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 code and values section.

SEE ALSO

RegisterDispatchTable()
Previous section.

NAME

EventNotifyManager

SYNOPSIS


CSSM_RETURN CSSMAPI EventNotifyManager
   (const CSSM_MANAGER_EVENT_NOTIFICATION *EventDescription)

DESCRIPTION

This function receives an event notification from another module manager. The source manager is identified by its service mask. The specified event type is interpreted by the received and the appropriate actions must be taken in response. EventId and EventData are optional. The EventId is specified by the source module manager when a reply is expected. The destination module manager must use this identifier when replying to the event notification. The EventData is additional data or descriptive information provided to the destination manager.

PARAMETERS

EventDescription

A structure containing the following fields:

DestinationModuleManagerType (input)

The unique service mask identifying the destination module manager.

SourceModuleManagerType (input)

The unique service mask identifying the source module manager.

Event (input)

An identifier indicating the event that has or will take place.

EventId (input/optional)

A unique identifier associated with this event notification. It must be used in any reply notification that results from this event notification.

EventData (input/optional)

Arbitrary data (required or informational) for this event.

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 also the general error codes and common error codes and values section.

CSSMERR_CSSM_MODULE_MANAGER_NOT_FOUND.

Previous section.

NAME

RefreshFunctionTable

SYNOPSIS


CSSM_RETURN CSSMAPI RefreshFunctionTable 
    (CSSM_FUNC_NAME_ADDR_PTR FuncNameAddrPtr,
    uint32 NumOfFuncNameAddr)

DESCRIPTION

CSSM invokes this function to obtain the EMM-defined API function. The table is returned to CSSM in FuncNameAddrPtr and CSSM returns the table to the application. The application uses this table to invoke the security services defined by the EMM's service category. CSSM must obtain and forward the API table to the application on behalf of the EMM because the application is not aware of the optional nature of the EMM. Applications use CSSM to obtain the API function table for basic module managers and elective module managers, providing a uniform application programming model.

If the Elective Module Manager needs the service provider's SPI function table in order to initialize the API function table, the EMM can obtain the SPI function table by invoking the CSSM-provided service cssm_GetAttachFunctions(). The service module may implement only a subset of the defined functions and the EMM may wish to manage these functions in a particular manner through the API mapping. The elective module manager uses the SPI function table to dispatch application calls for service to attached modules.

Multiple applications and multiple instances of a service module can be concurrently active. The single elective module manager is responsible for managing all of these concurrent sessions. After completing initialization of the API function table, the EMM returns the refreshed API table to CSSM.

PARAMETERS

FuncNameAddrPtr (input/output)

A pointer to a table mapping function names to EMM-defined APIs.

NumOfFuncNameAddr (input)

The number of entries in the table referenced by FuncNameAddrPtr.

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 feneral and common error codes and error values section.

CSSM Service Functions used by an EMM

The man-page definitions for service functions used by an Elective Module Manager are presented in this section.
Previous section.

NAME

cssm_GetAttachFunctions

SYNOPSIS


CSSM_RETURN CSSMAPI cssm_GetAttachFunctions
    (CSSM_MODULE_HANDLE hAddIn,
    CSSM_SERVICE_MASK AddinType,
    void **SPFunctions,
    CSSM_GUID_PTR Guid)

DESCRIPTION

This function returns an SPI function table for the service module identified by the module handle. The module must be of the type specified by the service mask. The SPFunctions parameter contains the returned function table. The elective module manager must use this function table to forward an application's call to the elective APIs to their corresponding SPIs represented in the function table. The returned Guid identifies the service module. It can be used to locate credentials and other information about the service module.

This function sets a lock on the SP functions table. The CSSM service function cssm_ReleaseAttachFunctions() must be used to release the lock.

PARAMETERS

hAddIn (input)

The handle identifying the attach-session whose function table is to be returned by this function.

AddinType (input)

A CSSM_SERVICE_MASK value identifying the type of service module whose function table is to be returned by this function.

SPFunctions (output)

A pointer to the service module function table, which CSSM acquired from the service module during module-attach processing. The module manager should use this table to forward application invocation of the elective APIs to their corresponding SPIs. The memory pointed to by the function pointers should not be freed by the EMM.

Guid (output)

A CSSM_GUID value identifying the service module whose function table is to be returned 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

See general and common error codes and error values section.
Previous section.

NAME

cssm_ReleaseAttachFunctions

SYNOPSIS


CSSM_RETURN CSSMAPI cssm_ReleaseAttachFunctions
    (CSSM_MODULE_HANDLE hAddIn)

DESCRIPTION

This function releases the lock on the SP function table for the service module identified by the module handle. The SPI function table was obtained by the elective module manager through the cssm_GetAttachFunctions() operation.

PARMETERS

hAddIn (input)

The handle identifying the attach-session whose function table is to be released 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

See also the general error codes and common error code and values section
Previous section.

NAME

cssm_GetAppMemoryFunctions

SYNOPSIS


CSSM_RETURN CSSMAPI cssm_GetAppMemoryFunctions
    (CSSM_MODULE_HANDLE hAddIn,
    CSSM_UPCALLS_PTR UpcallTable)

DESCRIPTION

This function gets a function table containing sets of service functions. Among these service functions are four application-provided memory management functions. The elective module manager can use these functions to manage memory on behalf of the application. The returned function table is specific to the attach-session identified by the module handle.

PARAMETERS

hAddIn (input)

The handle identifying the attach-session whose memory management function table is returned by this function.

UpcallTable (output)

The table containing sets of service functions among them a set of four memory management functions provided by the application that initiated the attach-session identified by hAddIn.

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 also the general error codes and common error code and values section
Previous section.

NAME

cssm_IsFuncCallValid

SYNOPSIS


CSSM_RETURN CSSMAPI cssm_IsFuncCallValid
    (CSSM_MODULE_HANDLE hAddin,
    CSSM_PROC_ADDR SrcAddress, /* application */
    CSSM_PROC_ADDR DestAddress,
    CSSM_PRIVILEGE InPriv,
    CSSM_PRIVILEGE *OutPriv,
    CSSM_BITMASK Hints,
    CSSM_BOOL * IsOK)

DESCRIPTION

This function checks secure linkage between an application and a service module. Based on address scope of the application and the service module associated with the attach handle, CSSM determines whether the SrcAddress is within an associated application and DestAddress is within the associated service module. The scope of the application and the service module is determined by their respective signed manifest credentials, which attest to the integrity of each entity.

This function uses the input privilege value InPriv to compare against the privilege range associated with the ranges for SrcAddress and DestAddres. The privilege check is performed when the InPriv privilege value is non-NULL. If the EMM wants the global privilege value to be checked, InPriv is zero and OutPriv is non-NULL. CSSM will return the privilege value in OutPriv. If integrity only checks are to be performed, InPriv is zero and OutPriv is NULL.

Another parameter called Hints is used to help CSSM efficiently perform the integrity and privilege verification operations. Hints helps CSSM know where to look to find the desired state information. In the regular case, CSSM will look for SrcAddress in the CallerList and DestAddress in the AttachList. For callback functions, the SrcAddress and DestAddress are likely to be in AttachList.

PARAMETERS

hAddIn (input)

The handle identifying the attach-session whose caller and callee scope is being tested by this function.

SrcAddress (input/optional)

An address to be tested for containment within the application that requested and created the attach-session identified by the module handle.

DestAddress (input/optional)

An address within a service module. The destination address must be valid for the service provider associated with the attach-session identified by the module handle.

InPriv (input)

The privilege value to be checked. Privilege checks apply to both SrcAddress and DestAddress.

OutPriv (output)

If non-NULL, the global privilege will be checked and returned in OutPriv.

Hints (input)

A flag providing search hints.

IsOK (output)

CSSM_TRUE if success, CSSM_FALSE if fail.

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 code and values section.
Previous section.

NAME

cssm_DeregisterManagerServices

SYNOPSIS


void CSSMAPI cssm_DeregisterManagerServices
    (const CSSM_GUID *Guid)

DESCRIPTION

This function is used by an elective module manager to de-register its function table with CSSM core services prior to termination. This function is invoked by an elective module manager only when exiting due to an error condition detected by the EMM. This allows CSSM to clean up any state information associated with the exiting EMM.

PARAMETERS

GUID (input)

A pointer to the CSSM_GUID structure containing the global unique identifier for this 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

See the general error codes and common error code and values section.

Contents Next section Index