Previous section.

Common Security: CDSA and CSSM, Version 2
Copyright © 1999 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 security service modules.

Module Management Services

The CSSM module management functions support dynamic selection and loading of service provider modules.

Applications can have apriori knowledge of the service module to be used or can use the Module Directory Services (MDS) to search the CDSA Directory database for service modules that provide the features and services required by the application. When service providers are made accessible on the local platform (typically through platform-specific installation procedures), the installation procedure includes registering the service module in MDS's CDSA database.

MDS records information about each installed service module and elective module manager available on the local system. MDS supports the following services and features with respect to the CDSA database:

The database entries are queried by applications, service modules, EMMs, and CSSM.

Applications select the particular security service they will use by selectively loading and attaching service 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 an input parameter when requesting services from the attached module. CSSM uses the handle to match the caller with the appropriate service module and service type.

The calling application attaches to a module once for each type of service it requires. If the service type requested by the application is not implemented by the module, the attach fails. PKCS#11 Device Using Crypto and Persistent Storage Services shows how the handles for an attached PKCS#11 service provider are used to perform cryptographic operations and persistent storage of certificates.


Figure: PKCS#11 Device Using Crypto and Persistent Storage Services

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 MDS CDSA database 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. The MDS CDSA database stores one record for each service category provided by a service module.

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 security 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.

CSSM requires successful certificate-based trust verification of all service modules when processing a CSSM_ModuleLoad() request. CSSM also requires trust verification of all Elective Module Managers when processing a CSSM_ModuleAttach() request.

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:

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 verifies and loads a module or a module manager. If verification fails, then the module or the module manager is not linked or loaded.

CDSA and Privileges

The CDSA environment supports modal behavior based on privilege granted through signed manifests and associated certificates. There are two classes of privileges:

Application privileges are specific to a class of applications and service providers. If used, CSSM will ensure the calling module and the target service provider are authorized to switch to the mode implied by a chosen privilege. The export privileges are a class of privileges allowing modal behavior in service providers which coincides with the export regulations over cryptography. More detail on export privileges is provided below.

Application privileges may be defined by The Open Group, and may also be vendor defined. The representation of privileges uses two 4-byte words (or an 8-byte word if the platform supports 64-bit words) The number space is divided in half between standard privileges and vendor defined privileges. The lower 32-bits are reserved for standard privileges and the upper 32-bits allocated to vendor specific privileges. The application privileges are granted to modules in signed manifests using the tag CDSA_PRIV. The CDSA_PRIV tag is added to the signer_info section of the module manifest. The associated value is a string of 4 byte base-64 encoded numbers, in big-endian order. Encoded 4-byte words are separated by colons. These numbers are the same numbers defined for the high-order word of CSSM_PRIVILEGE.

CDSA and USEE Privileges

Export privileges enable strong cryptography to be made available through the CDSA framework to applications performing special functions - where they would qualify for special case exemption from export regulations. Exportable components must enforce export policies to a "reasonable" degree, such that the effort to circumvent the enforcement mechanisms is at least as difficult as engineering the desired functionality from scratch.

All of the CDSA logical components may be subject to export controls. Exemptions to the export policy of public record are modeled using an artifact called USEE tags. Any time an exemption to export policy is granted, a USEE tag may be defined. The semantics of the USEE tag is interpreted in the context of the Exemption Rules. A standards body should control USEE namespace and provide interpretations of the meaning of USEE tags for developers. Specific requirements for USEE tags:

Exemptions are defined for financial, medical, insurance, key recovery, key exchange and authentication. SSL is also cited as a special case exemption in that SSL ciphersuites makes accommodation for export. As such, the USEE tag for SSL signifies to CSSM that the SSL library will carry the enforcement responsibilities. The tag for domestic use is provided for compatibility reasons. Any module not exported may carry the domestic privilege. The CSSM manifest does not require USEE tags to enforce their semantics. It is anticipated that other tags will be added as export policies change.

Additionally, CSSM and EMM components may use USEE tags to configure starting state. For example, the key recovery tag could instruct CSSM to set an internal switch that prevents use of attach handles that have not been sanitized through the key recovery module. Likewise, the domestic tag could indicate that the CSSM will not enforce export exemptions when deployed in the U.S.

A service module can also check the application manifest directly by retrieving its manifest from the MDS and verifying the signature.

Module-Granted Use Exemptions

Service module vendors can choose to provide enhanced services to selected applications or classes of applications. A module-defined use policy is in addition to the general CSSM integrity policy. Categories of enhanced services are defined as use exemptions. CSSM_USEE_TAG declares the currently defined set of exemption classes. These focus primarily on exemptions for using cryptographic services. New exemption classes can be defined in association with any category of security services.

Service providers should record the exemptions they grant by listing them in an appropriate MDS relation. Currently, Cryptographic Service Providers (CSPs) advertise their exemptions by listing them in the UseeTag attribute of the MDS CSP Primary relation. This is for information only. The verifiable authorization to grant the exemption must be recorded in the service module's signed manifest credentials. If a module grants exemptions, then the module's signed manifest must include a manifest attribute attesting to this authority. The manifest attribute for currently defined exemptions is a name-value pair with name CDSA_USEE. The associated value is a string of 4-byte base-64 encoded numbers in big-endian order. Encoded 4-byte words are separated by colons. These numbers are the same numbers defined for the lower order word of CSSM_PRIVILEGE. An example of CDSA_USEE tag in the manifest (which corresponds to the base64 encoding of the CSSM_USEE_TAG) is: 



 

CDSA_USEE: AAAAAg==:AAAABQ==:AAAAAw==

Applications can query MDS to retrieve the USEE Tags associated with any CSP.

Privileges which have numbers from the high order word of the CSSM_PRIVILEGE will use the manifest tag CDSA_PRIV, as opposed to the tag CDSA_USEE. Other than that exception, they are used exactly like the tags listed as CDSA_USEE*.

The CSSM_Init function needs to be called before calling any other CSSM interfaces. At the time of the first CSSM_Init call, a CSSM_PRIVILEGE_SCOPE and CSSM_KEY_HIERARCHY can be passed in. Based on the platform-specific implementation of CSSM, CSSM_Init() will succeed or return an error if the privilege scope is not supported. The Caller has to introduce itself to the CSSM framework for requesting privileges using the CSSM_Introduce,() CSSM_Init() or CSSM_ModuleAttach() call. Once the caller is introduced to the CSSM, CSSM remembers the privilege and key hierarchy of the callers.

There are two ways for an Application to request a privilege:

  1. An application can request a privilege while making a call to the "P" functions, for example, EncryptDataP, DecryptDataP, WrapKeyP or UnwrapKeyP, by passing the USEE_TAG as the privilege parameter. (If SetPrivilege is called and then a call is made to one of the "P" functions the USEE_TAG that is requested in the "P" function call will be sent to the service provider.)

  2. An application can set the privilege for all of its calls to a service provider by calling CSSM_Introduce() and CSSM_SetPrivilege() functions. After calling CSSM_SetPrivilege(), CSSM will then forward the USEE_TAG that was set to the service provider when a call is made to EncryptData, DecryptData, etc.

The appropriate USEE tags that validates the requested exemption may be in either the signed manifest of the Application (stored in the MDS Object Directory relation), and/or in the signed manifest of the CSSM. Either the Application or the CSSM (or both) must have a signed manifest with the appropriate USEE tag.

Service Module Requirements if USEE Tags are Supported

Application Privilege

Applications that require privileged use of cryptographic technology must obtain the necessary approval from their controling authority. In the USA, in order to get export privilege, an Application that uses cryptographic technology based on CDSA must undergo a one-time review by the National Security Agency (NSA). Applications may use CDSA USEE tags to obtain that privilege.

Multiple CSSM Vendors Authenticating Same Application

Different CSSMs can cross-check the same application, even if it requires application credentials based on difference roots of trust. Multiple CSSM Vendors Authenticating Same Application shows a complete set of credentials for an application module that can be cross-checked by different CSSM vendors. The credentials include three certificate chains. Each chain has a distinct root, and all chains sign the product. All three certificate chains are included in the credentials for this application module. When CSSM #1 attempts to verify the application module's credential, a verified certificate chain will be constructed from the application module's leaf certificate to the root certificate containing either public key PK2 or public key PK3, which are recognized as a points of trust by CSSM #1. Hence the application module's credentials will be successfully verified. CSSM #2 would verify the application module using public key PK5.


Figure: Multiple CSSM Vendors Authenticating Same Application

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_FALSE (0)
#define CSSM_TRUE (!CSSM_FALSE)
Definitions

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 returned by most CDSA functions. The permitted values include: 



 

typedef uint32 CSSM_RETURN;

#define CSSM_OK (0)
Definitions

CSSM_OK

Indicates operation was successful

All other values

Indicates the operation was unsuccessful and identifies the specific, detected error that resulted in the failure. Specific error values are defined for each function.

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 security service 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;
Definitions

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 security service 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;
Definitions

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_KEY_HIERARCHY

The CSSM_KEY_HIERARCHY is a bitmask of values defining classes of key hierarchies from which CDSA components may be signed. Components may be signed by a single key hierarchy, multiple hierarchies or not signed. A bitmask is used to indicate which hierarchies are important. 


 

typedef uint32 CSSM_BITMASK; 
typedef CSSM_BITMASK CSSM_KEY_HIERARCHY; 
#define CSSM_KEY_HIERARCHY_NONE (0)
#define CSSM_KEY_HIERARCHY_INTEG (1)
#define CSSM_KEY_HIERARCHY_EXPORT (2)

Definitions

CSSM_KEY_HIERARCHY_NONE

This value indicates the key hierarchy is unspecified. Unspecified key hierarchy values usually indicate the intended hierarchy will be inferred. For modules without a manifest, CSSM_KEY_HERARCHY_NONE may be supplied.

CSSM_KEY_HIERARCHY_INTEG

This value indicates the embedded key used for integrity checking is associated with a public key infrastructure that vouches for the integrity of executable modules. This flag helps the CSSM identify which embedded key will be used to determine the root of trust when performing cross-check operations.

CSSM_KEY_HIERARCHY_EXPORT

This value indicates the embedded key used for validating export privileges should be used to perform cross-check operations.

CSSM_PVC_MODE

Pointer validation checking policy can be configured globally for the CSSM when CSSM_Init() is called. See CSSM_Init for additional information. The possible values are as follows:

Value Description
0 PVC validation is not performed
1 PVC validation is performed on application modules
2 PVC validation is performed on service provider modules
3 Both types of PVC validations are performed 



 

typedef CSSM_BITMASK CSSM_PVC_MODE;


#define CSSM_PVC_NONE (0)
#define CSSM_PVC_APP (1)
#define CSSM_PVC_SP (2)

CSSM_PRIVILEGE_SCOPE

The privilege scope identifies whether the privilege specified using the CSSM_SetPrivilege() call applies to the entire process, CSSM_PRIVILEGE_SCOPE_PROCESS, or to the current thread, CSSM_PRIVILEGE_SCOPE_THREAD. The scope will determine the conditions under which other calls to CSSM_SetPrivilege() will be visible by other threads and libraries. 



 

typedef uint32 CSSM_PRIVILEGE_SCOPE;


#define CSSM_PRIVILEGE_SCOPE_NONE (0)
#define CSSM_PRIVILEGE_SCOPE_PROCESS (1)
#define CSSM_PRIVILEGE_SCOPE_THREAD (2)

CSSM_VERSION

This structure is used to represent the version of CDSA components. The major number begins at 1 and is incremented by 1 for each major release. 


 

typedef struct cssm_version {
    uint32 Major;
    uint32 Minor;
} CSSM_VERSION, *CSSM_VERSION_PTR;
Definitions

Major

The major version number of the component.

Minor

The minor version number of the component.

The minor number uses two digits to represent minor releases and revisions. The revision number is represented in the least significant digit. The remaining more significant digits represent minor numbers. The first release has the value of zero. There can be 9 subsequent releases then the minor number must be incremented. For example, the minor number for the very first release of a product would be represented as "00". Subsequent releases would be "01", "02", "03" etc., to "09". If version number changes at each release then the minor numbers would increment from "00", "10", "20" etc., to "90". A minor version of 10 release 1 would be "100".

Examples:

1.0.0 - Major: 1 Minor: 0
1.1.0 - Major: 1 Minor: 10
1.1.1 - Major: 1 Minor: 11
1.24 - Major: 1 Minor: 240
1.24.9 - Major: 1 Minor: 249
1.24.38 - not possible

CSSM_SUBSERVICE_UID

This structure uniquely identifies a set of behaviors within a subservice within a CSSM security service module. 


 

typedef struct cssm_subservice_uid {
    CSSM_GUID Guid;
    CSSM_VERSION Version;
    uint32 SubserviceId;
    CSSM_SERVICE_TYPE SubserviceType;
} CSSM_SUBSERVICE_UID, *CSSM_SUBSERVICE_UID_PTR;
Definitions

Guid

A unique identifier for a CSSM security service module.

Version

The version of the security service module.

SubserviceId

An identifier for the subservice within the security service 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 security service module. 


 

typedef uint32 CSSM_HANDLE, *CSSM_HANDLE_PTR;

CSSM_LONG_HANDLE

A unique, long identifier for an object managed by CSSM or by a service module. 


 

#if defined (WIN32)
typedef unsigned __int64 uint64; /* MSVC++ 5 declaration */
#else
typedef unsigned long long uint64; /* gcc 2.7.2 declaration */
#endif


typedef uint64 CSSM_LONG_HANDLE, *CSSM_LONG_HANDLE_PTR;

CSSM_MODULE_HANDLE

A unique identifier for an attached service provider module. 


 

typedef CSSM_HANDLE CSSM_MODULE_HANDLE, *CSSM_MODULE_HANDLE_PTR;

CSSM_MODULE_EVENT

This enumeration defines the event types that can be raised by any service module. Callers can define event handling callback functions of type CSSM_API_ModuleEventHandler to receive and manage these events. Callback functions are registered using the CSSM_ModuleLoad() function. Example events include insertion and removal of a subservice. Events are asynchronous. 


 

typedef enum cssm_module_event {
    CSSM_NOTIFY_INSERT = 1,
    CSSM_NOTIFY_REMOVE = 2,
    CSSM_NOTIFY_FAULT = 3, 
} CSSM_MODULE_EVENT, *CSSM_MODULE_EVENT_PTR;

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_AC (0x20)
#define CSSM_SERVICE_KR (0x40)

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_API_ModuleEventHandler

This defines the event handler interface that an application must define and implement to receive asynchronous notification of events such as insertion or removal of a hardware service module, or a fault detected by the service module. The event handler is registered with CSSM as part of the CSSM_ModuleLoad() function. This is the caller's single event handle for all general module events over all of the caller's attach-sessions with the loaded module. This general event notification is processed through CSSM.

The event handler defined by the CSSM_API_ModuleEventHandler structure must be executed outside the thread context that registered the handler. The handler can queue the event results and schedule a reader thread to service the queue. Applications should use AppNotifyCallbackCtx to track thread-id, the head of the queue, and other state information necessary to service the queue and process the events. The event handler must not issue calls through the CSSM API. These circular calls can result in deadlock in numerous situations, hence the event handler must be implemented without using CSSM services.

The CSSM_API_ModuleEventHandler can be invoked multiple times in response to a single event (such as the insertion of a smartcard). The handler and the calling application must track receipt of event notifications and ignore duplicates. Other events (such as the removal of a smartcard) can result in a single event notification. 



 

typedef CSSM_RETURN (CSSMAPI *CSSM_API_ModuleEventHandler)
    (const CSSM_GUID *ModuleGuid,
    void* AppNotifyCallbackCtx,
    uint32 SubserviceId,
    CSSM_SERVICE_TYPE ServiceType,
    CSSM_MODULE_EVENT EventType);

Definitions

ModuleGuid (input)

The GUID of the service module raising the event.

AppNotifyCallbackCtx (input)

The application context specified during CSSM_ModuleLoad().

SubserviceId (input)

The subserviceId of the service module raising the event.

ServiceType (input)

The service mask of the module raising the event.

EventType (input)

The CSSM_MODULE_EVENT that has occurred.

CSSM_ATTACH_FLAGS

This bitmask is used to specify the behaivor of the service provider being attached. 


 

typedef uint32 CSSM_ATTACH_FLAGS;


#define CSSM_ATTACH_READ_ONLY (0x00000001)
Definitions

CSSM_ATTACH_READ_ONLY

Causes the service provider to block all creation or deletion of persistent resources using the attach handle. An application may later override this flag using module specific facilities.

CSSM_PRIVILEGE

The USE exemption tag lists the exemption categories for cryptographic services. These categories can be supported by a cryptographic service provider. An application can be authorized to receive these services. The granting of one or more exemptions is recorded in an application's signed manifest credentials Cryptographic service providers record their ability to honor such exemptions in their signed manifest credential. Use exemptions can be defined to other cateogries of security services.

The representation of privileges uses two 4-byte words (or an 8 byte word if the platform supports 64-bit words). The high-order 4-byte word is reserved for non-export related privileges and vendor-specific privileges. Of the low-order 4-byte word, the lower byte is used to represent United States export policy, also known as USEE tags. The remaining number space (3 bytes) is reserved for future expansion.

Low-Order Word

Byte 3 Byte 2 Byte 1 Byte 0
Reserved Reserved Reserved USEE Tag

typedef uint32 CSSM_USEE_TAG;

There are U.S. export exemptions for strong encryption financial, medical, insurance, key recovery, key exchange and authentication applications. SSL is cited as a special case exemption in that SSL ciphersuites make accommodation for U.S. export rules. As such, the USEE tag for SSL signifies to CSSM that the SSL library will carry the enforcement responsibilities. The tag for domestic use is provided for compatibility reasons. Any U.S. module not exported may carry the domestic privilege. The CSSM manifest does not require USEE tags to enforce their semantics. It is anticipated that other tags will be added as U.S. export policies change and other types of exemptions are identified.

The high-order 4 bytes of privilege vector allow for vendor specific privilege values. The high order bit (31) is set (1). The lower 31 bits are reserved for vendor-specific privileges. When unset (0), the lower 31 bits (0-30) are interpreted as CDSA privileges not related to export. No CDSA non-export privileges are defined at the time of publishing this Technical Standard.

High-Order Word

Byte 7 Byte 6 Byte 5 Byte 4
Other Other Other Other
Privilege Privilege Privilege Privilege

Non-export privilege range: (0x00000000 - 0x7FFFFFFF)
Vendor specific range: (0x80000000 - 0xFFFFFFFF) 



 

typedef uint64 CSSM_PRIVILEGE;

#define CSSM_USEE_LAST (0xFF)

#define CSSM_USEE_NONE (0) 
#define CSSM_USEE_DOMESTIC (1)
#define CSSM_USEE_FINANCIAL (2)
#define CSSM_USEE_KRLE (3)
#define CSSM_USEE_KRENT (4)
#define CSSM_USEE_SSL (5)
#define CSSM_USEE_AUTHENTICATION (6)
#define CSSM_USEE_KEYEXCH (7)
#define CSSM_USEE_MEDICAL (8)
#define CSSM_USEE_INSURANCE (9)
#define CSSM_USEE_WEAK (10)
Definitions

CSSM_USEE_NONE

The policy implemented is unspecified.

CSSM_USEE_DOMESTIC

No restrictions are placed on the use of cryptography. Currently, this privilege cannot be given to general purpose cryptographic services manufactured in the United States.

CSSM_USEE_SSL

This exemption indicates that the application is enforcing U.S. export policy in accordance with mechanisms defined by SSL specifications.

CSSM_USEE_KRLE and CSSM_USEE_KRENT

The KRLE and KRENT tags indicate U.S. export permission is tied to key escrow using either law enforcement agencies or a business entity. The Key Recovery service provider must be used in conjunction with CSSM to gain access to strong crypto. Manifests containing key recovery privileges indicates the module is trusted to abide by the rules of key recovery. A user of CDSA may be exempt from key recovery if the privilege is granted to the calling module. In other words, the calling module is trusted to abide by U.S. export restrictions hence may be exempt from key recovery. Modules containing tags identifying use-based exemption, such as FINANCIAL, can avoid key recovery when operating in the FINANCIAL mode.

CSSM_USEE_WEAK

This flag identifies US export policy controlling minimum grade crypto for general purpose use.

Other USEE Tags

The remaining USEE tags map to exemptions granted in the U.S. export regulations.

The CSSM_USEE_TAG values represent exemptions to blanket export policy. Values map to sections in a countries export regulations that permits use of stronger cryptography if the application and constituant parts abide by the stipulations. Applications and their components can be authorized to receive privileges entitling them to stronger cryptographic services.

At the time of publication, the only country known to provide commodity class exemptions to export regulations is the United States of America. The USEE tags defined herein apply to United States export policy. Subsequent export exemptions may be added to the specification, the country to which the tag applies should be included in the documentation.

Application components, CDSA service providers and CSSM may be entrusted to cooperate in the enforcement of a set of policies. The signed manifest will contain a list of privileges the component implements/enforces. The manifest attribute for currently defined exemptions is a name-value pair with name CDSA_USEE. The associated value is a string of base-64 encoded numbers separated by colons.

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 data type defines the application-level protocols that could be supported by a Data Storage Library Module that communicates with service-based storage and directory services. 

typedef  uint32 CSSM_NET_PROTOCOL;
    #define CSSM_NET_PROTO_NONE (0)    /* local */
    #define CSSM_NET_PROTO_CUSTOM (1)  /* proprietary implementation */
    #define CSSM_NET_PROTO_UNSPECIFIED (2) /* implementation default */
    #define CSSM_NET_PROTO_LDAP (3)    /* light weight directory access */
                                       /* protocol */
    #define CSSM_NET_PROTO_LDAPS (4)   /* ldap/ssl where SSL initiates  */
                                       /* the connection */
    #define CSSM_NET_PROTO_LDAPNS (5)  /* ldap where ldap negotiates */
                                       /* an SSL session */
    #define CSSM_NET_PROTO_X500DAP (6) /* X.500 Directory access protocol */
    #define CSSM_NET_PROTO_FTP (7)     /* ftp for cert/crl fetch */
    #define CSSM_NET_PROTO_FTPS (8)    /* ftp/ssl/tls where SSL/TLS   */
                                       /* initiates the connection */
    #define CSSM_NET_PROTO_OCSP (9)    /* online certificate status */
                                       /* protocol */
    #define CSSM_NET_PROTO_CMP (10)    /* the cert request protocol */
                                       /* in PKIX3 */
    #define CSSM_NET_PROTO_CMPS (11)   /* The ssl/tls derivative of CMP */

CSSM_CALLBACK

An application uses this data type to request that an security service module call back into the application for certain cryptographic information. 


 

typedef CSSM_RETURN (CSSMAPI *CSSM_CALLBACK)
    (CSSM_DATA_PTR OutData, void *CallerCtx);
Definitions

OutData (output)

The opaque structured value to be returned by the callback function. The buffer is allocated by the caller and filled in by the callback function. The callback sets the Length field to the length of the value written to the buffer.

CallerCtx (input)

A generic pointer to the context information being returned to its originator. This context was created as state information by a caller, passed as input to another function, returned by that function to the original caller through the callback function. The callback handler uses information in the context to properly handle the callback.

CSSM_CRYPTO_DATA

This data structure is used to encapsulate cryptographic information passed from the application to a service provider module via a callback function. Typical information passed by this callback mechanism includes a seed value for cryptographic operations. 


 

typedef struct cssm_crypto_data {
    CSSM_DATA Param;
    CSSM_CALLBACK Callback;
    void *CallerCtx;
} CSSM_CRYPTO_DATA, *CSSM_CRYPTO_DATA_PTR;
Definitions

Param

The CSSM_DATA structure containing the parameters to be passed as input when invoking the callback function, and the size (in bytes) of those parameters.

Callback

An optional callback routine for a service to invoke to obtain information from the original caller.

CallerCtx

A generic pointer to the context information that should be input to the callback handler when invoking the callback function. The callback handler uses this information to properly handle the callback.

CSSM_WORDID_TYPE

This data type defines common symbols for integer values used to represent sample types, ACL subject types, and authorization tag values. The symbol name can be transported from system to system. The corresponding constant is used for local computation. 


 

typedef sint32 CSSM_WORDID_TYPE;

#define CSSM_WORDID__UNK_ (-1)  /* not in dictionary */
#define CSSM_WORDID__NLU_ (0)   /* not yet looked up */

#define CSSM_WORDID__STAR_ (1)
#define CSSM_WORDID_A (2)
#define CSSM_WORDID_ACL (3)
#define CSSM_WORDID_ALPHA (4)
#define CSSM_WORDID_B (5)
#define CSSM_WORDID_BER (6)
#define CSSM_WORDID_BINARY (7)
#define CSSM_WORDID_BIOMETRIC (8)
#define CSSM_WORDID_C (9)
#define CSSM_WORDID_CANCELED (10)
#define CSSM_WORDID_CERT (11)
#define CSSM_WORDID_COMMENT (12)
#define CSSM_WORDID_CRL (13)
#define CSSM_WORDID_CUSTOM (14)
#define CSSM_WORDID_D (15)
#define CSSM_WORDID_DATE (16)
#define CSSM_WORDID_DB_DELETE (17)
#define CSSM_WORDID_DB_EXEC_STORED_QUERY (18)
#define CSSM_WORDID_DB_INSERT (19)
#define CSSM_WORDID_DB_MODIFY (20)
#define CSSM_WORDID_DB_READ (21)
#define CSSM_WORDID_DBS_CREATE (22)
#define CSSM_WORDID_DBS_DELETE (23)
#define CSSM_WORDID_DECRYPT (24)
#define CSSM_WORDID_DELETE (25)
#define CSSM_WORDID_DELTA_CRL (26)
#define CSSM_WORDID_DER (27)
#define CSSM_WORDID_DERIVE (28)
#define CSSM_WORDID_DISPLAY (29)
#define CSSM_WORDID_DO (30)
#define CSSM_WORDID_DSA (31)
#define CSSM_WORDID_DSA_SHA1 (32)
#define CSSM_WORDID_E (33)
#define CSSM_WORDID_ELGAMAL (34)
#define CSSM_WORDID_ENCRYPT (35)
#define CSSM_WORDID_ENTRY (36)
#define CSSM_WORDID_EXPORT_CLEAR (37)
#define CSSM_WORDID_EXPORT_WRAPPED (38)
#define CSSM_WORDID_G (39)
#define CSSM_WORDID_GE (40)
#define CSSM_WORDID_GENKEY (41)
#define CSSM_WORDID_HASH (42)
#define CSSM_WORDID_HAVAL (43)
#define CSSM_WORDID_IBCHASH (44)
#define CSSM_WORDID_IMPORT_CLEAR (45)
#define CSSM_WORDID_IMPORT_WRAPPED (46)
#define CSSM_WORDID_INTEL (47)
#define CSSM_WORDID_ISSUER (48)
#define CSSM_WORDID_ISSUER_INFO (49)
#define CSSM_WORDID_K_OF_N (50)
#define CSSM_WORDID_KEA (51)
#define CSSM_WORDID_KEYHOLDER (52)
#define CSSM_WORDID_L (53)
#define CSSM_WORDID_LE (54)
#define CSSM_WORDID_LOGIN (55)
#define CSSM_WORDID_LOGIN_NAME (56)
#define CSSM_WORDID_MAC (57)
#define CSSM_WORDID_MD2 (58)
#define CSSM_WORDID_MD2WITHRSA (59)
#define CSSM_WORDID_MD4 (60)
#define CSSM_WORDID_MD5 (61)
#define CSSM_WORDID_MD5WITHRSA (62)
#define CSSM_WORDID_N (63)
#define CSSM_WORDID_NAME (64)
#define CSSM_WORDID_NDR (65)
#define CSSM_WORDID_NHASH (66)
#define CSSM_WORDID_NOT_AFTER (67)
#define CSSM_WORDID_NOT_BEFORE (68)
#define CSSM_WORDID_NULL (69)
#define CSSM_WORDID_NUMERIC (70)
#define CSSM_WORDID_OBJECT_HASH (71)
#define CSSM_WORDID_ONE_TIME (72)
#define CSSM_WORDID_ONLINE (73)
#define CSSM_WORDID_OWNER (74)
#define CSSM_WORDID_P (75)
#define CSSM_WORDID_PAM_NAME (76)
#define CSSM_WORDID_PASSWORD (77)
#define CSSM_WORDID_PGP (78)
#define CSSM_WORDID_PREFIX (79)
#define CSSM_WORDID_PRIVATE_KEY (80)
#define CSSM_WORDID_PROMPTED_PASSWORD (81)
#define CSSM_WORDID_PROPAGATE (82)
#define CSSM_WORDID_PROTECTED_BIOMETRIC (83)
#define CSSM_WORDID_PROTECTED_PASSWORD (84)
#define CSSM_WORDID_PROTECTED_PIN (85)
#define CSSM_WORDID_PUBLIC_KEY (86)
#define CSSM_WORDID_PUBLIC_KEY_FROM_CERT (87)
#define CSSM_WORDID_Q (88)
#define CSSM_WORDID_RANGE (89)
#define CSSM_WORDID_REVAL (90)
#define CSSM_WORDID_RIPEMAC (91)
#define CSSM_WORDID_RIPEMD (92)
#define CSSM_WORDID_RIPEMD160 (93)
#define CSSM_WORDID_RSA (94)
#define CSSM_WORDID_RSA_ISO9796 (95)
#define CSSM_WORDID_RSA_PKCS (96)
#define CSSM_WORDID_RSA_PKCS_MD5 (97)
#define CSSM_WORDID_RSA_PKCS_SHA1 (98)
#define CSSM_WORDID_RSA_PKCS1 (99)
#define CSSM_WORDID_RSA_PKCS1_MD5 (100)
#define CSSM_WORDID_RSA_PKCS1_SHA1 (101)
#define CSSM_WORDID_RSA_PKCS1_SIG (102)
#define CSSM_WORDID_RSA_RAW (103)
#define CSSM_WORDID_SDSIV1 (104)
#define CSSM_WORDID_SEQUENCE (105)
#define CSSM_WORDID_SET (106)
#define CSSM_WORDID_SEXPR (107)
#define CSSM_WORDID_SHA1 (108)
#define CSSM_WORDID_SHA1WITHDSA (109)
#define CSSM_WORDID_SHA1WITHECDSA (110)
#define CSSM_WORDID_SHA1WITHRSA (111)
#define CSSM_WORDID_SIGN (112)
#define CSSM_WORDID_SIGNATURE (113)
#define CSSM_WORDID_SIGNED_NONCE (114)
#define CSSM_WORDID_SIGNED_SECRET (115)
#define CSSM_WORDID_SPKI (116)
#define CSSM_WORDID_SUBJECT (117)
#define CSSM_WORDID_SUBJECT_INFO (118)
#define CSSM_WORDID_TAG (119)
#define CSSM_WORDID_THRESHOLD (120)
#define CSSM_WORDID_TIME (121)
#define CSSM_WORDID_URI (122)
#define CSSM_WORDID_VERSION (123)
#define CSSM_WORDID_X509_ATTRIBUTE (124)
#define CSSM_WORDID_X509V1 (125)
#define CSSM_WORDID_X509V2 (126)
#define CSSM_WORDID_X509V3 (127)
#define CSSM_WORDID_X9_ATTRIBUTE (128)

#define CSSM_WORDID_VENDOR_START (0x00010000)
#define CSSM_WORDID_VENDOR_END (0xFFFF0000)

Definitions
Only those letters that are used in key or signature definitions are defined:

CSSM_LIST_ELEMENT_TYPE

This data element defines the type of a list element. There are only two possibilities: a byte string or a sub-list. 


 

typedef uint32 CSSM_LIST_ELEMENT_TYPE, *CSSM_LIST_ELEMENT_TYPE_PTR;

#define CSSM_LIST_ELEMENT_DATUM   (0x00)
#define CSSM_LIST_ELEMENT_SUBLIST (0x01)
#define CSSM_LIST_ELEMENT_WORDID  (0x02)

CSSM_LIST_TYPE

This extensible list defines the type of linked lists used to contain the parsed elements of a certificate. 


 

typedef uint32 CSSM_LIST_TYPE,  * CSSM_LIST_TYPE_PTR;

#define CSSM_LIST_TYPE_UNKNOWN  (0)
#define CSSM_LIST_TYPE_CUSTOM   (1)
#define CSSM_LIST_TYPE_SEXPR    (2)

CSSM_LIST

This structure defines a linked list. It is defined with the intention of holding parsed certificates. The data structure definition is general and can be used for other lists as indicated in the ListType. 


 

typedef struct cssm_list_element *CSSM_LIST_ELEMENT_PTR;

typedef struct cssm_list {
    CSSM_LIST_TYPE ListType;      /* type of this list */ 
    CSSM_LIST_ELEMENT_PTR Head;   /* head of the list */
    CSSM_LIST_ELEMENT_PTR Tail;   /* tail of the list */
} CSSM_LIST, *CSSM_LIST_PTR;
Definitions

ListType

The type of linked list whose root in contained in this structure.

Head

A pointer to the CSSM_LIST_ELEMENT that forms the head of the linked list.

Tail

A pointer to the CSSM_LIST_ELEMENT that forms the tail of the linked list.

CSSM_LIST_ELEMENT

This structure defines a single element in a linked list. This structure is defined with the intention of holding parsed certificate elements, but the data structure definition is general and can be used for other parsed or decomposed objects. Each list element contains an immediate data item or a sub-list. Immediate data values can be represented by a WordID, or a Word of type CSSM_DATA, or both. When both a WordID and a CSSM_DATA word are provided, the two values should be related by a Dictionary that binds the two values under the Dictionary mapping. 


 

typedef struct cssm_list_element {
    struct cssm_list_element *NextElement;  /* next list element */
        
    CSSM_WORDID_TYPE WordID;    /* integer identifier associated */
                                /* with a Word value */
    CSSM_LIST_ELEMENT_TYPE  ElementType;
    union {
        CSSM_LIST Sublist;      /* sublist */
        CSSM_DATA Word;         /* a byte-string */
    } Element;
} CSSM_LIST_ELEMENT;
Definitions

NextElement

A pointer to the next CSSM_LIST_ELEMENT in the list.

WordID

An identifier associated with the Word or Sublist in this element. Valid values for WordID are defined for each ListType. If the list is of type CSSM_LIST_TYPE_SEXPR, then each list or sub-list must start with a pre-defined type-indicator. The WordID is an integer representation of a predefined dictionary word. The meaning of WordID depends on the ElementType as defined in the following table:

Element Type Meaning of WordID
CSSM_LIST_ELEMENT_DATUM WordID is associated with the value in Word. If the pre-defined dictionary does not contain a mapping from the value of Word to a WordID, then WordID is zero.
CSSM_LIST_ELEMENT_SUBLIST WordID is associated with the Word that begins the Sublist. If the pre-defined dictionary does not contain a mapping from the value of Word to a WordID, then WordID is zero.
CSSM_LIST_ELEMENT_WORDID WordID is the value of the list element. Word and Sublist are empty.

ElementType

Specifies whether the Element is a datum or a sub-list.

Element

The list element can contain zero values or one value. If a value is present it is of one of two types:

CSSM_TUPLE

This structure defines a full 5-tuple, representing one certificate (or a fragment of a more complex certificate). 


 

typedef struct {                /* 5-tuple definition */
    CSSM_LIST Issuer;           /* issuer, or empty if ACL */
    CSSM_LIST Subject;          /* subject */
    CSSM_BOOL Delegate;         /* permission to delegate */
    CSSM_LIST AuthorizationTag; /* authorization field */
    CSSM_LIST ValidityPeriod;   /* validity information (dates) */
} CSSM_TUPLE, *CSSM_TUPLE_PTR;
Definitions

Issuer

A CSSM_LIST structure containing a parse list representing the entity that issued the tuple. If this tuple represents an ACL, the CSSM_LIST structure must contain a NULL list.

Subject

A CSSM_LIST structure containing a parse list representing the subject entity for this tuple.

Delegate

A CSSM_BOOL value indicating whether the Subject entity is permitted to delegate the authorizations granted by AuthorizationTag during the ValidityPeriod to other entities.

AuthorizationTag

A CSSM_LIST structure containing a parse list representing the authorizations granted to the Subject by the Issuer for ValidityPeriod time. The meaning of the field is based on an application domain.

ValidityPeriod

A CSSM_LIST structure containing a parse list representing the time period for which the Issuer has granted authorizations to the Subject.

CSSM_TUPLEGROUP

This data structure contains a set of CSSM_TUPLE structures. The tuples are grouped from the purpose of input-to or output-from a function or service. 


 

typedef struct cssm_tuplegroup {
    uint32 NumberOfTuples;
    CSSM_TUPLE_PTR Tuples;
} CSSM_TUPLEGROUP, *CSSM_TUPLEGROUP_PTR;
Definitions

NumberOfTuples

The number of entries in the array Tuples.

Tuples

A pointer to an ordered array of CSSM_TUPLE structures. Each structure contains a single, nested tuple.

CSSM_SAMPLE_TYPE

This data type defines integer values identifying the types of samples a caller can present to a service provider. Samples are used to authenticate the caller and to verify authorization to access a resource. Authentication is typically based on zero or more samples and zero or more certificates. 


 

typedef CSSM_WORDID_TYPE CSSM_SAMPLE_TYPE;

#define CSSM_SAMPLE_TYPE_PASSWORD CSSM_WORDID_PASSWORD
#define CSSM_SAMPLE_TYPE_PROTECTED_PASSWORD CSSM_WORDID_PROTECTED_PASSWORD
#define CSSM_SAMPLE_TYPE_PROMPTED_PASSWORD CSSM_WORDID_PROMPTED_PASSWORD
#define CSSM_SAMPLE_TYPE_SIGNED_NONCE CSSM_WORDID_SIGNED_NONCE
#define CSSM_SAMPLE_TYPE_SIGNED_SECRET CSSM_WORDID_SIGNED_SECRET 
#define CSSM_SAMPLE_TYPE_BIOMETRIC CSSM_WORDID_BIOMETRIC
#define CSSM_SAMPLE_TYPE_PROTECTED_BIOMETRIC CSSM_WORDID_PROTECTED_BIOMETRIC
#define CSSM_SAMPLE_TYPE_THRESHOLD CSSM_WORDID_THRESHOLD

CSSM_SAMPLE_TYPE General Description
CSSM_SAMPLE_TYPE_PASSWORD The sample is a password or passphrase value.
CSSM_SAMPLE_TYPE_HASHED_PASSWORD The sample is a password or passphrase value. The service provider receiving this value computes its hash and uses the hash value as the gathered sample.
CSSM_SAMPLE_TYPE_PROMPTED_PASSWORD The sample is a password or passphrase with an associated prompt value that can be present to an application when requesting this sample.
CSSM_SAMPLE_TYPE_PROTECTED_PASSWORD The sample is a password or passphrase gathered indirectly from a service provider operating a protected data acquisition path to acquire and verify this sample value.
CSSM_SAMPLE_TYPE_SIGNED_NONCE A service provider presents a nonce to an application. The application signs the nonce with its private key. The resulting signed nonce is the sample value.
CSSM_SAMPLE_TYPE_SIGNED_SECRET The application and the service provider have a shared secret. The application signs the shared secret with its private key. The signed secret is the sample value.
CSSM_SAMPLE_TYPE_BIOMETRIC The sample is a biometric data sample provided by the caller and passed through the API.
CSSM_SAMPLE_TYPE_PROMPTED_BIOMETRIC The sample is a biometric data sample with an associated prompt value that can be present to an application when requesting this sample.
CSSM_SAMPLE_TYPE_PROTECTED_BIOMETRIC The sample is a biometric data sample, gathered indirectly from a service provider operating a protected data acquisition path to acquire and verify this sample value.
CSSM_SAMPLE_TYPE_THRESHOLD The sample is a choice of k-of-n samples. Each option is one of the defined sample types.

CSSM_SAMPLE

This structure contains a typed sample and a Globally Unique ID identifying a service provider module that can verify, authenticate, and process the sample value. An application uses this structure to provide actual sample values or references to sample values to a service provider. An application uses this structure in two situations:

When using this structure as an input parameter to a CDSA function, the structure can:

When using this structure as a response to a Challenge callback from a service provider, the structure must contain the sample type and sample value as immediate data values. 



 

typedef struct cssm_sample {
    CSSM_LIST TypedSample;
    const CSSM_SUBSERVICE_UID *Verifier;
} CSSM_SAMPLE, *CSSM_SAMPLE_PTR;
Definitions

TypedSample

A CSSM_LIST structure containing one or two elements. The first element is a sample type. The second element is an optional sample value. The immediate sample value in the list can be one of many types. Samples of type CSSM_SAMPLE_TYPE_PROTECTED_xyz can not be provided as an immediate value in this structure. A sample of this type is acquired through a protected path managed by the specified Verifier. In this case, the sample type is the only element in this list. Also the Verifier must be specified. All other sample types can be acquired by invoking a callback function. In this case the sample is not provided as an immediate value and this list contains a single element, the sample type. The following table defines the CSSM_LIST elements that can be presented under each valid use scenario.

CSSM_SAMPLE_ TYPE_PASSWORD CSSM_LIST Contents Verifier Required?
Immediate Type and Value Form A two-element list
First element: WordID = CSSM_SAMPLE_TYPE_PASSWORD
Second element: Word is a CSSM_DATA structure referencing a non-terminated <password string> value of specified length 		No
Immediate Type and Request for Callback Form A one-element list
First element: WordID = CSSM_SAMPLE_TYPE_PASSWORD 		No
Response to a Challenge callback A two-element list
First element: WordID = CSSM_SAMPLE_TYPE_PASSWORD
Second element: Word is a CSSM_DATA structure referencing a non-terminated <password string> value of specified length 		No
CSSM_SAMPLE_ TYPE_HASHED_ PASSWORD CSSM_LIST Contents Verifier Required?
Response to a Challenge callback A two-element list
First element: WordID = CSSM_SAMPLE_TYPE_HASHED_PASSWORD
Second element: Word is a CSSM_DATA structure referencing a non-terminated <password string> value of specified length 		No
CSSM_SAMPLE_ TYPE_PROMPTED_ PASSWORD CSSM_LIST Contents Verifier Required?
Response to a Challenge callback A two-element list
First element: WordID = CSSM_SAMPLE_TYPE_PROMPTED_PASSWORD
Second element: Word is a CSSM_DATA structure referencing a non-terminated <password string> value of specified length 		No
CSSM_SAMPLE_ TYPE_PROTECTED_ PASSWORD CSSM_LIST Contents Verifier Required?
Immediate Type and Protected Path Acquisition Form A one-element list
First element: WordID = CSSM_SAMPLE_TYPE_PROTECTED_PASSWORD 		Optional
CSSM_SAMPLE_ TYPE_SIGNED_ NONCE CSSM_LIST Contents Verifier Required?
Immediate Type and Request for Callback Form A one-element list
First element: WordID = CSSM_SAMPLE_TYPE_SIGNED_NONCE 		Yes
Response to a Challenge callback A two-element list
First element: WordID = CSSM_SAMPLE_TYPE_SIGNED_NONCE
Second element: Word is a CSSM_DATA structure referencing a < signed nonce > value of specified length 		Yes
CSSM_SAMPLE_ TYPE_SIGNED_ SECRET CSSM_LIST Contents Verifier Required?
Immediate Type and Value Form A two-element list
First element: WordID = CSSM_SAMPLE_TYPE_SIGNED_SECRET
Second element: Word is a CSSM_DATA structure referencing a < signed secret > value of specified length 		Yes
Immediate Type and Request for Callback Form A one-element list
First element: WordID = CSSM_SAMPLE_TYPE_SIGNED_SECRET 		Yes
Response to a Challenge callback A two-element list
First element: WordID = CSSM_SAMPLE_TYPE_SIGNED_SECRET
Second element: Word is a CSSM_DATA structure referencing a < signed secret > value of specified length 		Yes
CSSM_SAMPLE_ TYPE_BIOMETRIC CSSM_LIST Contents Verifier Required?
Immediate Type and Value Form A two-element list
First element: WordID = CSSM_SAMPLE_TYPE_BIOMETRIC
Second element: Word is a CSSM_DATA structure referencing a < biometric template > value of specified length 		Yes
Immediate Type and Request for Callback Form A one-element list
First element: WordID = CSSM_SAMPLE_TYPE_BIOMETRIC 		Yes
Response to a Challenge callback A two-element list
First element: WordID = CSSM_SAMPLE_TYPE_BIOMETRIC
Second element: Word is a CSSM_DATA structure referencing a < biometric template > value of specified length 		Yes
CSSM_SAMPLE_ TYPE_PROMPTED_ BIOMETRIC CSSM_LIST Contents Verifier Required?
Response to a Challenge callback A two-element list
First element: WordID = CSSM_SAMPLE_TYPE_PROMPTED_PASSWORD
Second element: Word is a CSSM_DATA structure referencing a < biometric template > value of specified length 		Yes
CSSM_SAMPLE_ TYPE_PROTECTED_ BIOMETRIC CSSM_LIST Contents Verifier Required?
Immediate Type and Protected Path Acquisition Form A one-element list
First element: WordID = CSSM_SAMPLE_TYPE_PROTECTED_BIOMETRIC 		Yes

Verifier

A pointer to the persistent identifier of a service provider module that is capable of identifying, authenticating or verifying the sample. This value is required in all cases except the immediate value password.

CSSM_SAMPLEGROUP

This structure contains a group of related samples. 


 

typedef struct cssm_samplegroup {
    uint32 NumberOfSamples;
    const CSSM_SAMPLE *Samples;
} CSSM_SAMPLEGROUP, *CSSM_SAMPLEGROUP_PTR;
Definitions

NumberOfSamples

The number of samples in the array Samples.

Samples

A pointer to an array of CSSM_SAMPLE structures.

CSSM_CHALLENGE_CALLBACK

This type defines the form of the callback function a service provider module must use to challenge a requester to acquire samples during an authentication and authorization verification procedure. 


 

typedef CSSM_RETURN (CSSMAPI * CSSM_CHALLENGE_CALLBACK)
    (const CSSM_LIST *Challenge,
    CSSM_SAMPLEGROUP_PTR Response,
    void *CallerCtx,
    const CSSM_MEMORY_FUNCS *MemFuncs);
Definitions

Challenge (input)

A pointer to a CSSM_LIST structure containing a typed challenge. The type is specified as the first element in the list. Samples acquired through protected path sources can not be gathered through the callback mechanism, hence samples of type CSSM_SAMPLE_TYPE_PROTECTED_xyz never occur in a challenge list. If more than one type of sample is applicable, then the first list element indicates the type CSSM_SAMPLE_TYPE_THRESHOLD. The first list element is the type of sample the service provider is challenging the original requester to present. The second element provides optional information to assist the requester in replying to the challenge. For example, when requesting a sample of type CSSM_SAMPLE_TYPE_SIGNED_NONCE, the service provider must provide a nonce to be signed by the requester. The list of possible challenge types, their parameters, and associated responses are summarized in a table below.

Response (output)

A pointer to a CSSM_SAMPLEGROUP structure containing the samples returned in response to the challenge. Each sample includes a CSSM_LIST structure and an optional UID for a Verifier. The first element of the list is the type of the sample. The returned sample types must be appropriate for the Challenge. The list of possible challenge types, their parameters, and associated responses are summarized in a table below.

CallerCtx (input)

A generic pointer to context information that was provided by the original requester and is being returned to its originator.

MemFuncs (input)

A pointer to a CSSM_MEMORY_FUNCS structure. The challenge callback must use the functions in this structure to allocate memory returned to the challenger in the Response structure.

CSSM_SAMPLE_ TYPE_PASSWORD CSSM_LIST Contents
Challenge form A one-element list
First element: WordID = CSSM_SAMPLE_TYPE_PASSWORD
Response form A two-element list
First element: WordID = CSSM_SAMPLE_TYPE_PASSWORD
Second element: Word is a CSSM_DATA structure referencing a non-terminated <password string> value of specified length
CSSM_SAMPLE_ TYPE_HASHED_ PASSWORD CSSM_LIST Contents
Challenge form A one-element list
First element: WordID = CSSM_SAMPLE_TYPE_HASHED_PASSWORD
Response form A two-element list
First element: WordID = CSSM_SAMPLE_TYPE_HASHED_PASSWORD
Second element: Word is a CSSM_DATA structure referencing a non-terminated <password string> value of specified length
T&  
cb cb  
l l.  
CSSM_SAMPLE_ TYPE_PROMPTED_ PASSWORD CSSM_LIST Contents
Challenge form A two-element list
First element: WordID = CSSM_SAMPLE_TYPE_PROMPTED_PASSWORD
Second element: Word is a CSSM_DATA structure referencing a non-terminated <prompt string> value of specified length
Response form A two-element list
First element: WordID = CSSM_SAMPLE_TYPE_PROMPTED_PASSWORD
Second element: Word is a CSSM_DATA structure referencing a non-terminated <password string> value of specified length
CSSM_SAMPLE_ TYPE_SIGNED_ NONCE CSSM_LIST Contents
Challenge form A two-element list
First element: WordID = CSSM_SAMPLE_TYPE_SIGNED_NONCE
Second element: Word is a CSSM_DATA structure referencing a <nonce to be signed> value of specified length
Response form A two-element list
First element: WordID = CSSM_SAMPLE_TYPE_SIGNED_NONCE
Second element: Word is a CSSM_DATA structure referencing a < signed nonce > value of specified length
CSSM_SAMPLE_ TYPE_SIGNED_ SECRET CSSM_LIST Contents
Challenge form A one-element list
First element: WordID = CSSM_SAMPLE_TYPE_SIGNED_SECRET
Response form A two-element list
First element: WordID = CSSM_SAMPLE_TYPE_SIGNED_SECRET
Second element: Word is a CSSM_DATA structure referencing a < signed secret > value of specified length
CSSM_SAMPLE_ TYPE_BIOMETRIC CSSM_LIST Contents
Challenge form A one-element list
First element: WordID = CSSM_SAMPLE_TYPE_BIOMETRIC
Response form A two-element list
First element: WordID = CSSM_SAMPLE_TYPE_BIOMETRIC
Second element: Word is a CSSM_DATA structure referencing a < biometric template > value of specified length
CSSM_SAMPLE_ TYPE_PROMPTED_ BIOMETRIC CSSM_LIST Contents
Challenge form A two-element list
First element: WordID = CSSM_SAMPLE_TYPE_PROMPTED_BIOMETRIC
Second element: Word is a CSSM_DATA structure referencing a non-terminated <prompt string> value of specified length
Response form A two-element list
First element: WordID = CSSM_SAMPLE_TYPE_PROMPTED_BIOMETRIC
Second element: Word is a CSSM_DATA structure referencing a < biometric template > value of specified length
CSSM_SAMPLE_ TYPE_THRESHOLD CSSM_LIST Contents
Challenge form An (n+3)-element list
First element: WordID = CSSM_SAMPLE_TYPE_THRESHOLD
Second element: WordID = <k value>
Third element: WordID = <n value>
Fourth element: Sublist = (typed_challenge_list-1)
Fifth element: Sublist = (typed_challenge_list-2)
 . . .
n+3rd element: Sublist = (typed_challenge_list-n)
Response form A k-entry array of sample responses, each responding to one of the typed challenges in the threshold list

CSSM_CERT_TYPE

This variable specifies the type of certificate format supported by a certificate library. They are expected to define such well-known certificate formats as X.509 Version 3 and SDSI, as well as custom certificate formats. The list of enumerated values can be extended for new types by defining a label with an associated value greater than CSSM_CL_CUSTOM_CERT_TYPE. 

typedef enum cssm_cert_type {
    CSSM_CERT_UNKNOWN = 0x00,
    CSSM_CERT_X_509v1 = 0x01,
    CSSM_CERT_X_509v2 = 0x02,
    CSSM_CERT_X_509v3 = 0x03,
    CSSM_CERT_PGP     = 0x04,
    CSSM_CERT_SPKI    = 0x05,
    CSSM_CERT_SDSIv1  = 0x06,
    CSSM_CERT_Intel   = 0x08,
    CSSM_CERT_X_509_ATTRIBUTE = 0x09, /* X.509 attribute cert */
    CSSM_CERT_X9_ATTRIBUTE = 0x0A,    /* X9 attribute cert    */
    CSSM_CERT_TUPLE   = 0x0B,
    CSSM_CERT_ACL_ENTRY = 0x0C,
    CSSM_CERT_MULTIPLE = 0x7FFE,
    CSSM_CERT_LAST = 0x7FFF
} CSSM_CERT_TYPE, *CSSM_CERT_TYPE_PTR;

/* Applications wishing to define their own custom certificate
 * type should define and publicly document a uint32 value greater
 * than the CSSM_CL_CUSTOM_CERT_TYPE */
#define CSSM_CL_CUSTOM_CERT_TYPE 0x08000

CSSM_CERT_ENCODING

This variable specifies the certificate encoding format supported by a certificate library. 

typedef enum cssm_cert_encoding {
    CSSM_CERT_ENCODING_UNKNOWN  = 0x00,
    CSSM_CERT_ENCODING_CUSTOM   = 0x01,
    CSSM_CERT_ENCODING_BER      = 0x02,
    CSSM_CERT_ENCODING_DER      = 0x03,
    CSSM_CERT_ENCODING_NDR      = 0x04,
    CSSM_CERT_ENCODING_SEXPR    = 0x05,
    CSSM_CERT_ENCODING_PGP      = 0x06,
    CSSM_CERT_ENCODING_MULTIPLE = 0x7FFE,
    CSSM_CERT_ENCODING_LAST     = 0x7FFF
} CSSM_CERT_ENCODING, *CSSM_CERT_ENCODING_PTR;


/* Applications wishing to define their own custom certificate
 * encoding should create a uint32 value greater than the
 * CSSM_CL_CUSTOM_CERT_ENCODING */
#define CSSM_CL_CUSTOM_CERT_ENCODING 0x8000

CSSM_ENCODED_CERT

This structure contains a pointer to a certificate in its encoded representation. The certificate is stored as a single contiguous byte array referenced by CertBlob. The length of the byte array is contained in the Length subfield of the CertBlob. The type and encoding of the certificate format are also contained in the structure. 

typedef struct cssm_encoded_cert {
    CSSM_CERT_TYPE CertType ;         /* type of certificate */
    CSSM_CERT_ENCODING CertEncoding ; /* encoding for this packed cert */
    CSSM_DATA CertBlob ;              /* packed cert */ 
} CSSM_ENCODED_CERT, *CSSM_ENCODED_CERT_PTR ;
Definition

CertType

Indicates the type of the certificate referenced by CertBlob.

CertEncoding

Indicates the encoding of the certificate referenced by CertBlob.

CertBlob

A two field structure containing a reference to a certificate in its opaque data blob format and the length of the byte array that contains the certificate blob.

CSSM_CERT_PARSE_FORMAT

This type defines an extensible list of formats for parsed certificates. 

typedef uint32 CSSM_CERT_PARSE_FORMAT; *CSSM_CERT_PARSE_FORMAT_PTR;

#define CSSM_CERT_PARSE_FORMAT_NONE      (0x00)
#define CSSM_CERT_PARSE_FORMAT_CUSTOM    (0x01) /* void* */
#define CSSM_CERT_PARSE_FORMAT_SEXPR     (0x02) /* CSSM_LIST */
#define CSSM_CERT_PARSE_FORMAT_COMPLEX   (0x03) /* void* */
#define CSSM_CERT_PARSE_FORMAT_OID_NAMED (0x04) /* CSSM_FIELDGROUP */
#define CSSM_CERT_PARSE_FORMAT_TUPLE     (0x05) /* CSSM_TUPLE */
#define CSSM_CERT_PARSE_FORMAT_MULTIPLE  (0x7FFE)
        /* multiple forms, each cert carries a parse format indicator */
#define CSSM_CERT_PARSE_FORMAT_LAST      (0x7FFF)

 /* Applications wishing to define their own custom parse
    format should create a * uint32 value greater than the
    CSSM_CL_CUSTOM_CERT_PARSE_FORMAT */

#define CSSM_CL_CUSTOM_CERT_PARSE_FORMAT (0x8000)

CSSM_PARSED_CERT

This structure contains a parsed representation of a certificate. It will likely have many parts, accessed by pointer. The developer must use a type cast to convert ParsedCert to the appropriate type, corresponding to the type and encoding of the certificate format as indicated in the structure. 

typedef struct cssm_parsed_cert {
    CSSM_CERT_TYPE CertType ;  /* certificate type */
    CSSM_CERT_PARSE_FORMAT ParsedCertFormat ; 
                               /* struct of ParsedCert */
    void *ParsedCert ;         /* parsed cert (to be typecast) */
} CSSM_PARSED_CERT, *CSSM_PARSED_CERT_PTR ;
Definition

CertType

Indicates the type of certificate that had been parsed to yield ParsedCert.

ParsedCertFormat

Indicates the structure and format representation of the parsed certificate. If the parsed representation is not available, then this value is CSSM_CERT_PARSE_FORMAT_NONE.

ParsedCert

A pointer to a parsed certificate represented in the structure and format indicated by ParsedCertFormat.

CSSM_CERTPAIR

This structure contains a certificate in two representations:

The representation used for each form (such as type, encoding, and format) is included in the applicable substructure. At least one of the two representations must be present at any given time. The omitted representation is indicated by a NULL pointer value. When the omitted alternate representation is generated, it can be added to this structure at any time. When both representations are included, those representations must be equivalent forms of a single certificate. This structure is provided for performance and convenience reasons. For security purposes, however, only a signed certificate (necessarily encoded) can have its signature checked. 


typedef struct cssm_cert_pair {
    CSSM_ENCODED_CERT EncodedCert; /* an encoded certificate blob */
    CSSM_PARSED_CERT ParsedCert;   /* equivalent parsed certificate */
} CSSM_CERT_PAIR, *CSSM_CERT_PAIR_PTR;
Definition

EncodedCert

A CSSM_ENCODED_CERT structure containing:

The certificate can have an equivalent parsed representation. If the parsed representation is provided it is contained in ParsedCert.

ParsedCert

A CSSM_PARSED_CERT structure containing:

The certificate can have an equivalent packed representation. If the packed representation is provided it is contained in EncodedCert.

CSSM_CERTGROUP_TYPE

This extensible list defines the type of a certificate group. A group can contain a single type of certificate or multiple types of certificates. Each certificate in the group can be represented in an encoded representation, a parsed representation, or both. 

typedef uint32 CSSM_CERTGROUP_TYPE, *CSSM_CERTGROUP_TYPE_PTR;

#define CSSM_CERTGROUP_DATA          (0x00)
#define CSSM_CERTGROUP_ENCODED_CERT  (0x01)
#define CSSM_CERTGROUP_PARSED_CERT   (0x02)
#define CSSM_CERTGROUP_CERT_PAIR     (0x03)

CSSM_CERTGROUP

This structure contains an arbitrary number of certificates. The group can be restricted to a single type of certificate or can contain multiple types of certificates as indicated in the CertGroupType field. For legacy compatibility, this structure includes the previous definition. In that form, this is a list of encoded, signed certificates all of the same type and all in the same encoding. If one has a group of certificates of mixed types, they can be either encoded, parsed or both.

Each certificate in the mixed group can be represented in one or two forms:

When using encoded and parsed representations, the specific format used for each certificate and each representation must be included in the applicable substructure. At least one of the two representations must be present in each list entry. When a single entry includes both representations, those representations are assumed but not guaranteed to be equivalent representations of a single certificate.

The number of certificates in the group is contained in the structure. 


typedef struct cssm_certgroup {
    CSSM_CERT_TYPE CertType;
    CSSM_CERT_ENCODING CertEncoding; 
        uint32 NumCerts ;       /* # of certificates in this list */
    union {
        CSSM_DATA_PTR CertList; /* legacy list of single type
                                   certificate blobs */
        CSSM_ENCODED_CERT_PTR EncodedCertList ;
                                /* list of multi-type
                                   certificate blobs */
        CSSM_PARSED_CERT_PTR ParsedCertList;
                                /* list of multi-type parsed certs */
        CSSM_CERT_PAIR_PTR PairCertList;
                                /* list of single or multi-type certs 
                                   with two representations:
                                   blob and parsed */
    } GroupList;
    CSSM_CERTGROUP_TYPE CertGroupType;
                                /* type of structure in the GroupList */
    void *Reserved ;            /* reserved for implementation
                                   dependent use */
} CSSM_CERTGROUP, *CSSM_CERTGROUP_PTR;
Definition

CertType

If all certificates in the GroupList are of the same type, this variable lists that type. Otherwise, the type should be CSSM_CERT_MULTIPLE.

CertEncoding

If all certificates in the GroupList are of the same encoding, this variable gives that encoding. Otherwise, the type should be CSSM_CERT_ENCODING_MULTIPLE.

NumCerts

The number of entries in the GroupList array.

GroupList

An array of certificates. The array contains exactly NumCerts entries. CertGroupType defines the type of structure contained in the array. The group types are described as follows:

CertGroupType Value Field Name Description
CSSM_CERTGROUP_DATA CertList (Legacy) A pointer to an array of CSSM_DATA structures. Each CertList array entry references a single certificate structure and indicates the length of the structure. A single type and encoding apply to all certificates in this group. The type and encoding are indicated in CertType and CertEncoding respectively.
CSSM_CERTGROUP_
ENCODED_CERT 		EncodedCertList A pointer to an array of CSSM_ENCODED_CERT structures. Each EncodedCertList array entry references a certificate in an opaque, single byte-array representation, and describes the format of the certificate data contained in the byte-array. Each certificate encoding and type can be distinct, as indicated in each array element.
CSSM_CERTGROUP_
PARSED_CERT 		ParsedCertList A pointer to an array of CSSM_PARSED_CERT structures. Each ParsedCertList array entry references a certificate in a parsed representation, and indicates the certificate type and parse format of that certificate.
CSSM_CERTGROUP_
CERT_PAIR 		PairCertList A pointer to an array of CSSM_CERT_PAIR structures.
Each PairCertList array entry aggregates two certificate representations: an opaque encoded certificate blob, and a parsed certificate representation.

At least one of the two representations must be present in each array entry. If both are present, they are assumed but not guaranteed to correspond to one another. If the parsed form is being used in a security sensitive operation, then it must have been verified against the packed, encoded form, whose signature must have been verified

Reserved

This field is reserved for future use.

CSSM_BASE_CERTS

This structure contains a group of zero or more certificates and optional handles identifying a Trust Policy Service Provider and a Certificate Library Service Provider that could be used to verify these certificates. 


 

typedef struct cssm_base_certs {
    CSSM_TP_HANDLE TPHandle;
    CSSM_CL_HANDLE CLHandle;
    const CSSM_CERTGROUP Certs;
} CSSM_BASE_CERTS, *CSSM_BASE_CERTS_PTR;
Definitions

TPHandle

The handle of a Trust Policy Service Provider that could be used to verify the certificates contained in the certificate group Certs. This handle is optional.

CLHandle

The handle of a Certificate Library Service Provider that could be used to verify the certificates contained in the certificate group Certs. This handle is optional.

Certs

A CSSM_CERTGROUP structure containing zero or more typed certificates.

CSSM_ACCESS_CREDENTIALS

This data structure contains the set of credentials a caller must provide when initiating a request for authorized access to a resource managed by a service provider module. The caller can present a set of certificates, and a set of samples. The certificates are optional, but if provided they must be immediate values included with the structure. Typically at least one sample is required, but if access is already authorized, then samples are not required. When samples are required, they can be: 


 

typedef struct cssm_access_credentials {
    CSSM_STRING EntryTag;
    CSSM_BASE_CERTS BaseCerts;
    CSSM_SAMPLEGROUP Samples;
    CSSM_CHALLENGE_CALLBACK Callback;
    void *CallerCtx;
} CSSM_ACCESS_CREDENTIALS, *CSSM_ACCESS_CREDENTIALS_PTR;
Definitions

EntryTag

An optional, user-defined tag value identifying the target ACL entry the caller is attempting to satisfy. If the caller does not know the tag value associated with a particular ACL entry, then this value should be NULL. The tag value is a human-readable value specified when an ACL entry is created. A caller can use this value to selectively identify one or more ACL entries. The value may not be unique among entries in a single ACL.

BaseCerts

A CSSM_BASE_CERT structure containing zero or more typed certificates. The structure also contains optional handles identifying a CL service module and a TP service module that can be used to verify the group of certificates. All certificates required by a service provider must be provided as immediate values in this structure. If the service provider does not require any certificates, this group should contain zero elements.

Samples

An array of CSSM_SAMPLE structures. The array contains zero or more samples. Each sample contains a CSSM_LIST structure and an optional SUBSERVICE_UID. Each CSSM_LIST structure contains a sample type and an optional sample value. If the sample value is not contained in the list, or the sample is not acquirable through a protected mechanism, the Callback function must be provided. A service provider uses the callback to obtain a sample of the type specified in the list.

Callback

A CSSM_CHALLENGE_CALLBACK function pointer. The service provider module can use this callback function to obtain a sample value of the type specified in a SAMPLE list. If the callback function is provided and Samples is NULL, then the service provider must invoke the callback providing a complete list of applicable Response options in the Challenge parameter of the callback function.

CallerCtx

A requester-defined structure that a service provider module must pass to the caller as an input parameter when invoking the Callback function.

CSSM_ACL_SUBJECT_TYPE

This type defines symbol names for the valid subject types contained in an ACL entry. ACL entries containing these subject types can be: 


 

typedef sint32 CSSM_ACL_SUBJECT_TYPE

#define CSSM_ACL_SUBJECT_TYPE_ANY CSSM_WORDID__STAR_
#define CSSM_ACL_SUBJECT_TYPE_THRESHOLD  CSSM_WORDID_THRESHOLD
#define CSSM_ACL_SUBJECT_TYPE_PASSWORD CSSM_WORDID_PASSWORD
#define CSSM_ACL_SUBJECT_TYPE_PROTECTED_PASSWORD CSSM_WORDID_PROTECTED_PASSWORD
#define CSSM_ACL_SUBJECT_TYPE_PROMPTED_PASSWORD CSSM_WORDID_PROMPTED_PASSWORD
#define CSSM_ACL_SUBJECT_TYPE_PUBLIC_KEY CSSM_WORDID_PUBLIC_KEY
#define CSSM_ACL_SUBJECT_TYPE_HASHED_SUBJECT CSSM_WORDID_HASHED_SUBJECT
#define CSSM_ACL_SUBJECT_TYPE_BIOMETRIC CSSM_WORDID_BIOMETRIC
#define CSSM_ACL_SUBJECT_TYPE_PROTECTED_BIOMETRIC CSSM_WORDID_PROTECTED_BIOMETRIC
#define CSSM_ACL_SUBJECT_TYPE_LOGIN_NAME CSSM_WORDID_LOGIN_NAME
#define CSSM_ACL_SUBJECT_TYPE_EXT_PAM_NAME CSSM_WORDID_PAM_NAME

CSSM_ACL_SUBJECT_TYPE_* General Description
ANY The subject matches everyone. The AuthorizationTag associated with this subject represents operations that can be performed by anyone.
THRESHOLD The subject specifies a nested "k-of-n" subject. Each of the options is another defined ACL subject type.
PASSWORD The subject value is a password or passphrase value.
PROTECTED_PASSWORD The subject value is dynamically acquired and matched by a service that manages a protected data acquisition path to gather and verify a password or passphrase value.
PROMPTED_PASSWORD The subject value is a password or passphrase value with an associated prompt value. The prompt value can be presented to an application.
PUBLIC_KEY The subject value is a public key of some specified format.
HASHED_SUBJECT The subject value is the hash value of any ACL Subject of valid type. For example, the hash of a password.
BIOMETRIC The subject value is an enrolled biometric template value.
PROTECTED_BIOMETRIC The subject value is acquired and matched by a service that manages a protected data acquisition path to gather and verify a biometric sample from a Biometric Sensor
LOGIN_NAME The subject value is a login name. The name space of login names is defined and managed by the service provider.
EXT_PAM_NAME The subject value is a user name. The name space for user names is defined and managed by the Pluggable Authentication Modules (PAM), an external service. PAM is a specification standard of The Open Group.

CSSM_ACL_AUTHORIZATION_TAG

This type defines a set of names for operations that can be performed on ACL entries and on the resource objects that are protected by ACL entries. These names are represented as integer values. When creating an ACL entry, a set of these values should be aggregated into a CSSM_LIST structure that is used to initialize the AuthorizationTag item within the ACL entry.

The operations named by these constants correspond to functions defined in the CDSA and CSSM APIs. Service providers can define names for additional controlled operations. Service providers are encouraged to identify two types of operations:

  1. Operations that use the resource object

  2. Operations that modify the ACLs that protect the resource object

Vendors defining new constants must manage the integer name space to avoid definitions that conflict with other vendors. 



 

/* Authorization tag type */
typedef sint32 CSSM_ACL_AUTHORIZATION_TAG;


/* All vendor specific constants must be in the number range 
   starting at CSSM_ACL_AUTHORIZATION_TAG_VENDOR_DEFINED_START
 */
#define CSSM_ACL_AUTHORIZATION_TAG_VENDOR_DEFINED_START (0x00010000)


/* No restrictions. Permission to perform all operations on 
   the resource or available to an ACL owner. 
 */
#define CSSM_ACL_AUTHORIZATION_ANY CSSM_WORDID__STAR_


/* Defined authorization tag values for CSPs */
#define CSSM_ACL_AUTHORIZATION_LOGIN CSSM_WORDID_LOGIN
#define CSSM_ACL_AUTHORIZATION_GENKEY CSSM_WORDID_GENKEY 
#define CSSM_ACL_AUTHORIZATION_DELETE CSSM_WORDID_DELETE
#define CSSM_ACL_AUTHORIZATION_EXPORT_WRAPPED CSSM_WORDID_EXPORT_WRAPPED 
#define CSSM_ACL_AUTHORIZATION_EXPORT_CLEAR CSSM_WORDID_EXPORT_CLEAR
#define CSSM_ACL_AUTHORIZATION_IMPORT_WRAPPED CSSM_WORDID_IMPORT_WRAPPED
#define CSSM_ACL_AUTHORIZATION_IMPORT_CLEAR CSSM_WORDID_IMPORT_CLEAR
#define CSSM_ACL_AUTHORIZATION_SIGN CSSM_WORDID_SIGN
#define CSSM_ACL_AUTHORIZATION_ENCRYPT CSSM_WORDID_ENCRYPT
#define CSSM_ACL_AUTHORIZATION_DECRYPT CSSM_WORDID_DECRYPT 
#define CSSM_ACL_AUTHORIZATION_MAC CSSM_WORDID_MAC
#define CSSM_ACL_AUTHORIZATION_DERIVE CSSM_WORDID_DERIVE 


/* Defined authorization tag values for DLs */
#define CSSM_ACL_AUTHORIZATION_DBS_CREATE CSSM_WORDID_DBS_CREATE
#define CSSM_ACL_AUTHORIZATION_DBS_DELETE CSSM_WORDID_DBS_DELETE
#define CSSM_ACL_AUTHORIZATION_DB_READ CSSM_WORDID_DB_READ
#define CSSM_ACL_AUTHORIZATION_DB_INSERT CSSM_WORDID_DB_INSERT
#define CSSM_ACL_AUTHORIZATION_DB_MODIFY CSSM_WORDID_DB_MODIFY
#define CSSM_ACL_AUTHORIZATION_DB_DELETE CSSM_WORDID_DB_DELETE

The meaning of each authorization tag is listed in the following table. The tag may have slightly different meanings depending on the ACL type.

Authorization Tag
CSSM_ACL_AUTHORIZATION_* 		Meaning
The subject of the ACL is authorized to
ANY No restrictions. Permission to perform all operations on the resource.
LOGIN login to the subservice.
GENKEY generate a new key resource managed by the subservice.
DELETE delete resources managed by the subservice.
EXPORT_WRAPPED export the key in a wrapped form.
EXPORT_CLEAR export the key as cleartext.
IMPORT_WRAPPED import a new key resource to be managed by the subservice. The new resource is wrapped.
IMPORT_CLEAR import a new key resource to be managed by the subservice. The new resource is cleartext.
SIGN perform signature operations using the key.
ENCRYPT perform encryption operations using the key.
DECRYPT perform decryption operations using the key.
MAC perform Message Authentication Code (MAC) operation using the key.
DERIVE perform key derivation operations using the key as the basis.
DBS_CREATE create new databases managed by the subservice.
DBS_DELETE delete existing databases managed by the subservice.
DB_READ read the contents of record in a database.
DB_INSERT insert new records into a database.
DB_MODIFY change the value of meta-data or the data value of records in a database.
DB_DELETE delete existing records in a database.

Each type of ACL has a set of authorization tags that are valid. The following table lists each defined ACL type and the valid attribute values for those ACLs.

ACL Type Valid Authorization Tags
CSP Login
CSSM_ACL_AUTHORIZATION_ANY
CSSM_ACL_AUTHORIZATION_LOGIN
CSSM_ACL_AUTHORIZATION_GENKEY
CSSM_ACL_AUTHORIZATION_DELETE
CSSM_ACL_AUTHORIZATION_IMPORT_WRAPPED
CSSM_ACL_AUTHORIZATION_IMPORT_CLEAR
CSP Secret Key
CSSM_ACL_AUTHORIZATION_ANY
CSSM_ACL_AUTHORIZATION_DELETE
CSSM_ACL_AUTHORIZATION_EXPORT_WRAPPED
CSSM_ACL_AUTHORIZATION_EXPORT_CLEAR
CSSM_ACL_AUTHORIZATION_ENCRYPT
CSSM_ACL_AUTHORIZATION_DECRYPT
CSSM_ACL_AUTHORIZATION_MAC
CSSM_ACL_AUTHORIZATION_DERIVE
CSP Private Key
CSSM_ACL_AUTHORIZATION_ANY
CSSM_ACL_AUTHORIZATION_DELETE
CSSM_ACL_AUTHORIZATION_EXPORT_WRAPPED
CSSM_ACL_AUTHORIZATION_EXPORT_CLEAR
CSSM_ACL_AUTHORIZATION_SIGN
CSSM_ACL_AUTHORIZATION_DECRYPT
CSSM_ACL_AUTHORIZATION_DERIVE
DL Database
CSSM_ACL_AUTHORIZATION_ANY
CSSM_ACL_AUTHORIZATION_DBS_CREATE
CSSM_ACL_AUTHORIZATION_DBS_DELETE
CSSM_ACL_AUTHORIZATION_DB_READ
CSSM_ACL_AUTHORIZATION_DB_INSERT
CSSM_ACL_AUTHORIZATION_DB_MODIFY

CSSM_AUTHORIZATIONGROUP

This structure contains a group of authorization tags. 


 

typedef struct cssm_authorizationgroup {
    uint32 NumberOfAuthTags;
    CSSM_ACL_AUTHORIZATION_TAG *AuthTags;
} CSSM_AUTHORIZATIONGROUP, *CSSM_AUTHORIZATIONGROUP_PTR;
Definitions

NumberOfAuthTags

The number of authorization tags in the array AuthTags.

AuthTags

A pointer to an array of integers representing authorization tag values.

CSSM_ACL_VALIDITY_PERIOD

This data type defines a structure containing a start date and end date for the validity of an ACL entry. The date and time for an ACL entry, a CSSM_TUPLE or an AuthCompute call is an ASCII string of the form, for example, "1999-06-30_15:05:39". Dates are compared by normal string comparison. 


 

typedef struct cssm_acl_validity_period {
    CSSM_DATA StartDate;
    CSSM_DATA EndDate;
} CSSM_ACL_VALIDITY_PERIOD, *CSSM_ACL_VALIDITY_PERIOD_PTR;

CSSM_ACL_ENTRY_PROTOTYPE

This data type defines the abstract structure of an Access Control List (ACL) entry. The structure is used:

When an application uses this structure to provide initial values for an ACL entry, the structure is passed as an input parameter to a CDSA security service function. The structure must contain all fields as immediate data values, except the TypedSubject field. An application can provide the value of the TypedSubject field by:

An ACL entry prototype is considered to be a duplicate of an existing ACL entry if the entries have equal values for all fields except EntryTag. 



 

typedef struct cssm_acl_entry_prototype {
    CSSM_LIST TypedSubject;
    CSSM_BOOL Delegate;
    CSSM_AUTHORIZATIONGROUP Authorization;
    CSSM_ACL_VALIDITY_PERIOD TimeRange;
    CSSM_STRING EntryTag;
} CSSM_ACL_ENTRY_PROTOTYPE, *CSSM_ACL_ENTRY_PROTOTYPE_PTR;
Definitions

TypedSubject

A CSSM_LIST structure containing one or two elements for the subject of an ACL entry. The first list element is the type of the subject. The second element is the subject value. The subject value can be empty if a callback function is provided to acquire the subject value interactively. In either case, the subject type indicates the type of the immediate value or the type of the value to be supplied on-demand. The following table specifies the CSSM_LIST elements for each ACL subject type under each valid use scenario.

CSSM_ACL_SUBJECT_TYPE_
ANY 		CSSM_LIST Contents
Immediate Type and Value Form A one-element list
First element: WordID = CSSM_ACL_SUBJECT_TYPE_ANY
Query-response Form A one-element list
First element: WordID = CSSM_ACL_SUBJECT_TYPE_ANY
CSSM_ACL_SUBJECT_TYPE_
THRESHOLD 		CSSM_LIST Contents
Immediate Type and Value Form An (n+3)-element list
First element: WordID = CSSM_ACL_SUBJECT_TYPE_THRESHOLD
Second element: WordID = <k value>
Third element: WordID = <n value>
Fourth element: Sublist = (typed_subject_list-1)
Fifth element: Sublist = (typed_ subject _list-2)
 . . .
n+3rd element: Sublist = (typed_ subject _list-n)
Immediate Type and Request for Callback Form A 3-element list
First element: WordID = CSSM_ACL_SUBJECT_TYPE_THRESHOLD
Second element: WordID = <k value>
Third element: WordID = <n value>
Query-response Form An (n+3)-element list
First element: WordID = CSSM_ACL_SUBJECT_TYPE_THRESHOLD
Second element: WordID = <k value>
Third element: WordID = <n value>
Fourth element: Sublist = (typed_ subject _list-1)
Fifth element: Sublist = (typed_ subject _list-2)
 . . .
n+3rd element: Sublist = (typed_ subject _list-n)
CSSM_ACL_SUBJECT_TYPE_
PASSWORD 		CSSM_LIST Contents
Immediate Type and Value Form A two-element list
First element: WordID = CSSM_ACL_SUBJECT_TYPE_PASSWORD
Second element: Word is a CSSM_DATA structure referencing a non-terminated <password string> value of specified length
Immediate Type and Request for Callback Form A one-element list
First element: WordID = CSSM_ACL_SUBJECT_TYPE_PASSWORD
Query-response Form A one-element list
First element: WordID = CSSM_ACL_SUBJECT_TYPE_PASSWORD
CSSM_ACL_SUBJECT_TYPE_
PROMPTED_PASSWORD 		CSSM_LIST Contents
Immediate Type and Value Form A three-element list
First element: WordID = CSSM_ACL_SUBJECT_TYPE_PROMPTED_PASSWORD
Second element: Word is a CSSM_DATA structure referencing a non-terminated <prompt string> value of specified length
Third element: Word is a CSSM_DATA structure referencing a non-terminated <password string> value of specified length
Immediate Type and Request for Callback Form A one-element list
First element: WordID = CSSM_ACL_SUBJECT_TYPE_PROMPTED_PASSWORD
Query-response Form A two-element list
First element: WordID = CSSM_ACL_SUBJECT_TYPE_PROMPTED_PASSWORD
Second element: Word is a CSSM_DATA structure referencing a non-terminated <prompt string> value of specified length
CSSM_ACL_SUBJECT_TYPE_
PROTECTED_PASSWORD 		CSSM_LIST Contents
Immediate Type and Protected Path Acquisition Form A two-element list
First element: WordID = CSSM_ACL_SUBJECT_TYPE_PROTECTED_PASSWORD
Second element: Word is a CSSM_DATA structure identifying a <service provider subservice uid> in memory (by starting address and length).
Query-response Form A one-element list
First element: WordID = CSSM_ACL_SUBJECT_TYPE_PROTECTED_PASSWORD
CSSM_ACL_SUBJECT_TYPE_
PUBLIC_KEY 		CSSM_LIST Contents
Immediate Type and Value Form A three-element list
First element: WordID = CSSM_ACL_SUBJECT_TYPE_PUBLIC_KEY
Second element: Word is a CSSM_KEYBLOB_RAW_FORMAT value
Third element: Word is the keyblob
Immediate Type and Request for Callback Form A one-element list
First element: WordID = CSSM_ACL_SUBJECT_TYPE_PUBLIC_KEY
Query-response Form A three-element list
First element: WordID = CSSM_ACL_SUBJECT_TYPE_PUBLIC_KEY
Second element: Word is a CSSM_KEYBLOB_RAW_FORMAT value
Third element: Word is the keyblob
CSSM_ACL_SUBJECT_TYPE_
BIOMETRIC 		CSSM_LIST Contents
Immediate Type and Value Form A two-element list
First element: WordID = CSSM_ACL_SUBJECT_TYPE_BIOMETRIC
Second element: Word is a CSSM_DATA structure referencing a < biometric template> value of specified length
Immediate Type and Request for Callback Form A one-element list
First element: WordID = CSSM_ACL_SUBJECT_TYPE_BIOMETRIC
Query-response Form A one-element list
First element: WordID = CSSM_ACL_SUBJECT_TYPE_BIOMETRIC
CSSM_ACL_SUBJECT_TYPE_
PROTECTED_BIOMETRIC 		CSSM_LIST Contents
Immediate Type and Protected Path Acquisition Form A two-element list
First element: WordID = CSSM_ACL_SUBJECT_TYPE_PROTECTED_BIOMETRIC
Second element: Word is a CSSM_DATA structure identifying a <service provider subservice uid> in memory (by starting address and length).
Query-response Form A one-element list
First element: WordID = CSSM_ACL_SUBJECT_TYPE_PROTECTED_BIOMETRIC
CSSM_ACL_SUBJECT_TYPE_
LOGIN_NAME 		CSSM_LIST Contents
Immediate Type and Value Form A two-element list
First element: WordID = CSSM_ACL_SUBJECT_TYPE_LOGIN_NAME
Second element: Word is a CSSM_DATA structure referencing a non-terminated < login name> value of specified length
Immediate Type and Request for Callback Form A one-element list
First element: WordID = CSSM_ACL_SUBJECT_TYPE_LOGIN_NAME
Query-response Form A two-element list
First element: WordID = CSSM_ACL_SUBJECT_TYPE_LOGIN_NAME
Second element: Word is a CSSM_DATA structure referencing a non-terminated < login name> value of specified length
CSSM_ACL_SUBJECT_TYPE_
EXT_PAM_NAME 		CSSM_LIST Contents
Immediate Type and Value Form A two-element list
First element: WordID = CSSM_ACL_SUBJECT_TYPE_EXT_PAM_NAME
Second element: Word is a CSSM_DATA structure referencing a non-terminated < PAM-user name> value of specified length
Immediate Type and Request for Callback Form A one-element list
First element: WordID = CSSM_ACL_SUBJECT_TYPE_EXT_PAM_NAME
Query-response Form A two-element list
First element: WordID = CSSM_ACL_SUBJECT_TYPE_EXT_PAM_NAME
Second element: Word is a CSSM_DATA structure referencing a non-terminated < PAM_user name> value of specified length

Delegate

A CSSM_BOOL value indicating whether the TypedSubject can delegate the access rights defined by the Authorization. Delegation is based on the use of the public key infrastructure (PKI). Therefore, if Delegate is true (CSSM_TRUE), then the subject of the ACL entry must be of type CSSM_ACL_SUBJECT_TYPE_PUBLIC_KEY.

Authorization

A CSSM_AUTHORIZATIONGROUP structure enumerating the operations for which permission is granted to the TypedSubject.

TimeRange

A CSSM_ACL_VALIDITY_PERIOD structure containing the time period for which the ACL entry is valid. The first list element is the start time. The second list element is the stop time.

EntryTag

A user-defined tag value associated with the ACL entry. The tag value is a human-readable value specified at ACL creation time. A caller can use this value to selectively identify one or more ACL entries. The value may not be unique.

CSSM_ACL_OWNER_PROTOTYPE

This data type is the abstract definition of an Access Control List (ACL) Owner (that is, the owner of the resource protected by the ACL). The ACL_OWNER acts as an ACL entry protecting the resource ACL. It is subset of an ACL_ENTRY_PROTOTYPE; consisting only of the TypedSubject(whoistheOwner),andthe Delegate flag to indicate whether the "Owner" can delegate his rights over the ACL. The value of TypedSubject is taken initially from the ACL_ENTRY_PROTOTYPE that forms the initial ACL on the resource (the creator of the resource is the initial owner), and the Delegate flag is initially set to CSSM_FALSE.

After creation, the Owner may retrieve the Owner definition in the form of a CSSM_ACL_OWNER_PROTOTYPE, and replace it with a new Owner definition. 



 

typedef  struct  cssm_acl_owner_prototype  {
    CSSM_LIST TypedSubject;
    CSSM_BOOL Delegate;
} CSSM_ACL_OWNER_PROTOTYPE, *CSSM_ACL_OWNER_PROTOTYPE_PTR;

See CSSM_ACL_ENTRY_PROTOTYPE for a definition of TypedSubject and Delegate.

CSSM_ACL_SUBJECT_CALLBACK

This type defines the form of the callback function a service provider module can use to acquire a value for the subject of a prototype ACL entry. The service provider initializes the SubjectRequest and the Application initializes the SubjectResponse based on the type of the request. 


 

typedef CSSM_RETURN (CSSMAPI * CSSM_ACL_SUBJECT_CALLBACK)
    (const CSSM_LIST *SubjectRequest,
    CSSM_LIST_PTR SubjectResponse,
    void *CallerContext,
    const CSSM_MEMORY_FUNCS *MemFuncs);
Definitions

SubjectRequest (input)

A pointer to a CSSM_LIST structure containing a typed request for an ACL subject list. The type is specified as the first element in the list. The service provider selects the subject type from one of two sources:

If the service provider supports more than one subject type, then the first list element indicates the type CSSM_ACL_SUBJECT_TYPE_THRESHOLD with a k-value of one and an n-value equal to the number of supported subject types. The following n list elements describe each supported subject type. A table defining the CSSM_LIST contents for each possible SubjectRequest and SubjectResponse pair is defined in a table below.

SubjectResponse (output)

A pointer to a CSSM_LIST structure containing the typed response to the SubjectRequest. The first element of the list is the type of the response. The returned Subject list must be an appropriate response for the type options presented in SubjectRequest. The response is a single subject list that can contain a set of subject lists. If the response contains a set of subject lists then the first element must be of type CSSM_ACL_SUBJECT_TYPE_THRESHOLD followed by the number of Subject lists that follow. A table defining the CSSM_LIST contents for each possible SubjectRequest and SubjectResponse pair is defined in a table below.

CallerContext (input)

A generic pointer to context information that was provided by the original requester and is being returned to its originator.

MemFuncs (input)

A pointer to a CSSM_MEMORY_FUNCS structure. The subject callback must use the functions in this structure to allocate memory returned to the service provider in the Response structure.

CSSM_ACL_SUBJECT_TYPE_
ANY 		CSSM_LIST Contents
SubjectRequest Form Not used.
SubjectResponse Form A one-element list
First element: WordID = CSSM_ACL_SUBJECT_TYPE_ANY
CSSM_ACL_SUBJECT_TYPE_
THRESHOLD 		CSSM_LIST Contents
SubjectRequest Form An (n+3)-element list
First element: WordID = CSSM_ACL_SUBJECT_TYPE_THRESHOLD
Second element: WordID = 1
Third element: WordID = <n value>
Fourth element: Sublist = (typed_ subject _list-1)
Fifth element: Sublist = (typed_ subject _list-2)
 . . .
n+3rd element: Sublist = (typed_ subject _list-n)
SubjectResponse Form An (n+3)-element list
First element: WordID = CSSM_ACL_SUBJECT_TYPE_THRESHOLD
Second element: WordID = <k value>
Third element: WordID = <n value>
Fourth element: Sublist = (typed_ subject _list-1)
Fifth element: Sublist = (typed_ subject _list-2)
 . . .
n+3rd element: Sublist = (typed_ subject _list-n)
CSSM_ACL_SUBJECT_TYPE_
PASSWORD 		CSSM_LIST Contents
SubjectRequest Form A one-element list
First element: WordID = CSSM_ACL_SUBJECT_TYPE_PASSWORD
SubjectResponse Form!A two-element list
First element: WordID = CSSM_ACL_SUBJECT_TYPE_PASSWORD
Second element: Word is a CSSM_DATA structure referencing a non-terminated <password string> value of specified length
CSSM_ACL_SUBJECT_TYPE_
PROMPTED_PASSWORD 		CSSM_LIST Contents
SubjectRequest Form A one-element list
First element:
WordID = CSSM_ACL_SUBJECT_TYPE_PROMPTED_PASSWORD
SubjectResponse Form!A three-element list
First element:
WordID = CSSM_ACL_SUBJECT_TYPE_PROMPTED_PASSWORD
Second element: Word is a CSSM_DATA structure referencing a non-terminated <prompt string> value of specified length
Third element: Word is a CSSM_DATA structure referencing a non-terminated <password string> value of specified length
CSSM_ACL_SUBJECT_TYPE_
PROTECTED_PASSWORD 		CSSM_LIST Contents
SubjectRequest Form A one-element list
First element:
WordID = CSSM_ACL_SUBJECT_TYPE_PROTECTED_PASSWORD
SubjectResponse Form!A two-element list
First element:
WordID = CSSM_ACL_SUBJECT_TYPE_PROTECTED_PASSWORD
Second element: Word is a CSSM_DATA structure identifying a <service provider subservice uid> in memory (by starting address and length).
CSSM_ACL_SUBJECT_TYPE_
PUBLIC_KEY 		CSSM_LIST Contents
SubjectRequest Form A one-element list
First element: WordID = CSSM_ACL_SUBJECT_TYPE_PUBLIC_KEY
SubjectResponse Form A three-element list
First element: WordID = CSSM_ACL_SUBJECT_TYPE_PUBLIC_KEY
Second element: Word is a CSSM_KEYBLOB_RAW_FORMAT value
Third element: Word is the keyblob
CSSM_ACL_SUBJECT_TYPE_
BIOMETRIC 		CSSM_LIST Contents
SubjectRequest Form A one-element list
First element: WordID = CSSM_ACL_SUBJECT_TYPE_BIOMETRIC
SubjectResponse Form A three-element list
First element: WordID = CSSM_ACL_SUBJECT_TYPE_BIOMETRIC
Second element: Word is a CSSM_DATA structure identifying a <service provider subservice uid> in memory (by starting address and length).
Third element: Word is a CSSM_DATA structure referencing a <biometric template> value of specified length
CSSM_ACL_SUBJECT_TYPE_
PROTECTED_BIOMETRIC 		CSSM_LIST Contents
SubjectRequest Form A one-element list
First element:
WordID = CSSM_ACL_SUBJECT_TYPE_PROTECTED_BIOMETRIC
SubjectResponse Form A two-element list
First element:
WordID = CSSM_ACL_SUBJECT_TYPE_PROTECTED_BIOMETRIC
Second element: Word is a CSSM_DATA structure identifying a <service provider subservice uid> in memory (by starting address and length).
CSSM_ACL_SUBJECT_TYPE_
LOGIN_NAME 		CSSM_LIST Contents
SubjectRequest Form A one-element list
First element: WordID = CSSM_ACL_SUBJECT_TYPE_LOGIN_NAME
SubjectResponse Form A two-element list
First element: WordID = CSSM_ACL_SUBJECT_TYPE_LOGIN_NAME
Second element: Word is a CSSM_DATA structure referencing a non-terminated < login name> value of specified length
CSSM_ACL_SUBJECT_TYPE_
EXT_PAM_NAME 		CSSM_LIST Contents
SubjectRequest Form A one-element list
First element:
WordID = CSSM_ACL_SUBJECT_TYPE_EXT_PAM_NAME
SubjectResponse Form A two-element list
First element:
WordID = CSSM_ACL_SUBJECT_TYPE_EXT_PAM_NAME
Second element: Word is a CSSM_DATA structure referencing a non-terminated < PAM_user name> value of specified length

CSSM_ACL_ENTRY_INPUT

This data structure is used by a caller to provide an ACL entry prototype to a service provider. An ACL entry prototype must be provided as input to a service provider when a new controlled resource is being created and when a new ACL entry is being added to an existing access-controlled resource. 


 

typedef struct cssm_acl_entry_input {
    CSSM_ACL_ENTRY_PROTOTYPE Prototype;
    CSSM_ACL_SUBJECT_CALLBACK Callback;
    void *CallerContext;
}  CSSM_ACL_ENTRY_INPUT, *CSSM_ACL_ENTRY_INPUT_PTR;
Definitions

Prototype

A CSSM_ACL_ENTRY_PROTOTYPE structure containing the initial values for an ACL entry. All sub-components of the ACL entry, except the ACL entry Subject, must be provided as immediate data in this structure. The Prototype->Subject field is of type CSSM_LIST. The ACL entry Subject value can be provided by:

Callback

A function pointer the service provider can de-reference (if necessary) to acquire the Subject of an ACL entry prototype from the original requester. The original requester must implement this function if the Subject value is not provided through alternate means, such as immediate data, a protected data path and service, or an external authentication or authorization service. If the initial value of the ACL entry Subject is provided by one of these other means, then the specified Callback must be NULL.

CallerCtx

A requester-defined structure that a service provider module must pass as an input parameter to the original requester when invoking the Callback function.

CSSM_RESOURCE_CONTROL_CONTEXT

This data structure is used by a caller when creating a new resource. The caller can provide AccessCredentials as evidence that the caller is allowed to create a new resource. The caller can also provide an ACL entry prototype to be used by the service provider in constructing the initial ACL entry controlling access to the new resource. 


 

typedef struct cssm_resource_control_context {
    CSSM_ACCESS_CREDENTIALS_PTR AccessCred;
    CSSM_ACL_ENTRY_INPUT InitialAclEntry;
} CSSM_RESOURCE_CONTROL_CONTEXT, *CSSM_RESOURCE_CONTROL_CONTEXT_PTR;
Definitions

AccessCred

A pointer to the set of credentials required to prove the caller's right to create a new resource. Required credentials can include zero or more certificates and zero or more samples. If certificates are provided, they must be provided as immediate values in this structure. The samples can be provided as immediate values or can be obtained through a callback function included in the AccessCred structure. If no additional credentials are required to demonstrate the caller's right to create a new resource, then AccessCred can be NULL.

InitialAclEntry

The prototype for the initial ACL entry that will control access to the newly created resource. All sub-components of the ACL entry, except the ACL entry Subject, must be provided as immediate data within this structure. The ACL entry Subject can be provided as immediate data or be acquired through a callback function included in the InitialAclEntry structure.

CSSM_ACL_HANDLE

This data type defines an opaque handle that uniquely identifies a single ACL entry associated with a particular resource. 


 

typedef  CSSM_HANDLE CSSM_ACL_HANDLE;

CSSM_ACL_ENTRY_INFO

This data structure is used to return ACL entry information from a service provider module to a caller. The structure includes:

The ACL information structure does not indicate the resource for which access control is being defined. A caller requests ACL information for a specific resource. The returned ACL entries are associated with the target resource. 



 

typedef  struct  cssm_acl_entry_info  {
    CSSM_ACL_ENTRY_PROTOTYPE EntryPublicInfo;
    CSSM_ACL_HANDLE EntryHandle;
} CSSM_ACL_ENTRY_INFO, *CSSM_ACL_ENTRY_INFO_PTR;
Definitions

EntryPublicInfo

A CSSM_ACL_ENTRY_PROTOTYPE containing the public information from an ACL entry. The structure includes:

EntryHandle

A unique, opaque identifier for the ACL entry. The value is defined and managed by the service provider who manages the ACL entries. The handle is valid for the current service provider attach session.

CSSM_ACL_EDIT_MODE

This data type defines identifiers for operations that modify an existing access control list (ACL). The three operations are: 


 

typedef  uint32 CSSM_ACL_EDIT_MODE;


#define CSSM_ACL_EDIT_MODE_ADD (1)
#define CSSM_ACL_EDIT_MODE_DELETE (2)
#define CSSM_ACL_EDIT_MODE_REPLACE (3)

CSSM_ACL_EDIT

This data structure contains the description of an edit operation to be applied to an existing Access Control List (ACL). The editing instructions include the edit operation, a handle to an existing ACL managed by a service provider, and information a service provider could use to update the existing ACL entry or to create a new ACL entry managed by the service provider module. 


 

typedef struct cssm_acl_edit {
    CSSM_ACL_EDIT_MODE EditMode;
    CSSM_ACL_HANDLE OldEntryHandle;
    const CSSM_ACL_ENTRY_INPUT *NewEntry;
} CSSM_ACL_EDIT, *CSSM_ACL_EDIT_PTR;
Definitions

EditMode

The type of edit operation to be performed on one of a set of ACL entries that control access to some resource.

OldEntryHandle

A unique, opaque value identifying an existing ACL entry. The name space for these identifiers is defined and managed by a service provider module. The identified ACL entry can be replaced or deleted.

NewEntry

A pointer to a prototype ACL entry. The prototype entry is used to update the ACL entry identified by OldEntryHandle according to the operation specified by EditMode. If EditMode is CSSM_ACL_EDIT_MODE_DELETE, this value must be NULL.

CSSM_PROC_ADDR

Generic pointer to a CSSM function. 


 

#if defined(WIN32)
typedef FARPROC CSSM_PROC_ADDR;
#else
typedef void (CSSMAPI *CSSM_PROC_ADDR) ();
#endif
typedef CSSM_PROC_ADDR *CSSM_PROC_ADDR_PTR;

CSSM_KR_POLICY_TYPE

Support for the KRMM relation. 


 

typedef uint32 CSSM_KR_POLICY_TYPE;
#define CSSM_KR_INDIV_POLICY (0x00000001)
#define CSSM_KR_ENT_POLICY (0x00000002)
#define CSSM_KR_LE_MAN_POLICY (0x00000003)
#define CSSM_KR_LE_USE_POLICY (0x00000004)

CSSM_FUNC_NAME_ADDR

This structure binds a function to the runtime address of the procedure that implements the named function. Function names are limited in length to the size of a CSSM_STRING. 


 

typedef struct cssm_func_name_addr {
    CSSM_STRING Name;
    CSSM_PROC_ADDR Address;
}CSSM_FUNC_NAME_ADDR, *CSSM_FUNC_NAME_ADDR_PTR;
Definition

Name

The name of the function represented as a fixed-length string.

Address

The runtime address of the procedure implementing the named function.

CSSM_MEMORY_FUNCS and CSSM_API_MEMORY_FUNCS

This structure is used by applications to supply memory functions for the CSSM and the security service modules. The functions are used when memory needs to be allocated by the CSSM or security services for returning data structures to the applications 


 

typedef void * (CSSMAPI *CSSM_MALLOC) 
    ( uint32 size,
    void * allocref)

typedef void (CSSMAPI *CSSM_FREE)
    (void * memblock,
    void * allocref)

typedef void * (CSSMAPI *CSSM_REALLOC)
    (void * memblock,
    uint32 size,
    void * allocref)

typedef void * (CSSMAPI *CSSM_CALLOC)
    (uint32 num,
    uint32 size,
    void * allocref)

typedef struct cssm_memory_funcs {
    CSSM_MALLOC malloc_func;
    CSSM_FREE free_func;
    CSSM_REALLOC realloc_func;
    CSSM_CALLOC calloc_func;
    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 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 (referenced by memblock) from heap allocref. The input parameters reserved0 and reserved1 can be used by the memory management functions to create an audit trail of memory allocation and de-allocation for tracking memory management problems among multiple dynamic modules.

realloc_func

Pointer to function that returns a void pointer to the reallocated memory block (referenced by memblock) of at least size bytes from heap allocref. The input parameters reserved0 and reserved1 can be used by the memory management functions to create an audit trail of memory allocation and de-allocation for tracking memory management problems among multiple dynamic modules.

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. The input parameters reserved0 and reserved1 can be used by the memory management functions to create an audit trail of memory allocation and de-allocation for tracking memory management problems among multiple dynamic modules.

AllocRef

Indicates the default memory heap if allocref is NULL in specific calls to these functions.

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

Common Error Return Codes

This section defines all the Error Values that can be returned by CSSM operations.

The Error Values that can be returned by CSSM functions can be either derived from the Common Error Codes defined in CSSM Error Handling, or they are specific to the CSSM function.

Error Values Derived from Common Error Codes 


#define CSSMERR_CSSM_INTERNAL_ERROR \
    (CSSM_CSSM_BASE_ERROR+CSSM_ERRCODE_INTERNAL_ERROR)


#define CSSMERR_CSSM_MEMORY_ERROR \
    (CSSM_CSSM_BASE_ERROR+CSSM_ERRCODE_MEMORY_ERROR)


#define CSSMERR_CSSM_MDS_ERROR \
    (CSSM_CSSM_BASE_ERROR+CSSM_ERRCODE_MDS_ERROR)


#define CSSMERR_CSSM_INVALID_POINTER \
    (CSSM_CSSM_BASE_ERROR+CSSM_ERRCODE_INVALID_POINTER)


#define CSSMERR_CSSM_INVALID_INPUT_POINTER \
    (CSSM_CSSM_BASE_ERROR+CSSM_ERRCODE_INVALID_INPUT_POINTER)


#define CSSMERR_CSSM_INVALID_OUTPUT_POINTER \ 
    (CSSM_CSSM_BASE_ERROR+CSSM_ERRCODE_INVALID_OUTPUT_POINTER)


#define CSSMERR_CSSM_FUNCTION_NOT_IMPLEMENTED \
    (CSSM_CSSM_BASE_ERROR+CSSM_ERRCODE_FUNCTION_NOT_IMPLEMENTED)


#define CSSMERR_CSSM_SELF_CHECK_FAILED \
    (CSSM_CSSM_BASE_ERROR+CSSM_ERRCODE_SELF_CHECK_FAILED)


#define CSSMERR_CSSM_OS_ACCESS_DENIED \
    (CSSM_CSSM_BASE_ERROR+CSSM_ERRCODE_OS_ACCESS_DENIED)


#define CSSMERR_CSSM_FUNCTION_FAILED \
    (CSSM_CSSM_BASE_ERROR+CSSM_ERRCODE_FUNCTION_FAILED)


#define CSSMERR_CSSM_MODULE_MANIFEST_VERIFY_FAILED \ 
    (CSSM_CSSM_BASE_ERROR+CSSM_ERRCODE_MODULE_MANIFEST_VERIFY_FAILED)


#define CSSMERR_CSSM_INVALID_GUID \
    (CSSM_CSSM_BASE_ERROR+CSSM_ERRCODE_INVALID_GUID)


#define CSSMERR_CSSM_INVALID_CONTEXT_HANDLE \
    (CSSM_CSSM_BASE_ERROR+CSSM_ERRCODE_INVALID_CONTEXT_HANDLE)


#define CSSMERR_CSSM_ INCOMPATIBLE_VERSION \
    (CSSM_CSSM_BASE_ERROR+CSSM_ERRCODE_INCOMPATIBLE_VERSION)


#define CSSMERR_CSSM_PRIVILEGE_NOT_GRANTED \
    (CSSM_CSSM_BASE_ERROR+CSSM_ERRCODE_PRIVILEGE_NOT_GRANTED)

CSSM Module-Specific Error Values

The first 16 CSSM Error Codes are reserved for general errors, see CSSM Error Handling. 


#define CSSM_CSSM_BASE_CSSM_ERROR \
    (CSSM_CSSM_BASE_ERROR+CSSM_ERRORCODE_COMMON_EXTENT+0x10)


#define CSSMERR_CSSM_SCOPE_NOT_SUPPORTED (CSSM_CSSM_BASE_CSSM_ERROR+1)
Privilege scope requested is not supported in the platform 


#define CSSMERR_CSSM_PVC_ALREADY_CONFIGURED (CSSM_CSSM_BASE_CSSM_ERROR+2)
PvcPolicy is already configured in the first call to CSSM_Init 


#define CSSMERR_CSSM_INVALID_PVC  (CSSM_CSSM_BASE_CSSM_ERROR+3)
PvcPolicy requested is invalid 


#define CSSMERR_CSSM_EMM_LOAD_FAILED (CSSM_CSSM_BASE_CSSM_ERROR+4)
EMM load failed 


#define CSSMERR_CSSM_EMM_UNLOAD_FAILED (CSSM_CSSM_BASE_CSSM_ERROR+5)
EMM unload failed 


#define CSSMERR_CSSM_ADDIN_LOAD_FAILED (CSSM_CSSM_BASE_CSSM_ERROR+6)
Addin Load function failed 


#define CSSMERR_CSSM_INVALID_KEY_HIERARCHY (CSSM_CSSM_BASE_CSSM_ERROR+7)
Invalid key hierarchy requested 


#define CSSMERR_CSSM_ADDIN_UNLOAD_FAILED (CSSM_CSSM_BASE_CSSM_ERROR+8)
Addin Unload function failed 


#define CSSMERR_CSSM_LIB_REF_NOT_FOUND (CSSM_CSSM_BASE_CSSM_ERROR+9)
A reference to the loaded library cannot be obtained 


#define CSSMERR_CSSM_INVALID_ADDIN_FUNCTION_TABLE \
    (CSSM_CSSM_BASE_CSSM_ERROR+10)
Addin function table registered with CSSM is invalid 


#define CSSMERR_CSSM_EMM_AUTHENTICATE_FAILED \
    (CSSM_CSSM_BASE_CSSM_ERROR+11)
ModuleManager authentication failed 


#define CSSMERR_CSSM_ADDIN_AUTHENTICATE_FAILED \
    (CSSM_CSSM_BASE_CSSM_ERROR+12)
Addin authenticate function failed 


#define CSSMERR_CSSM_INVALID_SERVICE_MASK \
    (CSSM_CSSM_BASE_CSSM_ERROR+13)
Invalid service mask 


#define CSSMERR_CSSM_MODULE_NOT_LOADED (CSSM_CSSM_BASE_CSSM_ERROR+14)
Module was not loaded 


#define CSSMERR_CSSM_INVALID_SUBSERVICEID (CSSM_CSSM_BASE_CSSM_ERROR+15)
Invalid subservice Id was requested 


#define CSSMERR_CSSM_BUFFER_TOO_SMALL (CSSM_CSSM_BASE_CSSM_ERROR+16)
Buffer size for the ModuleManagerGuids is less than the required size 


#define CSSMERR_CSSM_INVALID_ATTRIBUTE (CSSM_CSSM_BASE_CSSM_ERROR+17)
Invalid attribute in context 


#define CSSMERR_CSSM_ATTRIBUTE_NOT_IN_CONTEXT \
    (CSSM_CSSM_BASE_CSSM_ERROR+18)
Requested attribute is not in the context 


#define CSSMERR_CSSM_MODULE_MANAGER_INITIALIZE_FAIL \
    (CSSM_CSSM_BASE_CSSM_ERROR+19)
ModuleManger initialize failed 


#define CSSMERR_CSSM_MODULE_MANAGER_NOT_FOUND \
    (CSSM_CSSM_BASE_CSSM_ERROR+20)
ModuleManger to be notified is not loaded

Core Functions

The man-page definitions for CSSM Core functions are presented in this section.
Previous section.

Click here to return to the publication details.

NAME

CSSM_Init

SYNOPSIS


CSSM_RETURN CSSMAPI CSSM_Init(
    const CSSM_VERSION *Version,
    CSSM_PRIVILEGE_SCOPE Scope,
    const CSSM_GUID * CallerGuid, 
    CSSM_KEY_HIERARCHY KeyHierarchy,
    CSSM_PVC_MODE *PvcPolicy,
    const void *Reserved)

DESCRIPTION

This function initializes CSSM and verifies that the version of CSSM expected by the application is compatible with the version of CSSM on the system. This function should be called at least once by the application. It is an error to call any function of the CSSM API other than CSSM_Init() before a call to CSSM_Init() has returned successfully (that is, with CSSM_OK).

Implementations of CSSM may have platform specific characteristics associated with the implementation of CSSM_SetPrivilege() API. The privilege value may have thread specific scope or process specific scope. The application can specify the anticipated scope at CSSM_Init(). If the anticipated scope is not appropriate for the implementation, an error is returned. The scope can be configured only once. Subsequent attempts to configure scope are ignored.

The CSSM integrity model includes the ability to make and check assertions about trusted dynamically loaded libraries. Checking assertions happens while the program executes. It is known as Pointer Validation Checking (PVC). Pointer validation checking may be applied every time execution flow crosses the CSSM API or SPI interfaces.

Performing pointer validation checks has two purposes:

The CSSM can be configured to bypass pointer validation under some circumstances. Pointer validation cannot be bypassed when privileged operations are being performed.

The prerequisites for performing PVC on another module, be it service provider, CSSM, or other library, are:

Typically, the entry-points are discovered when a module's functions are called by another module. The CSSM will perform pointer validation checks based on the configured checking policy. Checking policies are established by the manufacturers of CSSM and other libraries. The checking policy to be applied during execution is configured using the CSSM_Init() call. The policy can be configured once during the life of the process and occurs the first time CSSM_Init() is called.

PVC Policy Configuration Options
Pointer validation checking can be applied at the CSSM API interface, the CSSM SPI interface or both. The CSSM vendor can configure a default policy through instructions contained in the CSSM signed manifest. Manifest attributes pertaining to pointer validation checking are defined as follows:

Module Tag Value Description
CSSM CDSA_PVC_API unspecified CSSM will perform PVC checks at the API boundary
CSSM CDSA_PVC_API OFF CSSM will not perform PVC checks at the API boundary
CSSM CDSA_PVC_SPI unspecified CSSM will perform PVC checks at the SPI boundary
CSSM CDSA_PVC_SPI OFF CSSM will not perform PVC checks at the SPI boundary
App CDSA_PVC_API EXEMPT The calling module is allowed to override the CSSM policy for the API boundary
App CDSA_PVC_API unspecified The calling module cannot weaken the CSSM API policy
App CDSA_PVC_SPI EXEMPT The calling module is allowed to override the CSSM policy for the SPI boundary
App CDSA_PVC_SPI unspecified The calling module cannot weaken the CSSM SPI policy

The PvcPolicy parameter to CSSM_Init() configures the run-time policy for the process. The PvcPolicy parameter is a bitmask allowing both API and SPI policies to be specified simultaneously. Unspecified policies default to the most conservative operational mode. The CSSM performs pointer validation checks unless explicitly disabled. Application modules may not override CSSM policy unless exemptions are explicitly granted. The following table shows the what policies may be configured for various manifest attribute values:

CSSM Manifest Calling Module Manifest Acceptable PvcPolicy Values
CDSA_PVC_API=<n/a> CDSA_PVC_API=EXEMPT API checks: off (0) or on (1)
CDSA_PVC_API=OFF CDSA_PVC_API=EXEMPT API checks: off (0) or on (1)
CDSA_PVC_API=<n/a> CDSA_PVC_API=<n/a> API checks: on (1)
CDSA_PVC_API=OFF CDSA_PVC_API=<n/a> API checks: off (0) or on (1)

The following table shows the PvcPolicy configuations available for the SPI:

SSM Manifest Calling Module Manifest Acceptable PvcPolicy Values
CDSA_PVC_SPI=<n/a> CDSA_PVC_SPI=EXEMPT SPI checks: off (0) or on (2)
CDSA_PVC_SPI =OFF CDSA_PVC_SPI=EXEMPT SPI checks: off (0) or on (2)
CDSA_PVC_SPI =<n/a> CDSA_PVC_SPI=<n/a> SPI checks: on (2)
CDSA_PVC_SPI =OFF CDSA_PVC_SPI=<n/a> SPI checks: off (0) or on (2)

If an application module does not have a manifest and CSSM requires the application module be subject to pointer validation checks, then pointer validation checks fail and CSSM will not operate with the anonymous module. All service provider modules are expected to have signed maniefests.

PARAMETERS

Version (input)

The major and minor version number of the CSSM release the application is compatible with.

Scope (input)

The scope of the global privilege value. The scope may either process scope wide (CSSM_PRIVILEGE_SCOPE_PROCESS) or thread wide (CSSM_PRIVILEGE_SCOPE_THREAD). This parameter is ignored after the first call to CSSM_Init().

CallerGuid (input)

The GUID associated with the caller. This GUID is used to locate the caller's credentials when evaluating the request for privileges.

KeyHierarchy (input)

The CSSM_KEY_HIERARCHY flag directing CSSM what embedded key to use when verifying integrity of the named module.

PvcPolicy (input/output)

Configures the way in which pointer validation checks will be performed. If not the first call to CSSM_Init(), the previously configured policy is returned in the PvcPolicy bitmask and the CSSM_Init() call continues processing. If successfully completed, the error code CSSMERR_CSSM_PVC_ALREADY_CONFIGURED is returned.

Value Description
0 PVC validation is not performed
1 PVC validation is performed on application modules
2 PVC validation is performed on service provider modules
3 Both types of PVC validations are performed

Reserved (input)

A reserved input.

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 Error Codes and Error Values section earlier in this Chapter.


CSSMERR_CSSM_SCOPE_NOT_SUPPORTED
CSSMERR_CSSM_PVC_ALREADY_CONFIGURED
CSSMERR_CSSM_INVALID_PVC

Previous section.

NAME

CSSM_Terminate

SYNOPSIS


CSSM_RETURN CSSMAPI CSSM_Terminate ( )

DESCRIPTION

This function terminates the caller's use of CSSM. CSSM can cleanup all internal state associated with the calling application. This function must be called once by each application.

CSSM_Terminate() must be called one time for each time CSSM_Init() was previously called. CSSM services remain available to the program until the final call to CSSM_Terminate() completes. After that final call, all information introduced by the caller (including privileges, handles, contexts, introduced libraries, etc.) is lost, and it is an error to subsequently call any CSSM API function other than CSSM_Init().

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 Codes and Values.

SEE ALSO

CSSM_Init().

Module Management Functions

The manpages for Module Management Functions can be found at the end of this chapter. The man-page definitions for Module Management functions are presented in this section.
Previous section.

NAME

CSSM_ModuleLoad

SYNOPSIS


CSSM_RETURN CSSMAPI CSSM_ModuleLoad
    (const CSSM_GUID *ModuleGuid, 
    CSSM_KEY_HIERARCHY KeyHierarchy, 
    CSSM_API_ModuleEventHandler AppNotifyCallback,
    void* AppNotifyCallbackCtx)

DESCRIPTION

This function initializes the security service service module. Initialization includes registering the application's module-event handler and enabling events with the security service service module. The application can choose to provide an event handler function to receive notification of insert, remove and fault events. The specified event handler is the single callback points for all attached sessions with the specified service module.

The function CSSM_Init() must be invoked prior to calling CSSM_ModuleLoad(). The function CSSM_ModuleAttach() can be invoked multiple times per call to CSSM_ModuleLoad().

PARAMETERS

ModuleGuid (input)

The GUID of the module selected for loading.

KeyHierarchy (input)

The CSSM_KEY_HIERARCHY flag directing CSSM what embedded key to use when verifying integrity of the named module.

AppNotifyCallback (input/optional)

The event notification function provided by the caller. This defines the callback for event notifications from the loaded (and later attached) service module.

AppNotifyCallbackCtx (input/optional)

When the selected service module raises an event, this context is passed as an input to the event handler specified by AppNotifyCallback. CSSM does not interpret or modify the value of AppNotifyCallbackCtx.

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 Error Codes and Error Values section earlier in this Chapter.


CSSMERR_CSSM_INVALID_GUID
CSSMERR_CSSM_ADDIN_LOAD_FAILED
CSSMERR_CSSM_EMM_LOAD_FAILED
CSSMERR_CSSM_INVALID_KEY_HIERARCHY

Previous section.

NAME

CSSM_ModuleUnload

SYNOPSIS


CSSM_RETURN CSSMAPI CSSM_ModuleUnload
    (const CSSM_GUID *ModuleGuid, 
    CSSM_API_ModuleEventHandler AppNotifyCallback,
    void* AppNotifyCallbackCtx)

DESCRIPTION

The function deregisters event notification callbacks for the caller identified by ModuleGuid. CSSM_ModuleLoad() is the analog call to CSSM_ModuleLoad(). If all registered callbacks registered with CSSM are removed, then CSSM unloads the service module that was loaded by calls to CSSM_ModuleLoad(). Calls to CSSM_ModuleUnload() that are not matched with a previous call to CSSM_ModuleLoad() result in an error.

The CSSM uses the three input parameters ModuleGuid, AppNotifyCallback, and AppNotifyCallbackCtx to uniquely identify registered callbacks.

This function should be invoked after all necessary calls to CSSM_ModuleDetach() have been performed.

PARAMETERS

ModuleGuid (input)

The GUID of the module selected for unloading.

AppNotifyCallback (input/optional)

The event notification function to be de-registered. The function must have been provided by the caller in CSSM_ModuleLoad().

AppNotifyCallbackCtx (input/optional)

The event notification context that was provided in the corresponding call to CSSM_ModuleLoad().

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 Error Codes and Error Values section earlier in this Chapter.


CSSMERR_CSSM_ADDIN_UNLOAD_FAILED
CSSMERR_CSSM_EMM_UNLOAD_FAILED

Previous section.

NAME

CSSM_Introduce

SYNOPSIS


CSSM_RETURN CSSM_Introduce 
    (const CSSM_GUID *ModuleID,
    CSSM_KEY_HIERARCHY KeyHierarchy)

DESCRIPTION

The CSSM_Introduce() function identifies a dynamically loadable executable module (e.g. DLL) to the CSSM framework. CSSM uses the ModuleID information to locate the signed manifest and library on the host platform. The Module Directory Service (MDS) should be used to obtain the information. CSSM performs an integrity crosscheck on the module identified by ModuleID and caches the result in an internal structure. Integrity crosscheck uses the KeyHierarchy information to determine which classes of embedded public keys must serve as anchors when doing certificate path validation. If the export key hierarchy is specified, the set of export privileges contained in the manifest are retrieved from the manifest and saved with the integrity state information in the cache. Privileges granted to a module are accepted only if the manifest sections containing the privilege set have been signed by a principal in the export key hierarchy class and that hash of the module binary is part of the hash of the privilege attributes.

CSSM_Introduce() may be called at any time after CSSM_Init(), by any module, on behalf of any module. Once a module is introduced into CSSM the load location of the module must not change. If the load location changes then the module must be re-introduced. Once introduced, the module load location, integrity and privilege information is held until CSSM_Terminate() is called or the process terminates. Initialization of internal data structures maintaining the table of introductions is performed when CSSM_Init() is called.

If CSSM_Introduce() is called on behalf of another module, then the caller needs to make sure that the other module is loaded into the process address space. If the library is already loaded into process address space, but a reference to the library cannot be obtained, a different error is returned (CSSMERR_CSSM_LIB_REF_NOT_FOUND).

PARAMETERS

ModuleID (input)

The CSSM_GUID of the calling library or other library that may call CDSA interfaces. The GUID is used to locate the signed manifest credentials of the named module to calculate module integrity information.

KeyHierarchy (input)

The CSSM_KEY_HIERARCHY flag directing CSSM what embedded key to use when verifying integrity of the named 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 also the Error Codes and Error Values section earlier in this Chapter.


CSSMERR_CSSM_INVALID_KEY_HIERARCHY
CSSMERR_CSSM_LIB_REF_NOT_FOUND


Previous section.


NAME


CSSM_Unintroduce

SYNOPSIS





CSSM_RETURN CSSM_Unintroduce 


    (const CSSM_GUID *ModuleID)

DESCRIPTION


The
CSSM_Unintroduce()
function removes the module referenced by
ModuleID
from the list of module information maintained by the CSSM framework.


A caller may
un-introduce
modules other than itself if the caller has been previously introduced.

PARAMETERS



ModuleID (input)



The CSSM_GUID of the calling library or other library that may call
CDSA interfaces. The GUID is used to locate the module integrity
and privilege information. If the
ModuleID
is NULL then the caller will be "un-introduced".


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 Error Codes and Error Values section earlier in this Chapter.


CSSMERR_CSSM_INVALID_GUID


Previous section.



NAME


CSSM_ModuleAttach

SYNOPSIS





CSSM_RETURN CSSMAPI CSSM_ModuleAttach


    (const CSSM_GUID *ModuleGuid,


    const CSSM_VERSION *Version, 


    const CSSM_API_MEMORY_FUNCS *MemoryFuncs,


    uint32 SubserviceID,


    CSSM_SERVICE_TYPE SubServiceType, 


    CSSM_ATTACH_FLAGS AttachFlags,


    CSSM_KEY_HIERARCHY KeyHierarchy,


    CSSM_FUNC_NAME_ADDR *FunctionTable,


    uint32 NumFunctionTable,


    const void *Reserved,


    CSSM_MODULE_HANDLE_PTR NewModuleHandle)

DESCRIPTION


This function attaches the service provider module and verifies that
the version of the module expected by the application is compatible
with the version on the system. The module can implement sub-services
(as described in the service provider's documentation). The caller can
specify a specific sub-service provided by the module.


If the sub-service is supported as part of the CSSM framework as well
as by an EMM,
ModuleAttach
attaches the Service Provider to the CSSM framework. If the sub-service
is only supported by an EMM,
ModuleAttach
loads the appropriate EMM. The Service Provider is given an indication
of whether it is being attached to the CSSM framework or an EMM.


The caller may provide a function table containing
function-names for the desired services. On output each function name
is matched with an API function pointer. The caller can use the pointers
to invoke service module operations through CSSM.

PARAMETERS



ModuleGuid (input)



A pointer to the CSSM_GUID structure containing the global unique
identifier for the CSP module.

Version (input)



The major and minor version number of CDSA that
the application is compatible with.

MemoryFuncs (input)



A structure containing pointers to the memory routines.

SubserviceID (input)



A
SubServiceID
identifying a particular subservice within the module.
Subservice IDs can be obtained from MDS or gleaned from insertion events
reported through the
callback
function installed through
CSSM_ModuleLoad().
Modules that provide only one service may use zero as
their Subservice ID.

SubServiceType (input)



A service mask describing the type of service the caller is requesting
of the service provider module.

AttachFlags (input)



A mask representing the caller's request for session-specific services.

KeyHierarchy (input)



The CSSM_KEY_HIERARCHY flag directing CSSM what embedded key to use
when verifying integrity of the named module.

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().

NumFunctionTable (input)



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

Reserved (input)



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

NewModuleHandle (output)



A new module handle that can be used to interact with the requested
service provider. The 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 also the Error Codes and Error Values section earlier in this Chapter.



CSSMERR_CSSM_INVALID_ADDIN_FUNCTION_TABLE
CSSMERR_CSSM_EMM_AUTHENTICATE_FAILED
CSSMERR_CSSM_ADDIN_AUTHENTICATE_FAILED
CSSMERR_CSSM_INVALID_SERVICE_MASK
CSSMERR_CSSM_MODULE_NOT_LOADED
CSSMERR_CSSM_INVALID_SUBSERVICEID
CSSMERR_CSSM_INVALID_KEY_HIERARCHY
CSSMERR_CSSM_INVALID_GUID

SEE ALSO

CSSM_ModuleDetach()
Previous section.

NAME

CSSM_ModuleDetach

SYNOPSIS


CSSM_RETURN CSSMAPI CSSM_ModuleDetach
    (CSSM_MODULE_HANDLE ModuleHandle)

DESCRIPTION

This function detaches the application from the service provider module.

PARAMETERS

ModuleHandle (input)

The handle that describes the service provider 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 General Error Codes and Common Error Codes and Values.

SEE ALSO


CSSM_ModuleAttach()
Previous section.

NAME

CSSM_SetPrivilege

SYNOPSIS


CSSM_RETURN CSSMAPI CSSM_SetPrivilege 
    (CSSM_PRIVILEGE Privilege)

DESCRIPTION

The SetPrivilege() function accepts as input a privilege value and stores it internal to the CSSM framework. The integrity credentials of the module calling SetPrivilege() must be verified by CSSM before the privilege value is updated. Integrity credentials are established using CSSM_Introduce(). CSSM will perform pointer validation check to ensure the caller has been previously introduced. SetPrivilege() will fail if no integrity information can be found for the caller.

After pointer validation checks, CSSM verifies the requested privilege is authorized. This is done by comparing Privilege with the set of privileges contained in the caller manifest. If Privilege is not a member, the SetPrivilege() call fails.

Subsequent calls to the framework that require privileges inherit the privilege value previously established by SetPrivilege(). The CSSM will perform pointer validation checks on the API caller before servicing the API call. If OK, then the Privilege value is supplied to the SPI function.

Internally, CSSM builds and maintains privilege information based on the chosen scope of the implementation. The scope may be dictated by the capabilities of the platform hosting the CSSM. If threading is available, the privilege value may be associated with the thread ID of the currently executing thread. In this scenario, CSSM may manage a table of tuples consisting of threadID and privilege value. If threading is not available, the privilege value may be global to the process.

Since the selected privilege value is shared, the application programmer should take precautions to reset the privilege value whenever program flow leaves the caller's module and again when control flow returns. In general, anytime there is a possibility for SetPrivilege() to be called while within the context of the security critical section, SetPrivilege() should be called again. Otherwise, the module receiving execution control could have called SetPrivilege() resulting in the privilege value being reset.

Data structures used to maintain the global privilege value should be initialized in CSSM_Init(). This includes lock initialization and preliminary resource allocation. CSSM_Init() is assumed to be idempotent with respect to shared structure initialization. This means CSSM_Init() will ensure a single thread initializes the shared structure and subsequent calls to CSSM_Init() will not re-initialize it. A reference count of calls to CSSM_Init() is needed to ensure matching calls to CSSM_Terminate() are handled.

Resource cleanup is performed at CSSM_Terminate(), after the reference count falls to zero. The last call to CSSM_Terminate() results in shared resources being freed and lock structures being released.

PARAMETERS

Privilege (input)

The CSSM_PRIVILEGE value to be applied to subsequent calls to CSSM interfaces.

ERRORS

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

NAME

CSSM_GetPrivilege

SYNOPSIS


CSSM_RETURN CSSM_GetPrivilege
    (CSSM_PRIVILEGE_PTR Privilege)

DESCRIPTION

The CSSM_GetPrivilege() function returns the CSSM_PRIVILEGE value currently established in the framework.

PARAMETERS

Privilege (output)

The CSSM_PRIVILEGE value currently set.

ERRORS

See General Error Codes and Common Error Codes and Values sections.
Previous section.

NAME

CSSM_GetModuleGUIDFromHandle

SYNOPSIS


CSSM_RETURN CSSMAPI CSSM_GetModuleGUIDFromHandle
    (CSSM_MODULE_HANDLE ModuleHandle,
    CSSM_GUID_PTR ModuleGUID)

DESCRIPTION

Returns the GUID of the attached module identified by the specified handle.

PARAMETERS

ModuleHandle (input)

Handle of the module for which the GUID should be returned.

ModuleGUID (output)

GUID of the module associated with ModuleHandle.n.

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 sections.

SEE ALSO


CSSM_GetSubserviceUIDFromHandle()
Previous section.

NAME

CSSM_GetSubserviceUIDFromHandle

SYNOPSIS


CSSM_RETURN CSSMAPI CSSM_GetSubserviceUIDFromHandle
    (CSSM_MODULE_HANDLE ModuleHandle,
    CSSM_SUBSERVICE_UID_PTR SubserviceUID)

DESCRIPTION

This function completes a structure containing the persistent unique identifier of the attached module subservice, as identified by the input handle.

PARAMETERS

ModuleHandle (input)

Handle of the module subservice for which the subservice unique identifier should be returned.

SubserviceUID (output)

Subservice UID value associated with ModuleHandle. The caller has to allocate the buffer.

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 sections.

SEE ALSO


CSSM_GetModuleGUIDFromHandle()

EMM Module Management Functions

The manpages for EMM Module Management Functions can be found at the end of this chapter. The man-page definition for the EMM Module Management function is presented in this section.
Previous section.

NAME

CSSM_ListAttachedModuleManagers

SYNOPSIS


CSSM_RETURN CSSMAPI CSSM_ListAttachedModuleManagers 
    (uint32 *NumberOfModuleManagers,
    CSSM_GUID_PTR ModuleManagerGuids)

DESCRIPTION

This function returns a list of GUIDs for the currently attached/active

PARAMETERS

NumberOfModuleManagers (input/output)

The number of GUIDs in the array. If the array is not large enough, then the actual number needed is returned and the error CSSMERR_CSSM_BUFFER_TOO_SMALL is returned. The caller should then allocate an appropriately-sized list and call the function again. If the supplied list is larger than needed, the number of module managers found is returned and no error is set.

ModuleManagerGuids (input/output)

A pointer to an array of CSSM_GUID structures, one per active module manager. The caller allocates this array.

RETURN VALUE

ERRORS


CSSMERR_CSSM_BUFFER_TOO_SMALL
CSSMERR_CSSM_INVALID_GUID

Utility Functions

The manpages for Utility Functions can be found at the end of this chapter. The man-page definition for the Utility function is presented in this section.
Previous section.

NAME

CSSM_GetAPIMemoryFunctions

SYNOPSIS


CSSM_RETURN CSSMAPI CSSM_GetAPIMemoryFunctions
    (CSSM_MODULE_HANDLE AddInHandle,
    CSSM_API_MEMORY_FUNCS_PTR AppMemoryFuncs)

DESCRIPTION

This function retrieves the memory function table associated with the security service service module identified by the input handle.

PARAMETERS

AddInHandle (input)

The handle to the security service service module that is associated with the requested memory function table.

AppMemoryFuncs (output)

Pointer to an empty memory functions table. Upon function return, the table is filled with the memory function pointers associated with the specified attach handle. Caller has to allocate the buffer.

RETURN VALUE

CSSM_OK if the function was successful.

ERRORS

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

SEE ALSO

None.

Contents Next section Index