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

CSSM_RETURN CSSMAPI CSSM_KR_GetRecoveredObject
               (CSSM_KRSP_HANDLE KRSPHandle,
               CSSM_HANDLE_PTR CacheHandle,
               unit32 IndexInResults,
               CSSM_CSP_HANDLE CSPHandle,
               const CSSM_CRYPTO_DATA_PTR PassPhrase,
               CSSM_KEY_PTR RecoveredKey,
               unit32 Flags,
               CSSM_DATA_PTR OtherInfo )

Input

KRSPHandle

The handle to the KRSP that is to be used.

CacheHandle

Pointer to the handle returned from a successful CSSM_KR_RecoveryRequest operation.

IndexInResults

The index into the results that are referenced by the ResultsHandle parameter.

PassPhrase

This parameter is only relevant if the recovered key is a private key. It is used to protect the private key when it is inserted into the CSP specified by the RecoveredKey template.

Flags

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.

Output

RecoveredKey

This parameter returns the recovered key.

OtherInfo

This parameter is used if there are additional information associated with the recovered key (such as the public key certificate when recovering a private key) that will be returned.

Input/optional

CSPHandle

This parameter identifies the CSP that the recovered key should be injected into. It may be set to NULL if the key is to be returned in raw form to the caller.

CSSM_OK if successful, CSSM_FAIL if an error occurred. Use CSSM_GetError to determine the exact error.