Key Recovery APIs

Module Management Operations

• CSSM_ModuleLoad

• CSSM_ModuleUnload

• CSSM_ModuleAttach

• CSSM_ModuleDetach

Key Recovery Context Operations

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_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_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_KR_GetPolicyInfo()

Returns the key recovery policy information pertaining to a given cryptographic context.

Key Recovery Registration Operations

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_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_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_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_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_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_KR_GetRecoveredObject()

Retrieves a single recovered key and its associated meta information.

CSSM_KR_RecoveryRequestAbort()

Terminates a recovery request operation and releases any state information associated with it.

Extensibility Functions

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 CSSM_CSP_CreateSymmetricContext() to obtain a cryptographic context handle (HB1) representing the encryption key used by A.

• B invokes 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.

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 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 CSSM_EncryptData(). The encrypt API will only accept a separate cryptographic context handle generated by the CSSM.

• A invokes CSSM_KR_CreateRecoveryEnablementContext() and obtains a HA2, representing the local, and optionally the remote, key recovery profiles.

• Using handles HA1 and HA2, A invokes CSSM_KR_GenerateRecoveryFields() to update the cryptographic context referenced by handle HA1 for subsequent encryption operations based on the same context information. The CSSM_KR_GenerateRecoveryFields() call also generates a set of key recovery fields that are returned to A.

• A invokes CSSM_EncryptData() and provides as parameters the cryptographic context handle (HA1), and the message to be encrypted.

• A obtains the encrypted message and sends it to B, along with the key recovery fields. 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 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
  

• In preparation, B invokes CSSM_KR_CreateRecoveryEnablementContext() to obtain the context handle HB2. This key recovery enablement context contains information used to process the key recovery fields in order to verify their integrity.

• B invokes CSSM_KR_ProcessRecoveryFields() and provides the two handles HB1 and HB2 as parameters If the recovery fields process correctly, the cryptographic context referenced by HB1 is updated and can be used in subsequent decrypt API calls to decrypt the message.

• B invokes CSSM_DecryptData() and provides the handle (HB1) 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_KRSP_HANDLE

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

CSSM_KR_NAME

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

typedef struct cssm_kr_profile {
    CSSM_KR_NAME UserName; /* name of the user */
    CSSM_CERTGROUP_PTR UserCertificate; /* public key certificate
                                        of the user */
    CSSM_CERTGROUP_PTR KRSCertChain;    /* cert chain for the 
                                              KRSP coordinator */
    uint8 LE_KRANum; /* number of KRA cert chains in the
                                                following list */
    CSSM_CERTGROUP_PTR LE_KRACertChainList; /* list of Law
                             enforcement KRA certificate chains*/

    uint8 ENT_KRANum; /* number of KRA cert chains in the
                                                following list */
    CSSM_CERTGROUP_PTR ENT_KRACertChainList; /* list of
                              Enterprise KRA certificate chains*/
    uint8 INDIV_KRANum; /* number of KRA cert chains in the
                                                following list */
    CSSM_CERTGROUP_PTR INDIV_KRACertChainList; /* list of
                              Individual KRA certificate chains*/

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

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

    CSSM_DATA_PTR KRSPExtensions; /* 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.

KRSCertChain

The certificate chain of Key Recovery Coordinator.

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.

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.

INDIV_AuthenticationInfo

Authentication information to be used for INDIV key recovery.

KRSPFlags

A bit mask specifying the user's selected service options specific to the selected key recovery service module.

KRSPExtensions

Reserved for future use.

CSSM_ATTRIBUTE_TYPE Additions

/* Attribute data type tags */
#define CSSM_ATTRIBUTE_DATA_KR_PROFILE 0x03000000

/* local entity profile */
CSSM_ATTRIBUTE_KRPROFILE_LOCAL 
    = (CSSM_ATTRIBUTE_DATA_KR_PROFILE | 32),

/* remote entity profile */
CSSM_ATTRIBUTE_KRPROFILE_REMOTE
    = (CSSM_ATTRIBUTE_DATA_KR_PROFILE | 33),

CSSM_KR_POLICY_FLAGS

 

#define CSSM_KR_INDIV           (0x00000001)
#define CSSM_KR_ENT             (0x00000002)
#define CSSM_KR_LE_MAN          (0x00000004)
#define CSSM_KR_LE_USE          (0x00000008)
#define CSSM_KR_LE              (CSSM_KR_LE_MAN|CSSM_KR_LE_USE)
#define CSSM_KR_OPTIMIZE        (0x00000010)
#define CSSM_KR_DROP_WORKFACTOR (0x00000020)

CSSM_KR_POLICY_LIST_ITEM

 

typedef struct cssm_kr_policy_list_item {
    struct kr_policy_list_item  *next;
    CSSM_ALGORITHMS AlgorithmId;
    CSSM_ENCRYPT_MODE Mode;
    uint32 MaxKeyLength;
    uint32 MaxRounds;
    uint8 WorkFactor;
    CSSM_KR_POLICY_FLAGS PolicyFlags;
    CSSM_CONTEXT_TYPE AlgClass;
} CSSM_KR_POLICY_LIST_ITEM, *CSSM_KR_POLICY_LIST_ITEM_PTR;

Definitions

AlgorithmID

The algorithm ID.

Mode

Encrypt mode. CSSM_ALGCLASS_SYMMETRIC and CSSM_ALGCLASS_ASYMMETRIC are valid options in this case.

Class

The class of the indicated algorithm.

MaxKeyLength

The maximum key length allowed for this encryption algorithm ID.

MaxRounds

Maximum number of encryption rounds.

WorkFactor

The maximum allowed workfactor value that may be used for law enforcement key recovery.

PolicyFlags

The mandatory policy flags.

AlgClass

CSSM_ALGCLASS_SYMMETRIC and CSSM_ALGCLASS_ASYMMETRIC are valid options in this case.

CSSM_KR_POLICY_INFO

 

typedef struct cssm_kr_policy_info {
    CSSM_BOOL krbNotAllowed;
    uint32 numberOfEntries;
    CSSM_KR_POLICY_LIST_ITEM *policyEntry;
} CSSM_KR_POLICY_INFO, *CSSM_POLICY_KR_INFO_PTR;

krbNotAllowed

If CSSM_TRUE, generation of key recovery blocks is not allowed.

numberOfEntries

Number of entries in the policyEntry array.

policyEntry

A list of CSSM_KR_POLICY_LIST_ITEM, containing the encryption strength and other information for each encryption algorithm.

Key Recovery MDS Relation

KR service modules store information in two MDS relations:

• Primary EMM Service Provider Relation

• KR Primary Relation.

CSSM uses the Primary EMM Service Provider Relation during module management operations. This relation is defined in Module Directory Services. Applications use the KR Primary Relation (see ) to locate and select specific KR modules.

Key Recovery Module Management Operations

NAME

CSSM_KR_SetEnterpriseRecoveryPolicy

SYNOPSIS

CSSM_RETURN CSSMAPI CSSM_KR_SetEnterpriseRecoveryPolicy
    (const CSSM_DATA *RecoveryPolicyFileName,
    const CSSM_CRYPTO_DATA *OldPassPhrase,
    const CSSM_CRYPTO_DATA *NewPassPhrase)

DESCRIPTION

This call establishes the identity of the file that contains the enterprise key recovery policy function. The first time this function is invoked, the old passphrase is established for access control purposes. Subsequent invocations of this function will require the original passphrase to be supplied in order to update the filename of the policy function. Optionally the passphrase can be changed from the oldpassphrase to the newpassphrase on subsequent invocations.

The policy function module is operating system platform specific (for Windows 95 and Windows NT, it may be a DLL, for UNIX platforms, it may be a separate executable which gets launched by the KRMM. It is expected that the policy function file will be protected using the available protection mechanisms of the operating system platform. The policy function is expected to conform to the following interface:

boolean EnterpriseRecoveryPolicy(CSSM_CONTEXT CryptoContext);

The Boolean return value of this policy function will determine whether enterprise-based key recovery is mandated for the given cryptographic operation.

PARAMETERS

RecoveryPolicyFileName (input)

A pointer to a CSSM_DATA structure that contains the file name of the module that contains the enterprise key recovery policy function. The filename may be a fully qualified pathname or a partial pathname.

OldPassPhrase (input)

The current, active passphrase that controls access to this operation.

NewPassPhrase (input/optional)

A new passphrase that becomes the current, active passphrase after the execution of this function. It must be used to control access to future invocations of this operation.

RETURN VALUES

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

CSSM_KR_INVALID_FILENAME

Invalid policy file name.

CSSM_MEMORY_ERROR

Memory error.

CSSM_KR_INVALID_POINTER

Invalid pointer.

CSSM_KR_INVALID_PASSWORD

Invalid password.

Key Recovery Context Operations

NAME

CSSM_KR_CreateRecoveryRegistrationContext

SYNOPSIS

CSSM_RETURN CSSMAPI CSSM_KR_CreateRecoveryRegistrationContext
    (CSSM_KRSP_HANDLE KRSPHandle,
    CSSM_CC_HANDLE *NewContext)

DESCRIPTION

This call creates a key recovery registration context based on a KRSP handle (which determines the key recovery mechanism that is in use). This context may be used for performing registration with key recovery servers and/or agents.

PARAMETERS

KRSPHandle (input)

The handle to the KRSP that is to be used.

NewContext (output)

A handle to the key recovery registration context. This value will be set to CSSM_INVALID_HANDLE if the function fails.

RETURN VALUES

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

CSSM_INVALID_KR_HANDLE

Invalid handle.

CSSM_MEMORY_ERROR

Memory error.

SEE ALSO

CSSM_KR_RegistrationRequest()

NAME

CSSM_KR_CreateRecoveryEnablementContext

SYNOPSIS

CSSM_RETURN CSSMAPI CSSM_KR_CreateRecoveryEnablementContext
    (CSSM_KRSP_HANDLE KRSPHandle,
    const CSSM_KR_PROFILE *LocalProfile,
    const CSSM_KR_PROFILE *RemoteProfile,
    CSSM_CC_HANDLE *NewContext)

DESCRIPTION

This call creates a key recovery enablement context based on a KRSP handle (which determines the key recovery mechanism that is in use), and key recovery profiles for the local and remote parties involved in a cryptographic exchange. A handle to the key recovery enablement context is returned. It is expected that the LocalProfile will contain sufficient information to perform LE, ENT and IND key recovery enablement, whereas the RemoteProfile will contain information to perform LE and ENT key recovery enablement only. However, any and all of the fields within the profiles may be set to NULL-in this case, default values for these fields are to be used when performing the recovery enablement operations.

PARAMETERS

KRSPHandle (input)

The handle to the KRSP that is to be used.

LocalProfile (input)

The key recovery profile for the local client.

RemoteProfile (input/optional)

The key recovery profile for the remote client.

NewContext (output)

A handle to the key recovery enablement context. This value will be set to CSSM_INVALID_HANDLE if the function fails.

RETURN VALUES

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

CSSM_INVALID_KR_HANDLE

Invalid handle.

CSSM_KR_INVALID_PROFILE

Invalid profile structure.

CSSM_KR_INVALID_PTR

Bad pointer.

CSSM_MEMORY_ERROR

Memory error.

SEE ALSO

CSSM_KR_GenerateRecoveryFields()
CSSM_KR_ProcessRecoveryFields()

NAME

CSSM_KR_CreateRecoveryRequestContext

SYNOPSIS

CSSM_RETURN CSSMAPI CSSM_KR_CreateRecoveryRequestContext
    (CSSM_KRSP_HANDLE KRSPHandle,
    const CSSM_KR_PROFILE *LocalProfile,
    CSSM_CC_HANDLE *NewContext)

DESCRIPTION

This call creates a key recovery request context based on a KRSP handle (which determines the key recovery mechanism that is in use) and the profile for the local client. A handle to the key recovery request context is returned.

PARAMETERS

KRSPHandle (input)

The handle to the KRSP that is to be used.

LocalProfile (input)

The key recovery profile for the local client. This parameter is relevant only when the KRFlags value is set to KR_INDIV.

NewContext (output)

A handle to the key recovery context. This value will be set to CSSM_INVALID_HANDLE if the function fails.

RETURN VALUES

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

CSSM_INVALID_KR_HANDLE

Invalid handle.

CSSM_KR_INVALID_PROFILE

Invalid profile.

CSSM_MEMORY_ERROR

Memory error.

SEE ALSO

CSSM_KR_RecoveryRequest()
CSSM_KR_RecoveryRetrieve()

NAME

CSSM_KR_GetPolicyInfo

SYNOPSIS

CSSM_RETURN CSSM_KR_GetPolicyInfo
    (CSSM_CC_HANDLE CCHandle,
    CSSM_KR_POLICY_FLAGS *EncryptionProhibited,
    uint32 *WorkFactor)

DESCRIPTION

This call returns the key recovery policy information for a given cryptographic context. The information returned constitutes the key recovery extension fields of a cryptographic context.

PARAMETERS

CCHandle (input)

The handle to the cryptographic context that is to be used.

EncryptionProhibited (output)

The usability field for law enforcement and enterprise key recovery. Possible values are:
- KR_LE
  Signifies that law enforcement key recovery enablement needs to be done.
- KR_ENT
  Signifies that enterprise key recovery enablement is required.

WorkFactor (output)

The maximum permissible workfactor value that may be used for law enforcement key recovery.

RETURN VALUES

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

CSSM_KR_INVALID_CC_HANDLE

Invalid crypto context handle.

CSSM_MEMORY_ERROR

Memory error.

Key Recovery Registration Operations

NAME

CSSM_KR_RegistrationRequest

SYNOPSIS

CSSM_RETURN CSSMAPI CSSM_KR_RegistrationRequest
    (CSSM_CC_HANDLE RecoveryRegistrationContext,
    const CSSM_DATA *KRInData,
    const CSSM_ACCESS_CREDENTIALS *AccessCredentials,
    CSSM_KR_POLICY_FLAGS KRFlags,
    sint32 *EstimatedTime,
    CSSM_HANDLE_PTR ReferenceHandle)

DESCRIPTION

This function initiates a key recovery registration operation. The KRInData contains known input parameters for the recovery registration operation. A UserCallback function can be supplied to allow the registration operation to interact with the user interface, if necessary.

This function returns a ReferenceHandle and an EstimatedTime for completion of the request. The ReferenceHandle must be used to retrieve the registration result using the CSSM_KR_RegistrationRetrieve() function after the EstimatedTime has elapsed. The return value for this function indicates whether the request was successfully initiated.

PARAMETERS

RecoveryRegistrationContext (input)

The handle to the key recovery registration context.

KRInData (input)

Input data for key recovery registration.

AccessCredentials (input/optional)

User access credentials, including certificates, samples (password, biometrics) and callback function and context pointers used to authenticate the caller.

KRFlags (input)

Flag values for recovery registration. Defined values are:

• KR_INDIV-registration for individual key recovery

• KR_ENT-registration for enterprise key recovery

• KR_LE-registration for law enforcement key recovery

EstimatedTime (output)

The estimated time after which this call should be repeated to obtain registration results. This is set to a non-zero value only when the KRProfile parameter is NULL. When the local service provider module or the key recovery server cannot estimate the time required to perform the requested service, the output value for estimated time is CSSM_ESTIMATED_TIME_UNKNOWN.

ReferenceHandle (output)

A handle that references the outstanding registration request. This handle must be used to retrieve the registration result using the function CSSM_KR_RegistrationRetrieve.

RETURN VALUES

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

CSSM_KR_INVALID_HANDLE

Invalid registration handle.

CSSM_KR_INVALID_POINTER

Invalid pointer.

CSSM_MEMORY_ERROR

Memory error.

SEE ALSO

CSSM_KR_CreateRecoveryRegistrationContext()
CSSM_KR_RecoveryRetrieve()

NAME

CSSM_KR_RegistrationRetrieve

SYNOPSIS

CSSM_RETURN CSSMAPI CSSM_KR_RegistrationRetrieve
    (CSSM_KRSP_HANDLE KRSPHandle,
    const CSSM_ACCESS_CREDENTIALS *AccessCredentials,
    sint32 *EstimatedTime,
    CSSM_KR_PROFILE_PTR *KRProfile)

DESCRIPTION

This function completes a key recovery registration operation by returning the profile information generated as a result of a successful key recovery registration process. It is possible that the key recovery registration process has not yet completed. In this case, the returned EstimatedTime is the updated estimate for completion of the registration procedure. If the profile pointer is NULL and the estimated time is greater than zero, the caller should repeat this call after the specified time to retrieve the profile structure.

PARAMETERS

KRSPHandle (input)

The handle of the KR module to perform this operation.

AccessCredentials (input/optional)

User access credentials, including certificates, samples (password, biometrics) and callback function and context pointers used to authenticate the caller.

EstimatedTime (output)

The estimated time after which this call should be repeated to obtain registration results. This is set to a non-zero value only when the KRProfile result is NULL. When the local service provider module or the key recovery server cannot estimate the time required to perform the requested service, the output value for estimated time is CSSM_ESTIMATED_TIME_UNKNOWN.

KRProfile (output)

The key recovery profile that is filled in by the registration operation.

RETURN VALUES

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

CSSM_KR_INVALID_HANDLE

Invalid reference handle.

CSSM_MEMORY_ERROR

Memory error.

SEE ALSO

CSSM_KR_CreateRecoveryRegistrationContext()
CSSM_KR_RecoveryRequest()

Key Recovery Enablement Operations

NAME

CSSM_KR_GenerateRecoveryFields

SYNOPSIS

CSSM_RETURN CSSMAPI CSSM_KR_GenerateRecoveryFields
    (CSSM_CC_HANDLE KeyRecoveryContext,
    CSSM_CC_HANDLE CryptoContext,
    const CSSM_DATA *KRSPOptions,
    CSSM_KR_POLICY_FLAGS KRFlags,
    CSSM_DATA_PTR KRFields)

DESCRIPTION

This function generates the key recovery fields for a cryptographic association given the key recovery context, the session specific key recovery attributes, and the handle to the cryptographic context containing the key that is to be made recoverable. The session attributes and the flags are not interpreted at the KRMM layer. The cryptographic context referenced by the CryptoContext handle is updated and will be used for subsequent encrypt API calls if the key recovery field generation is successful. The generated key recovery fields are returned as an output parameter. The KRFlags parameter may be used to fine tune the contents of the KRFields produced by this operation.

PARAMETERS

KeyRecoveryContext (input)

The handle to the key recovery context for the cryptographic association.

CryptoContext (input)

The cryptographic context handle that points to the session key.

KRSPOptions (input)

The key recovery service provider specific options. These options are not interpreted by the KRMM, but passed on to the KRSP.

KRFlags (input)

Flag values for key recovery fields generation. Defined values are:

• KR_INDIV-signifies that only the individual key recovery fields are to be generated

• KR_ENT-signifies that only the enterprise key recovery fields are to be generated

• KR_LE-signifies that only the law enforcement key recovery fields are to be generated

• KR_OPTIMIZE-signifies that performance optimization options are to be adopted by a KRSP while implementing this operation

• KR_DROP_WORKFACTOR-signifies that the key recovery fields should be generated without using the key size work factor.

KRFields (output)

The key recovery fields in the form of an uninterpreted data blob.

RETURN VALUES

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

CSSM_KR_INVALID_CC_HANDLE

Invalid crypto context handle.

CSSM_KR_INVALID_KRC_HANDLE

Invalid key recovery context handle.

CSSM_KR_INVALID_OPTIONS

Invalid recovery options.

CSSM_MEMORY_ERROR

Memory error.

SEE ALSO

CSSM_KR_CreateRecoveryEnablementContext()
CSSM_KR_ProcessRecoveryFields()

NAME

CSSM_KR_ProcessRecoveryFields

SYNOPSIS

CSSM_RETURN CSSMAPI CSSM_KR_ProcessRecoveryFields
    (CSSM_CC_HANDLE KeyRecoveryContext,
    CSSM_CC_HANDLE CryptoContext,
    const CSSM_DATA *KRSPOptions,
    CSSM_KR_POLICY_FLAGS KRFlags,
    const CSSM_DATA *KRFields)

DESCRIPTION

This call processed a set of key recovery fields given the key recovery context, and the cryptographic context for the decryption operation. If the processing is successful, the cryptographic context is updated and can be used for subsequent decrypt API calls.

PARAMETERS

KeyRecoveryContext (input)

The handle to the key recovery context.

CryptoContext (input)

A handle to the cryptographic context for which the key recovery fields are to be processed.

KRSPOptions (input)

The key recovery service provider specific options. These options are not interpreted by the KRMM, but passed on to the KRSP.

KRFlags (input)

Flag values for key recovery fields processing. Defined values are:

• KR_ENT-signifies that only the enterprise key recovery fields are to be processed

• KR_LE-signifies that only the law enforcement key recovery fields are to be processed

• KR_ALL-signifies that all of the key recovery fields are to be processed

• KR_OPTIMIZE-signifies that performance optimization options are to be adopted by a KRSP while implementing this operation.

KRFields (input)

The key recovery fields to be processed.

RETURN VALUES

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

CSSM_KR_INVALID_CC_HANDLE

Invalid crypto context handle.

CSSM_KR_INVALID_KRC_HANDLE

Invalid key recovery context handle.

CSSM_KR_INVALID_OPTIONS

Invalid recovery options.

CSSM_MEMORY_ERROR

Memory error.

SEE ALSO

CSSM_KR_CreateRecoveryEnablementContext()
CSSM_KR_GenerateRecoveryFields()

Key Recovery Request Operations

NAME

CSSM_KR_RecoveryRequest

SYNOPSIS

CSSM_RETURN CSSMAPI CSSM_KR_RecoveryRequest
    (CSSM_CC_HANDLE RecoveryRequestContext,
    const CSSM_DATA *KRInData,
    const CSSM_ACCESS_CREDENTIALS *AccessCredentials,
    sint32 *EstimatedTime,
    CSSM_HANDLE_PTR ReferenceHandle)

DESCRIPTION

This function initiates a key recovery request operation. The RecoveryRequestContext describes the operation to be performed. The KRInData contains known input parameters for the recovery request operation. A UserCallback function may be supplied to allow the recovery operation to interact with the user interface to obtain additional input, if necessary.

The results of a successful recovery operation are referenced by the ReferenceHandle parameter, which must be used with the CSSM_KR_RecoveryRetrieve() function to obtain a cache of secured, recovered keys. The returned value of EstimatedTime specifies the amount of time the caller should wait before call the retrieve function.

PARAMETERS

RecoveryRequestContext (input)

The handle to the key recovery request context.

KRInData (input)

Input data for key recovery requests. For encapsulation schemes, the key recovery fields are included in this parameter.

AccessCredentials (input/optional)

User access credentials, including certificates, samples (password, biometrics) and callback function and context pointers used to authenticate the caller.

EstimatedTime (output)

The estimated time after which the caller should invoke the CSSM_KR_RecoveryRetrieve() function to obtain a cache of recovered keys. When the local service provider module or the key recovery server cannot estimate the time required to perform the requested service, the output value for estimated time is CSSM_ESTIMATED_TIME_UNKNOWN.

ReferenceHandle (output)

Handle representing this outstanding recovery request. This handle should be used at input to the CSSM_KR_RecoveryRetrieve() function.

RETURN VALUES

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

CSSM_INVALID_KR_HANDLE

Invalid handle.

CSSM_KR_INVALID_HANDLE

Invalid recovery context handle.

CSSM_KR_INVALID_RECOVERY_CONTEXT

Invalid context value.

CSSM_KR_INVALID_POINTER

Invalid pointer.

CSSM_MEMORY_ERROR

Memory error.

SEE ALSO

CSSM_KR_CreateRecoveryRequestContext()
CSSM_KR_RecoveryRetrieve()

NAME

CSSM_KR_RecoveryRetrieve

SYNOPSIS

CSSM_RETURN CSSMAPI CSSM_KR_RecoveryRetrieve
    (CSSM_KRSP_HANDLE KRSPHandle,
    const CSSM_ACCESS_CREDENTIALS *AccessCredentials.
    CSSM_HANDLE ReferenceHandle,
    sint32 *EstimatedTime,
    CSSM_HANDLE_PTR CacheHandle,
    uint32 *NumberOfRecoveredKeys)

DESCRIPTION

This function completes a key recovery request operation. The ReferenceHandle parameter indicates which outstanding recovery request is to be completed. The results of a successful recovery operation are referenced by the ResultsHandle parameter, which may be used with the CSSM_KR_GetRecoveredObject() function to retrieve the recovered keys.

If the results are not available at the time this function is invoked, the CacheHandle is NULL, and the EstimatedTime parameter indicates when this operation should be repeated with the same ReferenceHandle.

PARAMETERS

KRSPHandle (input)

The handle of the KR module to perform this operation.

AccessCredentials (input/optional)

User access credentials, including certificates, samples (password, biometrics) and callback function and context pointers used to authenticate the caller.

ReferenceHandle (input)

Indicates which outstanding recovery request is to be completed.

EstimatedTime (output)

The number of seconds estimated before the set of recovered keys will be returned. A (default) value of zero indicates that the set has been returned as a result of this call. When the local service provider module or the key recovery server cannot estimate the time required to perform the requested service, the output value for estimated time is CSSM_ESTIMATED_TIME_UNKNOWN.

CacheHandle (output)

A reference handle which uniquely identifies the cache of recovered keys. If the object retrieval process has not been completed, the returned cache handle is NULL. A non-NULL cache handle can be used in the CSSM_KR_GetRecoveredObject() function to complete the recovery of an individual key.

NumberOfRecoveredKeys (output)

The number of keys in the cache.

RETURN VALUES

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

CSSM_INVALID_KR_HANDLE

Invalid KR handle.

CSSM_KR_INVALID_HANDLE

Invalid reference handle.

CSSM_MEMORY_ERROR

Memory error.

CSSM_KR_FAIL

Function failed.

SEE ALSO

CSSM_KR_CreateRecoveryRequestContext()
CSSM_KR_RecoveryRequest()
CSSM_KR_GetRecoveredObject()
CSSM_KR_RecoveryRequestAbort()

NAME

CSSM_KR_GetRecoveredObject

SYNOPSIS

CSSM_RETURN CSSMAPI CSSM_KR_GetRecoveredObject
    (CSSM_KRSP_HANDLE KRSPHandle,
    CSSM_HANDLE CacheHandle,
    uint32 IndexInResults,
    CSSM_CSP_HANDLE CSPHandle,
    const CSSM_RESOURCE_CONTROL_CONTEXT *CredAndAclEntry,
    uint32 Flags,
    CSSM_KEY_PTR RecoveredKey,
    CSSM_DATA_PTR OtherInfo)

DESCRIPTION

This function is used to step through the results of a recovery request operation in order to retrieve a single recovered key at a time along with its associated meta information. The cache handle returned from a successful CSSM_KR_RecoveryRetrieve() operation is used. When multiple keys are recovered by a single recovery request operation, the index parameter indicates which item to retrieve through this function.

If the recovered key is a private key it is stored in the specified CSP secured by the passphrase. If the recovered key is a symmetric key it is returned to the caller in the RecoveredKey parameter. The OtherInfo parameter is used to return other meta data associated with the recovered key.

PARAMETERS

KRSPHandle (input)

The handle of the KR module to perform this operation.

CacheHandle (input)

The handle returned from a successful CSSM_KR_RecoveryRequest() operation.

IndexInResults (input)

The index into the results that are referenced by the CacheHandle parameter. The IndexInResults ranges from 0 to (NumberOfRecoveredKeys-1), if NumberOfRecoveredKeys is 1 or larger. NumberOfRecoveredKeys is returned by a successful call to CSSM_KR_RecoveryRetrieve().

CSPHandle (input/optional)

This parameter is used when recovering the private key in a keypair. This identifies the CSP that should store the recovered key.

CredAndAclEntry (input/optional)

A structure containing one or more credentials authorized for creating a key and the prototype ACL entry that will control future use of the newly created key. The credentials and ACL entry prototype can be presented as immediate values, or callback functions can be provided for use by the CSP to acquire the credentials and/or the ACL entry interactively. If the CSP provides public access for creating a key, then the credentials can be NULL. If the CSP defines a default initial ACL entry for the new key, then the ACL entry prototype can be an empty list.

Flags (input)

Flag values relevant for recovery of a key. Possible values are: CERT_RETRIEVE - if the recovered key is a private key, return the corresponding public key certificate in the OtherInfo parameter.

RecoveredKey (output)

This parameter is used when recovering a symmetric key. The recovered key is stored in the key structure provided by the caller.

OtherInfo (output/optional)

Additional meta information can be associated with the recovered key. Any additional information is returned in this output parameter. The object is opaque and the caller must have knowledge of the expected structure of this result.

RETURN VALUES

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

CSSM_INVALID_KR_HANDLE

Invalid KR Handle.

CSSM_KR_INVALID_CSP_HANDLE

Invalid CSP Handle.

CSSM_KR_INVALID_HANDLE

Invalid cache handle.

CSSM_KR_INVALID_INDEX

Cache index value is out of range.

CSSM_KR_PRIVATE_KEY_STORE_FAIL

Unable to store private key in CSP.

CSSM_MEMORY_ERROR

Not enough memory.

SEE ALSO

CSSM_KR_CreateRecoveryRequestContext()
CSSM_KR_RecoveryRequest()
CSSM_KR_RecoveryRetrieve()
CSSM_KR_RecoveryRequestAbort()

NAME

CSSM_KR_RecoveryRequestAbort

SYNOPSIS

CSSM_RETURN CSSMAPI CSSM_KR_RecoveryRequestAbort
    (CSSM_KRSP_HANDLE KRSPHandle,
    CSSM_HANDLE CacheHandle)

DESCRIPTION

This function is invoked after a successful call to the CSSM_KR_RecoveryRetrieve() API, and after all desired keys were recovered using CSSM_KR_GetRecoveredObject(). The function also destroys all intermediate state and secret information used during the key recovery process.

PARAMETERS

KRSPHandle (input)

The handle of the KR module to perform this operation.

CacheHandle (input)

The handle returned from a successful CSSM_KR_RecoveryRetrieve() operation.

RETURN VALUES

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

CSSM_INVALID_KR_HANDLE

Invalid KR handle.

CSSM_KR_INVALID_HANDLE

Invalid cache handle.

SEE ALSO

CSSM_KR_CreateRecoveryRequestContext()
CSSM_KR_RecoveryRequest()
CSSM_KR_RecoveryRetrieve()
CSSM_KR_GetRecoveredObject()

NAME

CSSM_KR_QueryPolicyInfo

SYNOPSIS

CSSM_RETURN CSSMAPI CSSM_KR_QueryPolicyInfo
    (CSSM_ALGORITHMS AlgorithmId,
    CSSM_ENCRYPT_MODE Mode,
    CSSM_CONTEXT_TYPE Class,
CSSM_KR_POLICY_INFO_PTR *PolicyInfoData)

DESCRIPTION

This function queries the law enforcement CSSM policy in effect and returns relevant information for application use. No privilege is required to invoke this function.

The policy information reports the maximum key length that can be generated, per cipher algorithm type and mode, without a need to generate key recovery blocks. It also specifies whether it is the jurisdiction of manufacturing or the jurisdiction of use to enforce the given policy. For special situations where the jurisdiction of use prohibits generation of key recovery fields, that information will also be provided.

Applications can request policy information relative to a specific algorithm, by providing the CSSM algorithm identifier in first parameter to the call. If a CSSM_ALGID_NONE is provided in this field, the PolicyInfoData will contain information pertaining to the entire set of algorithms controlled for the law enforcement jurisdiction. The Mode parameter can be specified exactly, or set to CSSM_ALGMODE_NONE. In the latter case, all matching algorithm ids are returned, regardless of the actual mode. The class parameter should be set to correctly to symmetric or asymmetric, otherwise the results will not be accurate.

If the API can not find a matching entry in the configured policies, the numberOfEntries field in PolicyInfoData is set to 0, and the return code to CSSM_OK.

Applications have the responsibility to free the memory associated with the policy information data when no longer needed, by calling CSSM_KR_FreePolicyInfo().

PARAMETERS

AlgorithmID (input)

CSSM defined algorithm identifier for which policy information is requested. This parameter must be CSSM_ALGID_NONE if global policy information is desired.

Mode (input)

The desired algorithm mode. This parameter can be set to CSSM_ALGMODE_NONE to get all applicable modes.

Class (input)

The class of the desired algorithm. The allowed values are CSSM_ALGCLASS_ASYMMETRIC and CSSM_ALGCLASS_SYMMETRIC.

PolicyInfoData (output)

Pointer to a CSSM policy information data structure to receive the query results.

RETURN VALUES

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

CSSM_INVALID_KR_HANDLE

Invalid KR handle

CSSM_KR_INVALID_

Invalid or unsupported algorithm mode

CSSM_KR_INVALID_CLASS

Invalid or unsupported class of algorithm

CSSM_KR_INVALID_POINTER

Invalid pointer for policyinfo structure

NAME

CSSM_KR_FreePolicyInfo

SYNOPSIS

CSSM_RETURN CSSMAPI CSSM_KR_FreePolicyInfo
    (CSSM_KR_POLICY_INFO_PTR PolicyInfoData)

DESCRIPTION

This function frees the memory allocated in the PolicyInfoData by a successful call to the CSSM_KR_QueryPolicyInfo() API.

PARAMETERS

PolicyInfoData (input)

The pointer to the memory that stores the policy data and was allocated by a successful call to the CSSM_KR_QueryPolicyInfo() API.

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

CSSM_KR_INVALID_POINTER

Invalid input data

SEE

CSSM_KR_QueryPolicyInfo()

Extensibility Functions

NAME

CSSM_KR_PassThrough

SYNOPSIS

CSSM_RETURN CSSMAPI CSSM_KR_PassThrough
    (CSSM_KRSP_HANDLE KRSPHandle,
    CSSM_CC_HANDLE KeyRecoveryContext,
    CSSM_CC_HANDLE CryptoContext,
    uint32 PassThroughId,
    const void *InputParams,
    void **OutputParams)

DESCRIPTION

This function allows applications to call key recovery module-specific operations that have been exported. Such operations may include queries or services specific to the recovery mechanism implemented by the KR module.

PARAMETERS

KRSPHandle (input)

The handle of the KR module to perform this operation.

KeyRecoveryContext (input/optional)

The handle that describes the context for the key recovery operation.

CryptoContext (input/optional)

The handle that describes the context for a cryptographic operation. The cryptographic context specifies the handle of the cryptographic service provider (CSP) that must be used to perform the operation. If no cryptographic context is specified, the KR module uses an assumed context, if required.

PassThroughId (input)

An identifier assigned by the KR module to indicate the exported function to perform.

InputParams (input)

A pointer to the CSSM_DATA structure containing parameters to be interpreted in a function-specific manner by the requested KR module. This parameter can be used as a pointer to an array of CSSM_DATA_PTRs.

OutputParams (output)

A pointer to the CSSM_DATA structure containing the output from the pass-through function. The output data must be interpreted by the calling application based on externally available information.

RETURN VALUES

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

CSSM_INVALID_KR_HANDLE

Invalid KR handle.

CSSM_KR_INVALID_CC_HANDLE

Invalid crypto context handle.

CSSM_KR_INVALID_KRC_HANDLE

Invalid key recovery context handle.

CSSM_KR_INVALID_OP_ID

Invalid operation ID.

CSSM_KR_INVALID_POINTER

Invalid pointer to input data.

CSSM_MEMORY_ERROR

Error in allocating memory.

CSSM_KR_PASS_THROUGH_FAIL

Unable to perform pass through.

CSSM_FUNCTION_NOT_IMPLEMENTED

Function not implemented.