Common Security: CDSA and CSSM - Elective Module Manager Operations

Common Security: CDSA and CSSM
Copyright © 1997 The Open Group

Elective Module Manager Operations

Data Structures

CSSM_BOOL

This data type is used to indicate a true or false condition.

typedef enum cssm_bool {
        CSSM_TRUE = 1,
        CSSM_FALSE = 0
} CSSM_BOOL

Definition

CSSM_TRUE: Indicates a true result or a true value.
CSSM_FALSE: Indicates a false result or a false value.

CSSM_RETURN

This data type is used to indicate whether a function was successful.

typedef enum cssm_return {
        CSSM_OK = 0,
        CSSM_FAIL = -1
} CSSM_RETURN

Definition

CSSM_OK: Indicates operation was successful.
CSSM_FAIL: Indicates operation was unsuccessful.

CSSM_DATA

The CSSM_DATA structure is used to associate a length, in bytes, with an arbitrary block of contiguous memory. This memory must be allocated and freed using the memory management routines provided by the calling application via CSSM.

typedef struct cssm_data{
    uint32 Length;  /* in bytes */
    uint8 *Data;
} CSSM_DATA, *CSSM_DATA_PTR

Definition

Length: Length of the data buffer in bytes.
Data: Points to the start of an arbitrary length data buffer.

CSSM_GUID

This structure designates a global unique identifier (GUID) that uniquely identifies each add-in module and elective module manager. All GUID values should be computer-generated to guarantee uniqueness (the GUID generator in Microsoft Developer Studio* and the RPC UUIDGEN/uuid_gen program on a number of UNIX* platforms can be used).

typedef struct cssm_guid{
    uint32 Data1;
    uint16 Data2;
    uint16 Data3;
    uint8  Data4[8];
} CSSM_GUID, *CSSM_GUID_PTR

Definition

Data1: Specifies the first eight hexadecimal digits of the GUID.
Data2: Specifies the first group of four hexadecimal digits of the GUID.
Data3: Specifies the second group of four hexadecimal digits of the GUID.
Data4: Specifies an array of eight elements that contains the third and final group of eight hexadecimal digits of the GUID in elements 0 and 1, and the final 12 hexadecimal digits of the GUID in elements 2 through 7.

CSSM_MODULE_HANDLE

A unique identifier for a session between an application and an attached, add-in service provider module.

typedef uint32 CSSM_MODULE_HANDLE

CSSM_SERVICE_MASK

This defines a bit mask of all the basic service types recognized by CSSM. The elective module manager must define a unique service mask for the new type of service it defines.

typedef uint32 CSSM_SERVICE_MASK;

#define CSSM_SERVICE_CSSM  0x1
#define CSSM_SERVICE_CSP   0x2
#define CSSM_SERVICE_DL    0x4
#define CSSM_SERVICE_CL    0x8
#define CSSM_SERVICE_TP    0x10
#define CSSM_SERVICE_LAST  CSSM_SERVICE_Tp

CSSM_EXEMPTION_MASK

The CSSM defines the exemption mask flags listed above. Other elective module managers define flags for their respective exemption categories. It is the responsibility of the elective module manager developer to ensure uniqueness of their defined flag values and to document those values for use by applications.

typedef uint32 CSSM_EXEMPTION_MASK

#define CSSM_EXEMPT_NONE 0x00000001
#define CSSM_EXEMPT_MULTI_ENCRYPT_CHECK 0x00000002
#define CSSM_EXEMPT_ALL 0xFFFFFFFF

CSSM_MODULE_MANAGER_INFO

This structure aggregates a description of the module manager.

typedef struct cssm_module_manager_info {
    CSSM_VERSION Version; /* Module Manager version */
    CSSM_VERSION CompatibleCSSMVersion; /* CSSM version the
                                             manager works with */
    CSSM_GUID_PTR CompatibleInterfaceGUID, /* opt GUID for
                                           compatible CSSM interface */
    CSSM_STRING Description; /* Module Manager description */
    CSSM_STRING Vendor; /* Vendor name */
    CSSM_SERVICE_MASK ServiceType; /* Bit mask of supported services */
    CSSM_EXEMPTION_FLAGS ExemptionFlags; /* Flags for exemption
                                                          categories */
    CSSM_KEY_PTR AppAuthenRootKeys, /* Mgr-specific keys to
                                                   authenticate apps */
    uint32 NumberOfAppAuthenRootKeys,/* Number of Manager-specific
                                                           root keys */
    void *Reserved;
} CSSM_MODULE_MANAGER_INFO, *CSSM_MODULE_MANAGER_INFO_PTR;

Definition

Version: The major and minor version numbers of this module manager.
CompatibleCSSMVersion: The version of CSSM that this module manager was written to.
CompatibleInterfaceGUID: An optional GUID describing the CSSM interface this module was written to.
Description: A text description of this module manager and its functionality.
Vendor: The name and description of the module manager vendor.
ServiceType: A bit mask identifying the types of services available through this module manager.
ExemptionFlags: A bit mask identifying the exemption categories offered by this module manager.
AppAuthenRootKeys: Public root keys defined by the module manager as additional roots for authenticating an application's request for exemptions.
NumberOfAppAuthenRootKeys: The number of public root keys in the AppAuthenRootKeys list.
Reserved: This field is reserved for future use. It should always be set to NULL.

CSSM_MEMORY_FUNCS

This structure is used by applications to supply memory functions for the CSSM and the add-in modules. The functions are used when memory needs to be allocated by the CSSM or add-ins for returning data structures to the applications.

typedef struct cssm_memory_funcs {
  void *(*malloc_func) (uint32 Size, void *AllocRef);
  void  (*free_func)   (void *MemPtr, void *AllocRef);
  void *(*realloc_func)(void *MemPtr, uint32 Size, void *AllocRef);
  void *(*calloc_func) (uint32 Num, uint32 Size, void *AllocRef);
  void *AllocRef;
} CSSM_MEMORY_FUNCS, *CSSM_MEMORY_FUNCS_PTR;

Definition

malloc_func: Pointer to function that returns a void pointer to the allocated memory block of at least size bytes from heap AllocRef.
free_func: Pointer to function that deallocates a previously-allocated memory block (memblock) from heap AllocRef.
realloc_func: Pointer to function that returns a void pointer to the reallocated memory block (memblock) of at least size bytes from heap AllocRef.
calloc_func: Pointer to function that returns a void pointer to an array of num elements of length size initialized to zero from heap AllocRef.
AllocRef: Indicates which memory heap the function operates on.

CSSM_MODULE_FUNCS

This structure is used by add-in modules to pass a table of function pointers for a single service to CSSM. CSSM core service forwards this table to the module manager responsible for dispatching function calls to the add-in module using this function table.

typedef struct cssm_module_funcs {
    uint32 SubServiceID;
    uint32 ServiceType;
    void *ModuleServices;
} CSSM_MODULE_FUNCS, *CSSM_MODULE_FUNCS_PTR;

Definition

SubServiceId: A module-specific identifier.
ServiceType: The type of add-in module services accessible via the ModuleServices function table.

CSSM_MANAGER_EVENT_TYPES

This enumerated list defines a standard set of event types used by module managers when informing other module managers of this event.

typedef enum cssm_manager_event_types {
        CSSM_MANAGER_LOADED = 1,          /* source manager
                                        just loaded */
        CSSM_MANAGER_UNLOADED = 2,        /* source manager about
                                        to be unloaded */
        CSSM_MANAGER_SERVICE_REQUEST = 3, /* source mgr asking
                                        standard service */
        CSSM_MANAGER_REPLY = 4,           /* event is a reply to
                                        earlier event notice */
} CSSM_MANAGER_EVENT_TYPES;

CSSM_MANGER_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 DestinationModuleManagerUsage;
    CSSM_SERVICE_MASK SourceModuleManagerUsage;
    CSSM_MANAGER_EVENT_TYPES Event;
    uint32 EventId;
    CSSM_DATA_PTR 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 result 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_MODULE_HANDLE Modulehandle,
         CSSM_MEMORY_FUNCS_PTR AppMemoryCallTable,
         CSSM_MODULE_FUNCS_PTR AddInCallTable);
    CSSM_RETURN (CSSMAPI *DeregisterDispatchTable)
        (CSSM_MODULE_HANDLE Modulehandle);
    CSSM_RETURN (CSSMAPI *EventNotifyManager)
        (CSSM_SERVICE_MASK DestinationModuleManagerType,
         CSSM_SERVICE_MASK SourceModuleManagerType,
         CSSM_MANAGER_EVENT_TYPES Event,
         uint32 EventId,
         CSSM_DATA_PTR EventData);
} 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 service provider function table to an elective module manager.
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 service provider function table for that add-in module is no longer for the terminating session.
EventNotifyManager: Function invoked by CSSM forwarding an event notification from one module manager to another target module manager.

Elective Module Manager Functions

The manpages for Elective Module Manager Functions can be found at the end of this chapter.

Why not acquire a nicely bound hard copy?
Click here to return to the publication details or order a copy of this publication.
You should also read the legal notice explaining the terms and conditions relating to the CDSA documentation.

Contents

Next section

Index