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