NAME

CSSM_KR_RecoveryRequest

SYNOPSIS

CSSM_RETURN CSSMAPI CSSM_KR_RecoveryRequest
    (CSSM_CC_HANDLE RecoveryRequestContext,
    const CSSM_DATA_PTR KRInData,
    const CSSM_CRYPTO_DATA_PTR UserCallback,
    uint32 *EstimatedTime,
    const CSSM_DATA_PTR ReferenceHandle)

DESCRIPTION

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.

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.

UserCallback (input/optional)

A callback function that may be used to collect further information from the user interface.

EstimatedTime (output)

The estimated time after which the caller should invoke the CSSM_KR_RecoveryRetrieve function to obtain a cache of recovered keys.

ReferenceHandle (output)

Handle representing this outstanding recovery request. This handle should be used at input to the CSSM_KR_RecoveryRetrieve function.

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