To understand the role of key recovery in encrypted data
communication, consider the following scenario, illustrated in
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
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.
typedef uint32 CSSM_KRSP_HANDLE; /* Key Recovery Service
Provider Handle */
typedef struct cssm_kr_name {
uint8 Type; /* namespace type */
uint8 Length; /* name string length */
char *Name; /* name string */
} CSSM_KR_NAME;
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;
/* 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),
-
-
#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)
-
-
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;
-
-
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;
KR service modules store information in two MDS relations:
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
CSSM_KR_SetEnterpriseRecoveryPolicy
CSSM_RETURN CSSMAPI CSSM_KR_SetEnterpriseRecoveryPolicy (const CSSM_DATA *RecoveryPolicyFileName, const CSSM_CRYPTO_DATA *OldPassPhrase, const CSSM_CRYPTO_DATA *NewPassPhrase)
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.
- 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.
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.
- 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.
CSSM_KR_CreateRecoveryRegistrationContext
CSSM_RETURN CSSMAPI CSSM_KR_CreateRecoveryRegistrationContext (CSSM_KRSP_HANDLE KRSPHandle, CSSM_CC_HANDLE *NewContext)
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.
- 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.
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.
- CSSM_INVALID_KR_HANDLE
Invalid handle.
- CSSM_MEMORY_ERROR
Memory error.
CSSM_KR_RegistrationRequest()
CSSM_KR_CreateRecoveryEnablementContext
CSSM_RETURN CSSMAPI CSSM_KR_CreateRecoveryEnablementContext (CSSM_KRSP_HANDLE KRSPHandle, const CSSM_KR_PROFILE *LocalProfile, const CSSM_KR_PROFILE *RemoteProfile, CSSM_CC_HANDLE *NewContext)
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.
- 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.
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.
- CSSM_INVALID_KR_HANDLE
Invalid handle.
- CSSM_KR_INVALID_PROFILE
Invalid profile structure.
- CSSM_KR_INVALID_PTR
Bad pointer.
- CSSM_MEMORY_ERROR
Memory error.
CSSM_KR_GenerateRecoveryFields()
CSSM_KR_ProcessRecoveryFields()
CSSM_KR_CreateRecoveryRequestContext
CSSM_RETURN CSSMAPI CSSM_KR_CreateRecoveryRequestContext (CSSM_KRSP_HANDLE KRSPHandle, const CSSM_KR_PROFILE *LocalProfile, CSSM_CC_HANDLE *NewContext)
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.
- 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.
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.
- CSSM_INVALID_KR_HANDLE
Invalid handle.
- CSSM_KR_INVALID_PROFILE
Invalid profile.
- CSSM_MEMORY_ERROR
Memory error.
CSSM_KR_RecoveryRequest()
CSSM_KR_RecoveryRetrieve()
CSSM_KR_GetPolicyInfo
CSSM_RETURN CSSM_KR_GetPolicyInfo (CSSM_CC_HANDLE CCHandle, CSSM_KR_POLICY_FLAGS *EncryptionProhibited, uint32 *WorkFactor)
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.
- 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.
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.
- CSSM_KR_INVALID_CC_HANDLE
Invalid crypto context handle.
- CSSM_MEMORY_ERROR
Memory error.
CSSM_KR_RegistrationRequest
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)
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.
- 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.
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.
- CSSM_KR_INVALID_HANDLE
Invalid registration handle.
- CSSM_KR_INVALID_POINTER
Invalid pointer.
- CSSM_MEMORY_ERROR
Memory error.
CSSM_KR_CreateRecoveryRegistrationContext()
CSSM_KR_RecoveryRetrieve()
CSSM_KR_RegistrationRetrieve
CSSM_RETURN CSSMAPI CSSM_KR_RegistrationRetrieve (CSSM_KRSP_HANDLE KRSPHandle, const CSSM_ACCESS_CREDENTIALS *AccessCredentials, sint32 *EstimatedTime, CSSM_KR_PROFILE_PTR *KRProfile)
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.
- 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.
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.
- CSSM_KR_INVALID_HANDLE
Invalid reference handle.
- CSSM_MEMORY_ERROR
Memory error.
CSSM_KR_CreateRecoveryRegistrationContext()
CSSM_KR_RecoveryRequest()
CSSM_KR_GenerateRecoveryFields
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)
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.
- 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.
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.
- 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.
CSSM_KR_CreateRecoveryEnablementContext()
CSSM_KR_ProcessRecoveryFields()
CSSM_KR_ProcessRecoveryFields
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)
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.
- 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.
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.
- 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.
CSSM_KR_CreateRecoveryEnablementContext()
CSSM_KR_GenerateRecoveryFields()
CSSM_KR_RecoveryRequest
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)
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.
- 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 theCSSM_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 theCSSM_KR_RecoveryRetrieve() function.
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.
- 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.
CSSM_KR_CreateRecoveryRequestContext()
CSSM_KR_RecoveryRetrieve()
CSSM_KR_RecoveryRetrieve
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)
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 theCSSM_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.
- 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 theCSSM_KR_GetRecoveredObject() function to complete the recovery of an individual key.
- NumberOfRecoveredKeys (output)
The number of keys in the cache.
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.
- CSSM_INVALID_KR_HANDLE
Invalid KR handle.
- CSSM_KR_INVALID_HANDLE
Invalid reference handle.
- CSSM_MEMORY_ERROR
Memory error.
- CSSM_KR_FAIL
Function failed.
CSSM_KR_CreateRecoveryRequestContext()
CSSM_KR_RecoveryRequest()
CSSM_KR_GetRecoveredObject()
CSSM_KR_RecoveryRequestAbort()
CSSM_KR_GetRecoveredObject
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)
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 successfulCSSM_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.
- KRSPHandle (input)
The handle of the KR module to perform this operation.
- CacheHandle (input)
The handle returned from a successfulCSSM_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 toCSSM_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.
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.
- 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.
CSSM_KR_CreateRecoveryRequestContext()
CSSM_KR_RecoveryRequest()
CSSM_KR_RecoveryRetrieve()
CSSM_KR_RecoveryRequestAbort()
CSSM_KR_RecoveryRequestAbort
CSSM_RETURN CSSMAPI CSSM_KR_RecoveryRequestAbort (CSSM_KRSP_HANDLE KRSPHandle, CSSM_HANDLE CacheHandle)
This function is invoked after a successful call to theCSSM_KR_RecoveryRetrieve() API, and after all desired keys were recovered usingCSSM_KR_GetRecoveredObject() . The function also destroys all intermediate state and secret information used during the key recovery process.
- KRSPHandle (input)
The handle of the KR module to perform this operation.
- CacheHandle (input)
The handle returned from a successfulCSSM_KR_RecoveryRetrieve() operation.
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.
- CSSM_INVALID_KR_HANDLE
Invalid KR handle.
- CSSM_KR_INVALID_HANDLE
Invalid cache handle.
CSSM_KR_CreateRecoveryRequestContext()
CSSM_KR_RecoveryRequest()
CSSM_KR_RecoveryRetrieve()
CSSM_KR_GetRecoveredObject()
CSSM_KR_QueryPolicyInfo
CSSM_RETURN CSSMAPI CSSM_KR_QueryPolicyInfo (CSSM_ALGORITHMS AlgorithmId, CSSM_ENCRYPT_MODE Mode, CSSM_CONTEXT_TYPE Class, CSSM_KR_POLICY_INFO_PTR *PolicyInfoData)
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() .
- 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.
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.
- 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
CSSM_KR_FreePolicyInfo
CSSM_RETURN CSSMAPI CSSM_KR_FreePolicyInfo (CSSM_KR_POLICY_INFO_PTR PolicyInfoData)
This function frees the memory allocated in the PolicyInfoData by a successful call to theCSSM_KR_QueryPolicyInfo() API.
- PolicyInfoData (input)
The pointer to the memory that stores the policy data and was allocated by a successful call to theCSSM_KR_QueryPolicyInfo() API.
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.
- CSSM_KR_INVALID_POINTER
Invalid input data
CSSM_KR_QueryPolicyInfo()
CSSM_KR_PassThrough
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)
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.
- 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.
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.
- 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.
Contents | Next section | Index |