Previous section.

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

Core Services API

Overview

The CSSM provides a set of core service APIs for:

These APIs are implemented by the CSSM, not by add-in modules.

Core Services for CSSM Management

CSSM provides functions for managing multiple instances of CSSM. These instances can be distinct versions of CSSM or multiple copies of the same instance of CSSM. Applications can select which instance of CSSM to use at runtime. Three pieces of information help to identify each instance of a CSSM executable:

Applications can use this descriptive information to assist in selecting the appropriate CSSM instance.

Every CSSM instance must specify its unique identification GUID. Specification of the interface GUID and the version numbers is optional, but believed to be of value as an augmentation to the distinguished name for an executable instance of CSSM. Using these three pieces of information can determine interoperability and compatibility with an instance of CSSM.

Applications use the CSSM_GetInfo interface to obtain this identification information for any instance of CSSM that has been installed on a local system. Once an instance has been selected, the application must load that instance using CSSM_Load. Following the dynamic load operation, the application must perform all required initialization steps before using other CSSM services. Initialization includes invoking CSSM_Init and the optional exchange of application credentials for purposes of authentication between CSSM and the application.

Module Management Services

The CSSM module management functions support module installation, dynamic selection and loading of modules, and querying of module features and status.

System administration utilities use CSSM install and uninstall functions to maintain add-in modules on a local system.

The CSSM registry records information about each installed add-in module and elective module manager for the local system. The registry is CSSM's critical information base. CSSM must support the following services and features with respect to the CSSM registry:

The registry entries are queried by applications, add-in modules, and components of CSSM.

Applications select the particular security services they will use by selectively attaching add-in modules. These modules are provided by independent vendors. Each has an assigned, Globally Unique ID (GUID), and a set of descriptive attributes to assist applications in selecting appropriate modules for their use. A module can implement a range of services across the CSSM APIs (such as, cryptographic functions and data storage functions) or a module can restrict its services to a single CSSM category of service (such as, certificate library services only). Modules that span service categories are called Multi-Service modules.

Applications use a module's GUID to specify the module to be attached. The attach function returns a handle representing a unique pairing between the caller and the attached module. This handle must be provided as in input parameter when requesting services from the attached module. CSSM uses the handle to match the caller with the appropriate service module.

The calling application uses the handle to obtain any and all types of services implemented by the attached module. Application Using Cryptographic Services and Persistent Storage Services shows how the handle for an attached PKCS#11 service provider is used to perform cryptographic operations and persistent storage of certificates. The single handle value can be used as the CSPHandle in cryptographic operations and as the DLHandle in data storage operations.

Figure: Application Using Cryptographic Services and Persistent Storage Services
of a Class 2, PKCS#11 device

Multiple calls to attach are viewed as independent requests. Each attach request returns separate, independent handles that do not share execution state.

Before attaching a service module, an application can query the CSSM registry to obtain information on:

Applications use this information to select a module for use. A multi-service module has multiple capability descriptions associated with it, at least one per functional area supported by the module. Some areas (such as CSP and TP) may have multiple independent capability descriptions for a single functional area. There is one CSSM registry entry for a multi-service module. That entry records all service types for the module. CSSM returns all information about a module's capabilities when queried by the application. Each set of capabilities includes a type identifier to distinguish CSPinfo from Clinfo, and so on.

Applications can query about CSSM itself. Different versions of CSSM and add-in modules will exist. CSSM provides several functions to assist applications in selecting a version that meets the application's needs. One function returns version information about the running CSSM. Another function verifies whether the application's expected CSSM version is compatible with the currently-running CSSM version. The general function to query add-in module information also returns the module's version information.

Memory Management Support

The CSSM memory management functions are a class of routines for reclaiming memory allocated by CSSM on behalf of an application from the CSSM memory heap. When CSSM allocates objects from its own heap and returns them to an application, the application must inform CSSM when it no longer requires the use of that object. Applications use specific APIs to free CSSM-allocated memory. When an application invokes a free function, CSSM can choose to retain or free the indicated object, depending on other conditions known only to CSSM. In this way CSSM and applications work together to manage these objects in the CSSM memory heap.

Integrity of the CSSM Environment

As a security framework, CSSM provides each application with additional assurance of the integrity of the CSSM execution environment With dynamic link-loading of add-in service modules, viruses and other forms of impersonation are common threats. CSSM defines and enforces an umbrella integrity policy that reduces the risk of these threats.

At module attach time, CSSM requires successful certificate-based trust verification for:

All verifications performed to enforce CSSM-defined policy are based on CSSM-selected public root keys as points of trust.

When CSSM performs a verification check on any component in the CSSM environment, the verification process has three aspects:

These steps are implemented by CSSM' s Integrity Services. Integrity Services are packaged as a static library called the Embedded Integrity Services Library (EISL). CDSA defines a bilateral authentication procedure by which CSSM and a component interacting with CSSM authenticate each other to achieve a mutual trust.

As part of bilateral authentication, CSSM calls EISL to verify and load a module or a module manager. If EISL returns a failure condition, then the module or the module manager has not been linked and loaded. CSSM must detect this failure and must return the value CSSM_ATTACH_ERROR to the caller of the CSSM_ModuleAttach operation.

EISL services support unilateral authentication, identity verification, and object code integrity checks. EISL facilities are documented in the CSSM Embedded Integrity Services Library API Spec.

Module-Defined Usage Policies

Service module vendors may wish to provide enhanced services to selected applications or classes of applications. A module-defined policy is in addition to the CSSM's general integrity policy.

Module-defined policies are enforced by one of the following authentication checks:

The module specifies its policy by selecting one of these authentication checks. Options one and two use CSSM to enforce the module-defined policy during attach processing. Option three is carried out independently by the add-in module, using EISL services. The add-in module requests CSSM enforcement by setting MODULE_FLAGS corresponding to options one and two in the MODULE_INFO structure. When option two is selected, the MODULE_INFO structure should also contain a set of module-specific, public root keys corresponding to the module's points of trust.

The MODULE_INFO structure is presented to CSSM during module installation in two forms:

The policy is securely stored in the signed credentials. These credentials are authenticated by CSSM each time the module is attached. CSSM uses the signed policy description as the authoritative representation of the policy. The MODULE_INFO structure is also stored in the CSSM registry allowing applications to read the policy description by calling CSSM_GetModuleInfo.

Add-in modules can independently authenticate applications based on module-defined points of trust. The application must incorporate a verifiable certificate in its credentials. To authenticate the application directly, the add-in module:

An application's verifiable credentials must be created during application manufacturing. The application vendor must obtain a manufacturing/signing certificate from all service module vendors and CSSM vendors who will provide it with privileged status. The application vendor uses the manufacturing certificates to create the certificate chains shown in Application Using Cryptographic Services and Persistent Storage Services . The application must carry all of these certificate chains in the signature block for its persistent credentials. When the application calls CSSM_ModuleAttach on a service module for which it has been granted special privileges, CSSM or the service module can verify at least one of the certificate chains in the application's manifest signature block based on CSSM-defined or module-defined roots of trust.

Three certificate chains representing the application's module-specific credentials for three distinct modules or module vendors

Application-Authenticated Add-In Modules

An application vendor or an application installer can define and enforce a policy that precludes the end-user from using non-authorized add-in service modules. This policy is in addition to CSSM's general integrity policy.

Application-defined policies are enforced by one of the following authentication checks:

The application specifies its policy by selecting one of these authentication checks. Options one and two use CSSM to enforce the application-defined policy during attach processing. Option one is part of the umbrella integrity policy defined and enforced by CSSM. This check is always performed by CSSM. Options two and three are checks performed in addition to the CSSM check. Option three is carried out independently by the application, using EISL services. The application requests CSSM enforcement by setting APP_SERVICE_FLAGS corresponding to option two in the APP_SERVICE_INFO structure. The APP_SERVICE_INFO structure should also contain a set of application-specific, public root keys corresponding to the application's points of trust.

The APP_SERVICE_INFO structure must be flattened and stored as an attribute value in the application's signed credentials. These credentials are used during module attach and provide verifiable information to CSSM for application-directed authentication of the attached add-in module.

Alternatively, applications can independently authenticate selected add-in service modules based on application-defined points of trust. This authentication procedure is in addition to procedures automatically performed by CSSM based on CSSM-defined roots of trust. By performing a second authentication, an application vendor or an application installer can preclude the use of non-authorized add-in modules. The policy defining which add-in modules an application is authorized to use is specified and maintained outside of the CSSM.

The add-in service module must incorporate a verifiable certificate in its credentials. The application must locate the module's credential files and verify them directly by invoking EISL facilities. A module's credentials can be located using file system path information published in the module's CSSM registry entry. (CSSM registry information can be retrieved using the CSSM_GetModuleInfo function.) Verification using EISL facilities must be based on application-defined roots of trust.

An application defines its roots of trust for authenticating add-in modules by one of two methods:

In either case, the application defines a root of trust that can be used to verify the add-in module. The add-in module incorporates a verifiable certificate in its credentials and the application can use CSSM's EISL facilities to authenticate the add-in module based on the application's (adopted or issued) root of trust. The add-in module's credentials will appear as shown in Application Using Cryptographic Services and Persistent Storage Services .

Add-in module credentials including a certificate chain recognized by an application

To authenticate the add-in module using EISL, the application proceeds as follows:

  1. Call CSSM_GetModuleInfo to obtain the pathname and filename for the target module.

  2. Construct the name of the module's associated credentials (using the module's pathname and filename).

  3. For each trusted public root key that could authenticate the target add-in module, call ISL_VerifyLoadedModuleAndCredentials specifying the name of the module's credentials and the trusted public root key, until you find one that verified or all keys fail to verify.

It is important to note that the application-defined roots of trust for authenticating add-in service modules are independent of the module-defined roots of trust for authenticating applications.

A service module's verifiable credentials must be created during module manufacturing. The module vendor must obtain a manufacturing/signing certificate from all application vendors who wish to enforce exclusive use of the service module by their application. The module vendor uses the manufacturing certificates to create the certificate chains shown in Application Using Cryptographic Services and Persistent Storage Services . The module must carry all of these certificate chains in the signature block for its persistent credentials. The application or CSSM can successfully verify at least one of the certificate chains in the module's credentials based on CSSM-defined or application-defined roots of trust.

Application Exemptions

CSSM and the CSSM module managers implement a small number of built-in checks for normal controlled functioning of security services. Applications must be able to request exemption from these built-in checks. Exemption is granted if the caller provides credentials that:

Exemptions can be granted per application thread, if threads are supported in the operating environment. Exemption privileges can not be inherited by spawned processes or spawned threads. Each process or thread must present credentials and obtain its own exemption status.

The CSSM_RequestCssmExemption function is used to request exemptions. Applications can invoke this function at any time after invoking the CSSM_Init function. This allows applications to change exemption status as appropriate during execution. Authentication and implied authorization are checked by CSSM at each request.

A bit mask represents the set of requested exemptions.

New elective module managers can define and implement additional built-in checks. Exemption categories, with corresponding bit mask values, should be defined by the elective module manager. This allows authorized applications to be exempt from these additional built-in checks.

Data Structures for Core Services

CSSM_BOOL

This data type is used to indicate a true or false condition.
typedef uint32 CSSM_BOOL;
#define CSSM_TRUE 1
#define CSSM_FALSE 0

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_STRING

This is used by CSSM data structures to represent a character string inside of a fixed-length buffer. The character string is expected to be NULL-terminated. The string size was chosen to accommodate current security standards, such as PKCS #11.
#define CSSM_MODULE_STRING_SIZE 64
typedef char CSSM_STRING [CSSM_MODULE_STRING_SIZE + 4];

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. Trust policy modules and certificate libraries use this structure to hold certificates and CRLs. Other add-in service modules, such as CSPs, use this same structure to hold general data buffers, and DLMs use this structure to hold persistent security-related objects.
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 distinguishes one add-in module from another. 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_VERSION

This structure is used to represent the version of CDSA components.
typedef struct cssm_version {
    uint32 Major;
    uint32 Minor;
} CSSM_VERSION, *CSSM_VERSION_PTR

Definition

Major

The major version number of the component.

Minor

The minor version number of the component.

CSSM_SUBSERVICE_UID

This structure uniquely identifies a set of behaviors within a subservice within a CSSM add-in module.
typedef struct cssm_subservice_uid {
    CSSM_GUID Guid;
    CSSM_VERSION Version;
    uint32 SubserviceId;
    uint32 SubserviceFlags;
} CSSM_SUBSERVICE_UID, *CSSM_SUBSERVICE_UID_PTR;

Definition

Guid

A unique identifier for a CSSM add-in module.

Version

The version of the add-in module.

SubserviceId

An identifier for the subservice within the add-in module.

SubserviceFlags

An identifier for a set of behaviors provided by this subservice.

CSSM_HANDLE

A unique identifier for an object managed by CSSM or by an add-in module.
typedef uint32 CSSM_HANDLE, *CSSM_HANDLE_PTR

CSSM_MODULE_HANDLE

A unique identifier for an attached service provider module.
typedef uint32 CSSM_MODULE_HANDLE

CSSM_LIST_ITEM

This structure is used to encapsulate the name and GUID of an add-in module.
typedef struct cssm_list_item{
    CSSM_SUBSERVICE_UID SubserviceUid;
    char *Name;
} CSSM_LIST_ITEM, *CSSM_LIST_ITEM_PTR

Definition

SubserviceUid

The global, persistent, unique identifier of the module.

Name

The name of the module.

CSSM_LIST

This structure is used to encapsulate an array of CSSM_LIST_ITEMs, where the array length is given by the NumberItems variable.
typedef struct cssm_list{
    uint32 NumberItems;
    CSSM_LIST_ITEM_PTR Items;
} CSSM_LIST, *CSSM_LIST_PTR

Definition

NumberItems

The number of entries in the Items array.

Items

An array of name and GUID pairs.

CSSM_CSSMINFO

This structure describes attributes of the CSSM infrastructure itself.
typedef struct cssm_cssminfo {
    CSSM_VERSION Version;
    CSSM_STRING Description; /* Description of CSSM */
    CSSM_STRING Vendor; /* Vendor of CSSM */
    CSSM_BOOL ThreadSafe;
    CSSM_STRING Location;
    CSSM_GUID GUID CssmGUID;
    CSSM_GUID InterfaceGUID; /* opt GUID defining supported
                                                    interface */
}CSSM_CSSMINFO, *CSSM_CSSMINFO_PTR

Definition

Version

The major and minor version numbers of the CSSM Core component.

Description

A text description of the CSSM Core.

Vendor

The name and description of the CSSM Core vendor.

ThreadSafe

An indicator of whether or not this CSSM Core implementation is thread safe.

Location

The path to the CSSM Core library.

CssmGUID

The unique identifier of the CSSM Core library.

InterfaceGUID

the unique identifier of the interface implemented by the CSSM core library.

CSSM_EVENT_TYPE

Events occur when an application calls a CSSM core service function. CSSM informs the attached module of this event using the EventNotify call to the Service provider module. Six types of events are defined:
typedef uint32 CSSM_EVENT_TYPE, *CSSM_EVENT_TYPE_PTR;
#define CSSM_EVENT_ATTACH (0)
/* application has requested an attach operation */
#define CSSM_EVENT_DETACH (1)
/* application has requested an detach operation */
#define CSSM_EVENT_INFOATTACH (2)
/* application has requested module info for dynamic module
                                            capabilities */
#define CSSM_EVENT_INFODETACH (3)
/* CSSM has completed obtaining dynamic module capabilities */
#define CSSM_EVENT_CREATE_CONTEXT (4)
/* application has performed a create context operation */
#define CSSM_EVENT_DELETE_CONTEXT (5)
/* application has performed a delete context operation */

CSSM_SERVICE_MASK

This defines a bit mask of all the types of CSSM services a single module can implement.
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_SERVICE_TYPE

This data type is used to identify a single service from the CSSM_SERVICE_MASK options defined above.
typedef CSSM_SERVICE_MASK CSSM_SERVICE_TYPE

CSSM_SERVICE_FLAGS

This bitmask is used to identify characteristics of the service, such as whether it contains any embedded products.
typedef uint32 CSSM_SERVICE_FLAGS
#define CSSM_SERVICE_ISWRAPPEDPRODUCT 0x1
    /* On = Contains one or more embedded products
    Off = Contains no embedded products */

CSSM_SERVICE_INFO

This structure holds a description of a module service. The service described is of the CSSM service type specified by the module usage type.
typedef struct cssm_serviceinfo {
    CSSM_STRING Description; /* Service description */
    CSSM_SERVICE_TYPE Type; /* Service type */
    CSSM_SERVICE_FLAGS Flags; /* Service flags */
    uint32 NumberOfSubServices; /* Number of sub services in
                                        SubService List */
    union cssm_subservice_list { /* List of sub services */
        void *SubServiceList;
        CSSM_CSPSUBSERVICE_PTR CspSubServiceList;
        CSSM_DLSUBSERVICE_PTR DlSubServiceList;
        CSSM_CLSUBSERVICE_PTR ClSubServiceList;
        CSSM_TPSUBSERVICE_PTR TpSubServiceList;
    } SubserviceList;
    void *Reserved;
} CSSM_SERVICE_INFO, *CSSM_SERVICE_INFO_PTR;

Definition

Description

A text description of the service.

Type

Specifies exactly one type of service structure, such as CSSM_SERVICE_CSP, CSSM_SERVICE_CL, and so on.

Flags

Characteristics of this service, such as whether it contains any embedded products.

NumberOfSubServices

The number of elements in the module SubServiceList.

SubServiceList

A list of descriptions of the encapsulated SubServices which are not of the basic service types.

CspSubServiceList

A list of descriptions of the encapsulated CSP SubServices.

DlSubServiceList

A list of descriptions of the encapsulated DL SubServices.

ClSubServiceList

A list of descriptions of the encapsulated CL SubServices.

TpSubServiceList

A list of descriptions of the encapsulated TP SubServices.

Reserved

This field is reserved for future use. It should always be set to NULL.

CSSM_MODULE_FLAGS

This bitmask is used to identify characteristics of the module, such as whether it is threadsafe, exportable, an so on. The flags also describe if and how CSSM must perform additional authentication checks on behalf of the add-in service module during module attach. The service module can select one of the following authentication checks:
typedef uint32 CSSM_MODULE_FLAGS;

#define CSSM_MODULE_THREADSAFE 0x1 /* Module is threadsafe */
#define CSSM_MODULE_EXPORTABLE 0x2 /* Module can be exported
                                        outside the USA */
#define CSSM_MODULE_CALLER_AUTHENTOCSSM 0x04
    /* CSSM authenticates the caller based on CSSM-known points
                                                of trust */
#define CSSM_MODULE_CALLER_AUTHENTOMODULE 0x08
    /* CSSM authenticates the caller based on module-supplied
                                        points of trust */

CSSM_MODULE_INFO

This structure aggregates all service descriptions about all service types of a module implementation.
typedef struct cssm_moduleinfo {
    CSSM_VERSION Version; /* Module version */
    CSSM_VERSION CompatibleCSSMVersion; /* CSSM version the
                                        module is written for*/
    CSSM_GUID_PTR InterfaceGUID; /* opt GUID defining supported
                                           interface */
    CSSM_STRING Description; /* Module description */
    CSSM_STRING Vendor; /* Vendor name */
    CSSM_MODULE_FLAGS Flags; /* Flags to describe and control 
                                           module use */
    CSSM_KEY_PTR AppAuthenRootKeys; /* Module-specific keys to 
                                        authenticate apps */
    uint32 NumberOfAppAuthenRootKeys; /* Number of module-
                                        specific root keys */
    CSSM_SERVICE_MASK ServiceMask; /* Bit mask of supported 
                                        services */
    uint32 NumberOfServices; /* Number of services in ServiceList */
    CSSM_SERVICE_INFO_PTR ServiceList; /* A list of service 
                                        info structures */
    void *Reserved;
} CSSM_MODULE_INFO, *CSSM_MODULE_INFO_PTR;

Definition

Version

The major and minor version numbers of this add-in module.

CompatibleCSSMVersion

The version of CSSM that this module was written to.

InterfaceGUID

GUID describing the interface supported by the version of CSSM that this module was written to

Description

A text description of this module and its functionality.

Vendor

The name and description of the module vendor.

Flags

Characteristics of this module, such as whether or not it is threadsafe.

AppAuthenRootKeys

Public root keys used by CSSM to verify an application's credentials when the service module has requested authentication based on module-specified root keys by setting the CSSM_MODULE_CALLER_AUTHENTOMODULE bit to true in its CSSM_MODULE_FLAGS mask. These keys should successfully authenticate only those applications that the service module wishes to recognize to receive the services the module has registered with CSSM during module installation.

NumberOfAppAuthenRootKeys

The number of public root keys in the AppAuthenRoot Keys list.

ServiceMask

A bit mask identifying the types of services available in this module.

NumberOfServices

The number of services for which information is provided. Multiple descriptions (as sub-services) can be provided for a single service category.

ServiceList

An array of pointers to the service information structures. This array contains NumberOfServices entries.

Reserved

This field is reserved for future use. It should always be set to NULL.

CSSM_ALL_SUBSERVICES

This data type is used to identify that information on all of the sub-services is being requested or returned.

CSSM_INFO_LEVEL

This enumerated list defines the levels of information detail that can be retrieved about the services and capabilities implemented by a particular module. Modules can implement multiple CSSM service types. Each service may provide one or more sub-services, and can also be have dynamically available services and features.
typedef enum cssm_info_level {
    CSSM_INFO_LEVEL_MODULE = 0,
    /* values from CSSM_SERVICE_INFO struct */
    CSSM_INFO_LEVEL_SUBSERVICE = 1,
    /* values from CSSM_SERVICE_INFO and XXsubservice struct */
    CSSM_INFO_LEVEL_STATIC_ATTR = 2,
    /* values from CSSM_SERVICE_INFO and XXsubservice and
    all static-valued attributes of a subservice */
    CSSM_INFO_LEVEL_ALL_ATTR = 3,
    /* values from CSSM_SERVICE_INFO and XXsubservice and
    all attributes, static and dynamic, of a subservice */
} CSSM_INFO_LEVEL;

CSSM_NET_ADDRESS_TYPE

This enumerated type defines representations for specifying the location of a service.
typedef enum cssm_net_address_type {
    CSSM_ADDR_NONE = 0,
    CSSM_ADDR_CUSTOM = 1,
    CSSM_ADDR_URL = 2, /* char* */
    CSSM_ADDR_SOCKADDR = 3,
    CSSM_ADDR_NAME = 4 /* char* - qualified by access method */
} CSSM_NET_ADDRESS_TYPE;

CSSM_NET_ADDRESS

This structure holds the address of a service. Typically the service is remote, but the value of the address field may resolve to the local system. The AddressType field defines how the Address field should be interpreted.
typedef struct cssm_net_address {
    CSSM_NET_ADDRESS_TYPE AddressType;
    CSSM_DATA Address;
} CSSM_NET_ADDRESS, *CSSM_NET_ADDRESS_PTR;

CSSM_NET_PROTOCOL

This enumerated list defines the application-level protocols that could be supported by a Certificate Library Module that communicates with Certification Authorities, Registration Authorities and other services, or by a Data Storage Library Module that communicates with service-based storage and directory services.
typedef enum cssm_net_protocol {
    CSSM_NET_PROTO_NONE = 0, /* local */
    CSSM_NET_PROTO_CUSTOM = 1, /* proprietary implementation */
    CSSM_NET_PROTO_UNSPECIFIED = 2, /* implementation default */
    CSSM_NET_PROTO_LDAP = 3, /* light weight directory access 
                                        protocol */
    CSSM_NET_PROTO_LDAPS = 4, /* ldap/ssl where SSL initiates 
                                        the connection */
    CSSM_NET_PROTO_LDAPNS = 5, /* ldap where ldap negotiates an 
                                        SSL session */
    CSSM_NET_PROTO_X500DAP = 6, /* x.500 Directory access 
                                        protocol */
    CSSM_NET_PROTO_FTPDAP = 7, /* file transfer protocol for 
                                        cert/crl fetch */
    CSSM_NET_PROTO_FTPDAPS = 8, /* ftp/ssl where SSL initiates 
                                        the connection */
    CSSM_NET_PROTO_NDS = 9, /* Novell directory services */
    CSSM_NET_PROTO_OCSP = 10, /* online certificate status 
                                        protocol */
    CSSM_NET_PROTO_PKIX3 = 11, /* the cert request protocol 
                                        in PKIX3 */
    CSSM_NET_PROTO_PKIX3S = 12, /* The ssl/tls derivative 
                                        of PKIX3 */
    CSSM_NET_PROTO_PKCS_HTTP = 13, /* PKCS client <=> CA protocol 
                                        over HTTP */
    CSSM_NET_PROTO_PKCS_HTTPS = 14, /* PKCS client <=> CA protocol
                                        over HTTPS */
} CSSM_NET_PROTOCOL;

CSSM_APP_SERVICE_FLAGS

As part of module-attach processing, CSSM authenticates every attached service module based on CSSM-defined roots of trust. Applications can elect to have CSSM perform an additional authentication check on behalf of the application. This additional verification is performed during module attach and is based on application-specified roots of trust. An application service flag is used to request this additional service by CSSM.
typedef uint32 CSSM_APP_SERVICE_FLAGS

#define CSSM_APP_SERVICE_AUTHENTOAPP  0x1 
      /* CSSM authenticates the service module based on
         application-supplied points of trust */

CSSM_APP_KEYS

This structure aggregates the roots of trust for authenticating a particular add-in service module during module attach.

typedef struct cssm_app_keys {
    CSSM_KEY_PTR ModuleAuthenRootKeys,
          /* Application-specified keys to authen service modules*/
    uint32 NumberOfModuleAuthenRootKeys,
          /* Number of application-specified root keys */
} CSSM_APP_KEYS, *CSSM_APP_KEYS_PTR;

Definition

ModuleAuthenRootKeys

Public root keys used by CSSM to verify an service module's credentials when the application has requested authentication based on application-specified root keys by setting the CSSM_APP_SERVICE_AUTHENTOAPP bit to true in the flags mask in the CSSM_APP_SERVICE_INFO structure. These keys should successfully authenticate only those service modules that the application wishes to recognize.

NumberOfModuleAuthenRootKeys

The number of public root keys in the ModuleAuthenRoot Keys list.

CSSM_APP_SERVICE_INFO

This structure aggregates all information required by CSSM to perform additional authentication of add-in service modules on behalf of an application during module attach processing.

typedef struct cssm_app_service_info {
    CSSM_SUBSERVICE_UID_PTR ModuleList;  /* List of module 
                                         service ID structs */
    uint32 NumberOfModules;              /* Number of modules to 
                                         authenticate */
    CSSM_APP_SERVICE_FLAGS Flags;
/* Flags selecting CSSM or app-specified roots of trust */
    CSSM_APP_KEYS_PTR *Keys,
/* Application-specified keys to authenticate modules */
    void *Reserved;
} CSSM_APP_SERVICE_INFO, *CSSM_APP_SERVICE_INFO_PTR; 

Definition

ModuleList

The unique identifier for each module that CSSM must authenticate on behalf of the application.

NumberOfModules

The number of module identification structure in ModuleList.

Flags

Specify whether CSSM a second verification of the service module using application-specified roots of trust.

Keys

A pointer to a list of sets of application-specified root keys, one for each module in ModuleList. These keys are used by CSSM to verify the module during module attach.

Reserved

This field is reserved for future use. It should always be set to NULL.

CSSM_EXEMPTION_MASK

This bitmask represents the exemptions requested by the calling application process or thread. Exemptions are defined corresponding to built-in checks performed by CSSM and the CSSM Module Managers. Elective Module Managers can define additional categories of exemption for built-in checks performed by those elective managers. The caller must possess the necessary credentials to be granted the exemptions.
typedef uint32 CSSM_EXEMPTION_MASK

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

CSSM_USER_AUTHENTICATION_MECHANISM

This enumerated list defines different methods an add-in module can require when authenticating a caller. The module specifies which mechanism the caller must use for each sub-service type provided by the module. CSSM-defined authentication methods include password-based authentication, a login sequence, or a certificate and passphrase. It is anticipated that new mechanisms will be added to this list as required.
typedef enum cssm_user_authentication_mechanism {
    CSSM_AUTHENTICATION_NONE = 0,
    CSSM_AUTHENTICATION_CUSTOM = 1,
    CSSM_AUTHENTICATION_PASSWORD = 2,
    CSSM_AUTHENTICATION_USERID_AND_PASSWORD = 3,
    CSSM_AUTHENTICATION_CERTIFICATE_AND_PASSPHRASE = 4,
    CSSM_AUTHENTICATION_LOGIN_AND_WRAP = 5,
} CSSM_USER_AUTHENTICATION_MECHANISM;

CSSM_CALLBACK

An application uses this data type to request that an add-in module call back into the application for certain cryptographic information.
typedef CSSM_DATA_PTR (CSSMAPI *CSSM_CALLBACK) (void *allocRef, uint32 ID);

Definition

allocRef

Memory heap reference specifying which heap to use for memory allocation.

ID

Input data to identify the callback.

CSSM_CRYPTO_DATA

This data structure is used to encapsulate cryptographic information, such as the passphrase to use when accessing a private key.
typedef struct cssm_crypto_data {
    CSSM_DATA_PTR Param;
    CSSM_CALLBACK Callback;
    uint32 ID;
}CSSM_CRYPTO_DATA, *CSSM_CRYPTO_DATA_PTR

Definition

Param

A pointer to the parameter data and its size in bytes.

Callback

An optional callback routine for the add-in modules to obtain the parameter.

ID

A tag that identifies the callback.

CSSM_USER_AUTHENTICATION

This structure holds the user's credentials for authenticating to a module. The type of credentials required is defined by the module and specified as a CSSM_USER_AUTHENTICATION_MECHANISM.
typedef struct cssm_user_authentication {
    CSSM_DATA_PTR Credential; /* a cert, a shared secret, other */
    CSSM_CRYPTO_DATA_PTR MoreAuthenticationData;
} CSSM_USER_AUTHENTICATION, *CSSM_USER_AUTHENTICATION_PTR;

Definition

Credential

A certificate, a shared secret, a magic token or whatever is required by an add-in service modules for user authentication. The required credential type is specified as a CSSM_USER_AUTHENTICATION_MECHANISM.

MoreAuthenticationData

A passphrase or other data that can be provided as immediate data within this structure or via a callback function to the user/caller.

CSSM_NOTIFY_CALLBACK

An application uses this data type to request that an add-in module call back into the application to notify it of certain events.
typedef CSSM_RETURN (CSSMAPI *CSSM_NOTIFY_CALLBACK)
    (CSSM_MODULE_HANDLE ModuleHandle,
    uint32 Application,
    uint32 Reason,
    void* Param);

Definition

ModuleHandle

The handle of the attached add-in module.

Application

Input data to identify the callback.

Reason

The reason for the notification.

Reason Description
CSSM_NOTIFY_SURRENDER The add-in module is temporarily surrendering control of the process
CSSM_NOTIFY_COMPLETE An asynchronous operation has completed
CSSM_NOTIFY_DEVICE_REMOVED A device, such as a token or storage device, has been removed
CSSM_NOTIFY_DEVICE_INSERTED A device, such as a token or storage device, has been inserted

Param

Any additional information about the event.

CSSM_MEMORY_FUNCS and CSSM_API_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;

typedef CSSM_MEMORY_FUNCS CSSM_API_MEMORY_FUNCS;
typedef CSSM_API_MEMORY_FUNCS *CSSM_API_MEMORY_FUNCS_PTR;

Definition

malloc_func

Pointer to a function that returns a void pointer to the allocated memory block of at least Size bytes from heap AllocRef.

free_func

Pointer to a function that deallocates a previously-allocated memory block (MemPtr) from heap AllocRef.

realloc_func

Pointer to a function that returns a void pointer to the reallocated memory block (MemPtr) of at least Size bytes from heap AllocRef.

calloc_func

Pointer to a 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.

See Application Memory Functions for details about the application memory functions.

Core Functions

The manpages for Core Functions can be found at the end of this chapter.

Module Management Functions

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

Utility Functions

The manpages for Utility 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