Common Security: CDSA and CSSM

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

Key Recovery APIs

Module Management Operations

The generic CSSM module management functions are used to install and attach a Key Recovery add-in service module. These functions are specified in detail in the CSSM Application Programming Interface. The applicable generic management functions include:

CSSM_ModuleInstall
CSSM_ModuleUninstall
CSSM_ListModules
CSSM_ModuleAttach
CSSM_ModuleDetach
CSSM_GetModuleInfo
CSSM_FreeModuleInfo

The new management function, CSSM_KR_SetEnterpriseRecoveryPolicy, is directly supported by the Key Recovery Module Manager.

CSSM_DATA_PTR CSSMAPI CSSM_KR_SetEnterpriseRecoveryPolicy(): Establishes the filename which contains the enterprise-based key recovery policy function for use by the KRMM in CSSM.

Key Recovery Context Operations

CSSM_BOOL CSSMAPI CSSM_KR_CreateRecoveryRegistrationContext(): Accepts as input the handle to the KRSP and returns a handle to a key recovery registration context. This context must be used when registering with a key recovery server or agent.
CSSM_DATA_PTR CSSMAPI CSSM_KR_CreateRecoveryEnablementContext(): Accepts as input the handle to the KRSP and the key recovery profiles of the local and remote parties, and returns a handle to the key recovery context for the given parties under the key recovery mechanism specified.
CSSM_BOOL CSSMAPI CSSM_KR_CreateRecoveryRequestContext(): Accepts as input the handle to the KRSP, the key recovery fields (from which the key is to be recovered), and the profile of the local party, and returns a handle to the key recovery context for the given party and key recovery fields.
CSSM_DATA_PTR CSSMAPI CSSM_KRPolicyInfo(): Returns the key recovery policy information pertaining to a given cryptographic context.

Key Recovery Registration Operations

CSSM_RETURN CSSMAPI CSSM_KR_RegistrationRequest(): Performs a recovery registration request operation. A callback may be supplied to allow the registration operation to query for additional input information, if necessary. The result of the registration request operation is a reference handle that may be used to invoke the CSSM_KR_RegistrationRetrieve function.
CSSM_RETURN CSSMAPI CSSM_KR_RegistrationRetrieve(): Completes a recovery registration operation. The result of the registration operation is returned in the form of a key recovery profile.

Key Recovery Enablement Operations

CSSM_RETURN CSSMAPI CSSM_KR_GenerateRecoveryFields(): Accepts as input the key recovery context handle, the session-based recovery parameters and the cryptographic context handle, and several other parameters of relevance to the KRSP, and outputs a buffer of the appropriate mechanism-specific key recovery fields in a format defined and interpreted by the specific KRSP involved. It returns a cryptographic context handle, which can be input to the encryption APIs in the cryptographic framework.
CSSM_RETURN CSSMAPI CSSM_KR_ProcessRecoveryFields(): Accepts as input the key recovery context handle, the cryptographic context handle, several other parameters of relevance to a KRSP, and the unparsed buffer of key recovery fields. It returns with a cryptographic context handle, which can then be used for the decryption APIs in the cryptographic framework.

Key Recovery Request Operations

CSSM_RETURN CSSMAPI CSSM_KR_RecoveryRequest(): Performs a recovery request operation for one or more recoverable keys. A callback may be supplied to allow the recovery request operation to query for additional input information, if necessary. The result of the recovery request operation is a results handle that may be used to obtain each recovered key and its associated meta information using the CSSM_KR_GetRecoveredObject function.
CSSM_RETURN CSSMAPI CSSM_KR_RecoveryRetrieve(): Completes a recovery request operation for one or more recoverable keys. The result of the recovery operation is a results handle that may be used to obtain each recovered key and its meta information using the CSSM_KRGetRecoveredObject function.
CSSM_RETURN CSSMAPI CSSM_KR_GetRecoveredObject(): Retrieves a single recovered key and its associated meta information.
CSSM_RETURN CSSMAPI CSSM_KR_RecoveryRequestAbort(): Terminates a recovery request operation and releases any state information associated with it.

Extensibility Functions

CSSM_RETURN CSSMAPI CSSM_KR_PassThrough(): Accepts as input an operation ID and an arbitrary set of input parameters. The operation ID may specify any type of operation the KR wishes to export. Such operations may include queries or services specific to the key recovery mechanism implemented by the KR module.

An Example Application Using Key Recovery APIs

To understand the role of key recovery in encrypted data communication, consider the following scenario, illustrated in Encrypted Communications without Key Recovery . A communication protocol running on behalf of party A sends an encrypted message to its counterpart running on behalf of party B. To encrypt/decrypt message data, the communication protocol implementations use the CSSM APIs as follows:

A invokes "CSSM_CSP_CreateSymmetricContext" and obtains a cryptographic context handle (HA1) representing the encryption key.
A invokes the "CSSM_EncryptData" API and provides the cryptographic context handle (HA1) as a parameter along with the message to be encrypted.
A obtains the encrypted message and sends it to B. A also sends B the data key via the key exchange mechanism. The encrypted message can be intercepted by law-enforcement agencies.
B obtains the data key from A through the key exchange mechanism and invokes the "CSSM_CSP_CreateSymmetricContext" to obtain a cryptographic context handle (HB1) representing the encryption key used by A.
B invokes the "CSSM_DecryptData" and provides the key handle (HB1) as a parameter along with the message to be decrypted.
B obtains the decrypted message sent by A. Figure: Encrypted Communications without Key Recovery
In the above scenario, after the key handles (and keys) are destroyed there is no practical way to decipher the contents of the encrypted message A sent to B by any law-enforcement agency. If good or strong encryption is used, deciphering the encrypted message is impractical (for example, either too expensive or impossible to decipher in useful time). Hence, key recovery techniques must be employed.
To illustrate the use of key recovery, we modify the scenario of Encrypted Communications without Key Recovery to take advantage of KR-API functions, as illustrated in Encrypted Communications with Key Recovery Enablement . The CSSM ensures that key recovery can be performed using the messages being passed between A and B, as seen from the intercept point.
A invokes the "CSSM_CSP_CreateSymmetricContext" and obtains a cryptographic context handle (HA1) representing the encryption key. In contrast to the previous scenario (Fig. 1(a)) where A could use the handle HA1 to encrypt the message, here, the direct use of key handle HA1 would be rejected by the "CSSM_EncryptData". The encrypt API will only accept a separate cryptographic context handle generated by the CSSM.
A invokes the "CSSM_KR_GenerateRecoveryFields" to obtain the new cryptographic context handle, HA2, that would be used for encryption. The "CSSM_KR_GenerateRecoveryFields" also generates a set of key recovery fields that are returned along with the HA2 to A.
Note that this is a simplified example. In reality, the "CSSM_KR_GenerateRecoveryFields" function requires a key recovery context handle in addition to the cryptographic context handle.
A invokes the "CSSM_EncryptData" and provides as parameters the cryptographic context handle (HA2), and the message to be encrypted.
A obtains the encrypted message and KR fields, and sends them to B. The data key is also sent to B using the key exchange mechanism. The encrypted message and KR fields can be intercepted by law enforcement agencies.
B retrieves the data key using the key exchange mechanism and invokes the "CSSM_CSP_CreateSymmetricContext" to obtain a cryptographic context handle (HB1) for the encryption key used by A. In contrast to the previous scenario (Fig. 1(a)) where B could use the handle HB1 to decrypt the message, here the direct use of HB1 would be rejected by the decrypt operation. The decrypt will only accept a separate cryptographic context handle generated by the CSSM. Figure: Encrypted Communications with Key Recovery Enablement
B invokes the "CSSM_KR_ProcessRecoveryFields" of the CSSM and provides the handle (HB1) as a parameter along with the KR fields to be processed. If the recovery fields process correctly, a new cryptographic context handle HB2 is returned, which B must use to decrypt the message. Note that without processing the KR fields, B could not obtain handle HB2 and, consequently, could not decrypt the message.
Note that this is a simplified example. In reality, the "CSSM_KR_ProcessRecoveryFields" function requires a key recovery context handle in addition to the cryptographic context handle.
B invokes the "CSSM_DecryptData" and provides the handle (HB2) as a parameter along with the message to be decrypted.
B obtains the decrypted message sent by A.
law enforcement picks up the recovery fields and obtains the key used by A and B with the help of one or more trusted third parties. To do so, law enforcement must authenticate itself to the recovery service, must present the KR fields and must demonstrate that it has the legal credentials (for example, Court warrant) for recovering the key.

The second scenario discussed above points out one of the salient features of the CSSM, namely that a key cannot be used to encrypt or decrypt a message without mediation by the CSSM. Hence, the CSSM cannot be bypassed.

Data Structures

CSSM_KR_HANDLE

This data structure represents the key recovery module handle. The handle value is a unique pairing between a key recovery module and an application that has attached that module. KR handles can be returned to an application as a result of the CSSM_ModuleAttach function.

typedef uint32 CSSM_KRSP_HANDLE /* Key Recovery Service
                                    Provider Handle */

CSSM_KR_NAME

This data structure contains a typed name. The namespace type specifies what kind of name is contained in the third parameter.

typedef struct cssm_kr_name {
     uint8 type; /* namespace type */
     uint8 length; /* name string length */
     char *name; /* name string */
} CSSM_KR_NAME

Definition

type: The type of the key recovery name space.
length: The length of the name (in bytes).
name: The name represented in a string.

CSSM_KR_PROFILE

This data structure encapsulates the key recovery profile for a given user and a given key recovery mechanism.

typedef struct cssm_kr_profile {
    CSSM_KR_NAME UserName; /* name of the user */
    CSSM_DATA_PTR UserCertificate; /* public key certificate
                                        of the user */

    uint8 LE_KRANum; /* number of KRA cert chains in the
                                        following list */
    CSSM_CERT_LIST_PTR LE_KRACertChainList; /* list of Law
                             enforcement KRA certificate chains*/

    uint8 ENT_KRANum; /* number of KRA cert chains in the
                                        following list */
    CSSM_CERT_LIST_PTR ENT_KRACertChainList; /* list of
                              Enterprise KRA certificate chains*/

    CSSM_DATA_PTR ENTAuthenticationInfo; /* authentication
                       information for enterprise key recovery */

    uint8 INDIV_KRANum; /* number of KRA cert chains in the
                                                following list */
    CSSM_CERT_LIST_PTR INDIV_KRACertChainList; /* list of
                              Individual KRA certificate chains*/

    CSSM_DATA_PTR INDIVAuthenticationInfo; /* authentication
                       information for individual key recovery */

    uint32 KRFlags;   /* flag values to be interpreted by KRSP */

    CSSM_DATA_PTR Extensions; /* reserved for extensions specific
                                                      to KRSPs */

} CSSM_KR_PROFILE, *CSSM_KR_PROFILE_PTR;

Definition

UserName: The user's name.
UserCertificate: The user's certificate chain, used for identity and authentication when performing policy evaluation.
LE_KRANum: The number of LE Key Recovery agents in the following list.
LE_KRACertChainList: A list of certificate chains, one per Key Recovery Agent authorized for LE key recovery.
ENT_KRANum: The number of ENT Key Recovery agents in the following list.
ENT_KRACertChainList: A list of certificate chains, one per Key Recovery Agent authorized for ENT key recovery.
ENTAuthenticationInfo: Authentication information to be used for ENT key recovery.
INDIV_KRANum: The number of INDIV Key Recovery agents in the following list.
INDIV_KRACertChainList: A list of certificate chains, one per Key Recovery Agent authorized for INDIV key recovery.
INDIVAuthenticationInfo: Authentication information to be used for INDIV key recovery.
KRFlags: A bit mask specifying the user's selected service options specific to the selected key recovery service module.
Extensions: Reserved for future use.

CSSM_EXEMPTION_MASK

The Key Recovery Module Manager defines these CSSM_EXEMPTION_MASK flags in addition to those defined by CSSM and other CSSM module managers. These flags represent exemption from specified, built-in checks performed by the KRMM. Authorized applications use the CSSM_RequestCssmExemption function to request exemptions. Exemption is granted if the application's credentials can be authenticated by CSSM based on selected roots of trust.

typedef uint32 CSSM_EXEMPTION_MASK

#define CSSM_EXEMPT_LE_KR 0x00000004   /* ask exemption from LE
                                       key recovery */
#define CSSM_EXEMPT_ENT_KR 0x00000008  /* ask exemption from ENT
                                       key recovery */

CSSM_CERT_LIST

This data structure encapsulates a generic list of items.

typedef struct cssm_cert_list {
    uint32 NumberCerts;
    CSSM_DATA_PTR CertList;
} CSSM_CERT_LIST, *CSSM_CERT_LIST_PTR;

Definition

NumberCerts: Count of the number of certs in the list.
CertList: Pointer to a list of certificate items.

CSSM_CONTEXT_ATTRIBUTE Extensions

The key recovery context creation operations return key recovery context handles that are represented as cryptographic context handles. In order to use the CSSM_CONTEXT data structure to implement key recovery contexts, the CSSM_CONTEXT will be used to hold new types of attributes, as shown below:

typedef struct cssm_context_attribute {
    uint32 AttributeType;
    uint32 AttributeLength;
    union cssm_context_attribute_value {
      char *String;
      uint32 Uint32;
      CSSM_CRYPTO_DATA_PTR Crypto;
      CSSM_KEY_PTR Key;
      CSSM_DATA_PTR Data;
      CSSM_DATE_PTR Date;
      CSSM_RANGE_PTR Range;
      CSSM_KR_PROFILE_PTR KRProfile;
    } Attribute;
    } CSSM_CONTEXT_ATTRIBUTE, *CSSM_CONTEXT_ATTRIBUTE_PTR;

All but the last member of the union above are part of the core CSSM Application Programming Interface. The descriptions of these basic fields and members are in the CSSM Application Programming Interface. The KRProfile member of the union has been added specifically to support key recovery contexts, and is described below.

Definition

KRProfile: A pointer to the key recovery profile structure that defines the user parameters with respect to the key recovery process.

CSSM_ATTRIBUTE_TYPE Additions

Several new attribute types were defined to support the key recovery context attributes. The following definitions are added to the enumerated type CSSM_ATTRIBUTE_TYPE:

CSSM_ATTRIBUTE_KRPROFILE_LOCAL   = CSSM_ATTRIBUTE_LAST+1,
                /* local entity profile */
CSSM_ATTRIBUTE_KRPROFILE_REMOTE  = CSSM_ATTRIBUTE_LAST+2,
                /* remote entity profile */

CSSM_KRSUBSERVICE

Two structures are used to contain all of the static information that describes a key recovery add-in module: the krinfo structure and the krsubservice structure. This descriptive information is securely stored in the CSSM registry when the KR module is installed with CSSM. A key recovery module may implement multiple types of services and organize them as sub-services. For example, a KR module supporting an encapsulation mechanism and an escrow mechanism may organize its implementation as two subservices.

The descriptive information stored in these structures can be queried using the function CSSM_GetModuleInfo() and specifying the key recovery module GUID.

typedef struct cssm_krsubservice {
    uint32 SubServiceId;
    char *Description;      /* Description of this sub service */
    CSSM_CALLER_AUTHENTICATION_MECHANISM AuthenticationMechanism;
} CSSM_KRSUBSERVICE, *CSSM_KRSUBSERVICE_PTR;

Definition

SubServiceId: A unique, identifying number for the sub-service described in this structure.
Description: A string containing a descriptive name or title for this sub-service.
AuthenticationMechanism: An enumerated value defining the credential format accepted by the KR module. When an authentication credential is required by a KR function, the presented credentials must be of the required format.

CSSM_KRINFO

The descriptive information stored in these structures can be queried using the function CSSM_GetModuleInfo() and specifying the key recovery module GUID.

typedef struct cssm_krinfo {
    CSSM_VERSION Version;  /* major and minor version number */
    char *Description;     /* Detailed description of this KR */
    char *Vendor;          /* KRSP Vendor name */
    char *Jurisdiction;    /* Home jurisdiction of the
                                            KRSP installation */
    uint32 NumberSubService;
    CSSM_KRSUBSERVICE_PTR SubService;
} CSSM_KRINFO, *CSSM_KRINFO_PTR;

Definition

Version: The major and minor version number of the add-in module.
Description: A character string containing a general description of this key recovery module.
Vendor: A character string containing the name of the vendor who implemented and manufactured this key recovery module.
Jurisdiction: A character string describing the geographical region where the key recovery module is installed.
NumberOfSubServices: The number of sub-services implemented by this key recovery module. Every KR module implements at least one sub-service.
Subservices: A pointer to an array of sub-service structures. Each structure contains detailed information about that sub-service.

Key Recovery Module Management Operations

The manpages for Key Recovery Module Management Operations can be found at the end of this chapter.

Key Recovery Context Operations

Key recovery contexts are essentially cryptographic contexts. The following API functions deal with the creation of these special types of cryptographic contexts. Once these contexts are created, the regular CSSM context API functions may be used to manipulate these key recovery contexts.

The manpages for Key Recovery Context Operations can be found at the end of this chapter.

Key Recovery Registration Operations

The manpages for Key Recovery Registration Operations can be found at the end of this chapter.

Key Recovery Enablement Operations

The manpages for Key Recovery Enablement Operations can be found at the end of this chapter.

Key Recovery Request Operations

The manpages for Key Recovery Request Operations can be found at the end of this chapter.

Extensibility Functions

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

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

Contents

Next section

Index