Key Recovery Interfaces

Summary of Interface Calls

Module Management Operations

• CSSM_ModuleLoad()

• CSSM_ModuleUnload()

• CSSM_ModuleAttach()

• CSSM_ModuleDetach()

Key Recovery Module Management Operations

CSSM_KR_SetEnterpriseRecoveryPolicy()

This call establishes the identity of the file that contains the enterprise key recovery policy function.

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

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

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

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

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

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

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

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

KRSP_GetRecoveredObject()

Retrieves a single recovered key and its associated meta information.

CSSM_KR_RecoveryRequestAbort()

KRSP_RecoveryRequestAbort()

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

Privileged Context Function

KRSP_PassPrivFunc()

Returns a private CSSM callback function that the service provider can use to exempt itself from recursive screening by its own key recovery policy.

Extensibility Function

CSSM_KR_PassThrough()

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

Example Application Using Key Recovery APIs

• 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;

Definitions

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;

Definitions

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

 

typedef uint32 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;

Definitions

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.

Generic Module Management Operations

The applicable generic management functions include:

• CSSM_ModuleLoad()

• CSSM_ModuleUnload()

• CSSM_ModuleAttach()

• CSSM_ModuleDetach()

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 KR SPI 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 KR SPI 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 KR SPI 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 KR SPI 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 CSSMAPI 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, for the CSSM API
KRSP_RegistrationRequest, for the KR SPI

SYNOPSIS

API:
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)

SPI:
CSSM_RETURN CSSMKRI KRSP_RegistrationRequest
    (CSSM_KRSP_HANDLE KRSPHandle,
    CSSM_CC_HANDLE KRRegistrationContextHandle,
    const CSSM_CONTEXT *KRRegistrationContext,
    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 may be supplied to allow the registration operation to interact with the user interface, if necessary.

When this operation is successful, a ReferenceHandle and an EstimatedTime parameter are returned. The ReferenceHandle is used to invoke the associated CSSM_KR_RegistrationRetrieve() (for the API) or KRSP_RegistrationRetrieve() (for the SPI) function, after the EstimatedTime in seconds.

API 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 CSSM_KR_RegistrationRetrieve() function.

SPI PARAMETERS

KRSPHandle (input)

The handle that describes the add-in key recovery service provider module used to perform up calls to CSSM for the memory functions managed by CSSM.

KRRegistrationContextHandle (input)

The handle that describes the context of this key recovery operation used to link to the KRSP-managed information.

KRRegistrationContext (input)

Pointer to CSSM_CONTEXT structure that describes the attributes with this key recovery context.

KRInData (input)

As for the API.

AccessCredentials (input/optional)

As for the API.

KRFlags (input)

As for the API.

EstimatedTime (output)

The estimated time after which the CSSM_KR_RegistrationRetrieve call should be invoked to obtain registration results. 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)

As for the API, except use the KRSP_RegistrationRetrieve() function to retrieve the registration 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_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()
KRSP_RecoveryRetrieve()

NAME

CSSM_KR_RegistrationRetrieve, for the CSSM API
KRSP_RegistrationRetrieve, for the KR SPI

SYNOPSIS

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

SPI:
CSSM_RETURN CSSMKRI KRSP_RegistrationRetrieve
    (CSSM_KRSP_HANDLE KRSPHandle,
    CSSM_HANDLE ReferenceHandle,
    const CSSM_ACCESS_CREDENTIALS *AccessCredential,
    sint32 *EstimatedTime,
    CSSM_KR_PROFILE_PTR *KRProfile)

DESCRIPTION

This function completes a key recovery registration operation. The results of a successful registration operation are returned through the KRProfile parameter, which may be used with the profile management API functions.

It is possible that the key recovery registration process has not yet completed, in which case the returned EstimatedTime is the updated estimate for completion of the registration procedure.

If the results are not available when this function is invoked, the KRProfile parameter is set to NULL, and the EstimatedTime parameter indicates when this operation should be repeated (in the case of the SPI, using the same ReferenceHandle).

API PARAMETERS

KRSPHandle (input)

The handle that describes the add-in key recovery service provider module used to perform up calls to CSSM for the memory functions managed by CSSM.

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.

SPI PARAMETERS

All as for the API, plus as follows:

ReferenceHandle (input)

Indicates which outstanding recovery request is to be completed.

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

Key Recovery Enablement Operations

NAME

CSSM_KR_GenerateRecoveryFields, for the CSSM API
KRSP_GenerateRecoveryFields, for the KR SPI

SYNOPSIS

API:
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)

SPI:
CSSM_RETURN CSSMKRI KRSP_GenerateRecoveryFields
    (CSSM_KRSP_HANDLE KRSPHandle,
    CSSM_CC_HANDLE KREnablementContextHandle,
    const CSSM_CONTEXT *KREnablementContext,
    CSSM_CC_HANDLE CryptoContextHandle,
    const CSSM_CONTEXT *CryptoContext,
    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, and the cryptographic context containing the key that is to be made recoverable. The session attribute and the flags are interpreted by the KRSP. A set of key recovery fields (KRFields) is returned if the function is successful. The KRFlags parameter may be used to fine tune the contents of the KRFields produced by this operation.

API 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 the individual key recovery fields should be generated.

• KR_ENT-signifies that the enterprise key recovery fields should be generated.

• KR_LE_MAN-signifies that the law enforcement key recovery fields pertaining to the manufacturing jurisdiction should be generated.

• KR_LE_USE-signifies that the law enforcement key recovery fields pertaining to the jurisdiction of use should 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.

SPI PARAMETERS

KRSPHandle (input)

The handle that describes the add-in key recovery service provider module used to perform up calls to CSSM for the memory functions managed by CSSM.

KREnablementContextHandle (input)

The handle that describes the context of this key recovery operation used to link to the KRSP-managed information.

KREnablementContext (input)

Pointer to CSSM_CONTEXT structure that describes the attributes with this key recovery context.

CryptoContextHandle (input)

The handle that describes the cryptographic context used to link to the CSP-managed information.

CryptoContext (input)

Pointer to CSSM_CONTEXT structure that describes the attributes of the cryptographic context.

KRSPOptions (input)

The key recovery service provider specific options. These options are uninterpreted by the SKMF, but passed on to the KRSP.

KRFlags (input)

As for the API.

KRFields (output)

As for the API.

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

NAME

CSSM_KR_ProcessRecoveryFields, for the CSSM API
KRSP_ProcessRecoveryFields, for the KR SPI

SYNOPSIS

API:
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)

SPI:
CSSM_RETURN CSSMKRI KRSP_ProcessRecoveryFields
    (CSSM_KRSP_HANDLE KRSPHandle,
    CSSM_CC_HANDLE KREnablementContextHandle,
    const CSSM_CONTEXT *KREnablementContext,
    CSSM_CC_HANDLE CryptoContextHandle,
    const CSSM_CONTEXT *CryptoContext,
    CSSM_DATA_PTR KRSPOptions,
    CSSM_KR_POLICY_FLAGS KRFlags,
    CSSM_DATA_PTR KRFields)

API DESCRIPTION

This call processes 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.

SPI DESCRIPTION

This call processed a set of key recovery fields given the key recovery context, and the cryptographic context for the encryption operation, and returns a non-NULL cryptographic context handle if the processing was successful. The returned handle may be used for the decrypt API calls of the CSSM.

API 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, in the form of a data blob.

SPI PARAMETERS

KRSPHandle (input)

The handle that describes the add-in key recovery service provider module used to perform up calls to CSSM for the memory functions managed by CSSM.

KREnablementContextHandle (input)

The handle that describes the context of this key recovery operation used to link to the KRSP-managed information.

KREnablementContext (input)

Pointer to CSSM_CONTEXT structure that describes the attributes with this key recovery context.

CryptoContextHandle (input)

The handle that describes the cryptographic context used to link to the CSP-managed information.

CryptoContext (input)

Pointer to CSSM_CONTEXT structure that describes the attributes of the cryptographic context.

KRSPOptions (input)

The key recovery service provider specific options. These options are uninterpreted by the SKMF, but passed on to the KRSP.

KRFlags (input)

As for the API.

KRFields (input)

As for the API

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

Key Recovery Request Operations

NAME

CSSM_KR_RecoveryRequest, for the CSSM API
KRSP_RecoveryRequest, for the KR SPI

SYNOPSIS

API:
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)

SPI:
CSSM_RETURN CSSMKRI KRSP_RecoveryRequest
    (CSSM_KRSP_HANDLE KRSPHandle,
    CSSM_CC_HANDLE KRRequestContextHandle,
    const CSSM_CONTEXT *KRRequestContext,
    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 RequestContext 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 associated CSSM_KR_ or KRSP_ 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 calling the retrieve function.

API 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 associated 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 as input to the CSSM_KR_RecoveryRetrieve() function.

SPI PARAMETERS

KRSPHandle (input)

The handle that describes the add-in key recovery service provider module used to perform upcalls to CSSM for the memory functions managed by CSSM.

KRRequestContextHandle (input)

The handle that describes the context of this key recovery operation used to link to the KRSP-managed information.

KRRequestContext (input)

Pointer to CSSM_CONTEXT structure that describes the attributes with this key recovery context.

KRInData (input)

As for the API

AccessCredentials (input/optional)

As for the API.

EstimatedTime (output)

As for the API except that the relevant follow-up call is KRSP_RecoveryRetrieve().

ReferenceHandle (output)

As for the API except this handle may be used to invoke the KRSP_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()
KRSP_RecoveryRetrieve()

NAME

CSSM_KR_RecoveryRetrieve, for the CSSM API
KRSP_RecoveryRetrieve, for the KR SPI

SYNOPSIS

API:
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)

SPI:
CSSM_RETURN CSSMKRI KRSP_RecoveryRetrieve
    (CSSM_KRSP_HANDLE KRSPHandle,
    const CSSM_ACCESS_CREDENTIALS *AccessCredentials,
    sint32 *EstimatedTime,
    CSSM_HANDLE_PTR CacheHandle,
    uint32 *NumberOfResults)

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 CacheHandle parameter, which may be used with the associated CSSM_KR_ or KRSP_ 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.

API PARAMETERS

KRSPHandle (input)

The handle of the KR module for 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 associated CSSM_KR_GetRecoveredObject() (API) or KRSP_GetRecoveredObject() (SPI) function to complete the recovery of an individual key.

NumberOfRecoveredKeys (output)

The number of recovered key objects in the cache.

SPI PARAMETERS

As for the API, except that there is no ReferenceHandle parameter.

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

KRSP_CreateRecoveryRequestContext()
KRSP_RecoveryRequest()
KRSP_GetRecoveredObject()
KRSP_RecoveryRequestAbort()

NAME

CSSM_KR_GetRecoveredObject, for the CSMM API
KRSP_GetRecoveredObject, for the KR SPI

SYNOPSIS

API:
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)

SPI:
CSSM_RETURN CSSMKRI KRSP_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() (for the CSSM API) or KRSP_RecoveryRetrieve() (for the KR SPI) 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.

The RecoveredKey parameter serves as an input template for the key to be returned. If a private key is to be returned by this operation, the PassPhrase parameter is used to inject the private key into the CSP indicated by the RecoveredKey template; the corresponding public key is returned in the RecoveredKey parameter. Subsequently, the PassPhrase and the public key may be used to reference the private key when operations using the private key are required.

The OtherInfo parameter may be 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() (for the CSSM API) or KRSP_RecoveryRequest() (for the KR SPI) 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 the associated CSSM_KR_ or KRSP_ 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. It may be set to NULL if the key is to be returned in raw form to the caller.

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 value is 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)

This parameter is used if there is additional information associated with the recovered key (such as the public key certificate when recovering a private key) that is to be returned. 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()

KRSP_CreateRecoveryRequestContext()
KRSP_RecoveryRequest()
KRSP_RecoveryRetrieve()
KRSP_RecoveryRequestAbort()

NAME

CSSM_KR_RecoveryRequestAbort, for the CSSM API
KRSP_RecoveryRequestAbort, for the KR SPI

SYNOPSIS

API:
CSSM_RETURN CSSMAPI CSSM_KR_RecoveryRequestAbort
    (CSSM_KRSP_HANDLE KRSPHandle,
    CSSM_HANDLE CacheHandle)

SPI:
CSSM_RETURN CSSMKRI KRSP_RecoveryRequestAbort
    (CSSM_KRSP_HANDLE KRSPHandle,
    CSSM_HANDLE ResultsHandle)

DESCRIPTION

This function is invoked after a successful call to the associated CSSM_KR_RecoveryRetrieve() (for the CSSM API) or KRSP_RecoveryRetrieve() (for the KR SPI) function, and after all desired keys were recovered using the associated CSMM_KR_ or KRSP_ GetRecoveredObject() function. 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() (for the CSSM API) or KRSP_RecoveryRetrieve() (for the KR SPI) 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()

KRSP_CreateRecoveryRequestContext()
KRSP_RecoveryRequest()
KRSP_RecoveryRetrieve()
KRSP_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_KR_INVALID_HANDLE

Invalid KR handle

CSSM_KR_INVALID_MODE

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

Privileged Context Operation

NAME

KRSP_PassPrivFunc

SYNOPSIS

CSSM_RETURN CSSMKRI KRSP_PassPrivFunc
    (CSSM_PRIV_FUNC_PTR CSSM_SetContextPriv)

DESCRIPTION

This function is used to provide the KR SPI with the CSSM_SetContextPriv() callback function. This callback is implemented by the CSSM and allows the setting or dropping of the privilege state flag for a given cryptographic context. This is used by the KR SPI to make a cryptographic context privileged with respect to key recovery policy enforcement decisions, so that the KR SPI itself is allowed to bypass the key recovery policy controls. The KR SPI is expected to reset the privilege state flag as soon as the need for the privilege is over.

PARAMETERS

CSSM_SetContextPriv (input)

The callback that is used by the KR SPI to set or drop the privilege state flag for a given cryptographic context.

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_MEMORY_ERROR

Not enough memory.

Extensibility Function

NAME

CSSM_KR_PassThrough, for the CSSM API br KRSP_PassThrough, for the KR SPI

SYNOPSIS

API:
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)

SPI:
CSSM_RETURN CSSMKRI KRSP_PassThrough
    (CSSM_KRSP_HANDLE KRSPHandle,
    CSSM_CC_HANDLE KeyRecoveryContextHandle,
    const CSSM_CONTEXT *KeyRecoveryContext,
    CSSM_CC_HANDLE CryptoContextHandle,
    const CSSM_CONTEXT *CryptoContext,
    uint32 PassThroughId,
    const void *InputParams,
    void **OutputParams)

DESCRIPTION

The KRSP_PassThrough() function is provided to allow KR SPI developers to extend the key recovery functionality of the CSSM API. Because it is only exposed to CSSM as a function pointer, its name internal to the KR SPI can be assigned at the discretion of the KR SPI module developer. However, its parameter list and return value must match what is shown below.

For the CSSM API, 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.

The error codes given in this definition constitute the generic error codes which may be used by all KR SPIs to describe common error conditions. KR SPI developers may also define their own module-specific error codes, as described in Part 9 - CSSM Add-in Module Structure and Administration Specification .

API 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 specifying the exported/custom function to perform.

InputParams (input)

A pointer to the 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 data pointers.

OutputParams (output)

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

SPI PARAMETERS

KRHandle (input)

As for the API.

KeyRecoveryContextHandle (input/optional)

The handle that describes the add-in key recovery service provider module used to perform upcalls to CSSM for the memory functions managed by CSSM.

KeyRecoveryContext (input/optional)

As for the API.

CryptoContextHandle (Input/optional)

The handle that describes the cryptographic context used to link to the CSP-managed information.

CryptoContext (input/optional)

As for the API.

PassThroughId (input)

As for the API.

InputParams (input)

As for the API.

OutputParams (output)

As for the API. The KR SPI will allocate the memory for this structure, and the application should free the memory for the structure.

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.