NAME

CSSM_KR_GetRecoveredObject

SYNOPSIS

CSSM_RETURN CSSMAPI CSSM_KR_GetRecoveredObject
    (CSSM_KR_HANDLE KRSPHandle,
    CSSM_HANDLE CacheHandle,
    uint32 IndexInResults,
    CSSM_CSP_HANDLE CSPHandle,
    const CSSM_CRYPTO_DATA_PTR Passphrase,
    CSSM_KEY_PTR RecoveredKey,
    Uint32 Flags,
    CSSM_DATA_PTR OtherInfo)

DESCRIPTION

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

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

PARAMETERS

KRSPHandle (input)

The handle of the KR module to perform this operation.

CacheHandle (input)

The handle returned from a successful CSSM_KR_RecoveryRequest operation.

IndexInResults (input)

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

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.

Passphrase (input/optional)

This parameter is used when recovering the private key in a keypair. The passphrase is associated with the private key when it is securely stored in the specified CSP.

RecoveredKey (output)

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

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.

OtherInfo (output/optional)

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

RETURN VALUES

A CSSM return value. This function returns CSSM_OK if successful and returns an error code if an error has occurred.

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.