NAME

KRSP_GetRecoveredObject

SYNOPSIS

CSSM_RETURN CSSMKRSPI KRSP_GetRecoveredObject
    (CSSM_KRSP_HANDLE KRSPHandle,
    CSSM_HANDLE CacheHandle,
    uint32 IndexInResults,
    CSSM_CSP_HANDLE CSPHandle,
    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 KRSP_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.

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 that describes the add-in key recovery service provider module used to perform up calls to CSSM for the memory functions managed by CSSM.

CacheHandle (input)

The handle returned from a successful CSSM_KR_RecoveryRequest operation.

IndexInResults (input)

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

CSPHandle (input/optional )

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.

PassPhrase (input)

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.

RecoveredKey (output)

This parameter returns the recovered key.

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)

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 is to be returned.

RETURN VALUE

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.