NAME

CL_CertRecoveryRetrieve

SYNOPSIS

CSSM_RETURN CSSMCLI CL_CertRecoveryRetrieve
    (CSSM_CL_HANDLE CLHandle,
    const CSSM_DATA_PTR ReferenceIdentifier,
    const CSSM_NET_ADDRESS_PTR CALocation,
    const CSSM_USER_AUTHENTICATION_PTR UserAuthentication,
    CSSM_HANDLE CacheHandle,
    uint32 *NumberOfRetrievedCerts,
    sint32 *EstimatedTime)

DESCRIPTION

This function returns the set of certificates recovered in response to the CL_CertRecoveryRequest function call. The reference identifier denotes the corresponding CertRecoveryRequest call.

The caller may be required to provide additional authentication information to recover the certificates. The format of these credentials is defined by the CL module and recorded in the CLSubservice structure, which can be queried by the caller.

This function obtains the set of recovered certificates and their associated private keys. It returns a cache handle to reference the returned set. The cache handle is used when retrieving individual certificates and keys using the CSSM_CL_CertRecover function.

It is possible that the recovered certificates are not ready to be retrieved when CSSM_CL_CertRecoveryRetrieve is called. In that case, an EstimatedTime to complete certificate recovery is returned with a NULL cache handle. The caller reuses the reference identifier to retrieve the recovered certificates after the estimated time to completion has elapsed.

PARAMETERS

CLHandle (input)

The handle that describes the add-in certificate library module used to perform this function.

ReferenceIdentifier (input)

A reference identifier which uniquely identifies the CSSM_CL_CertRecoveryRequest call that initiated recovery of the set of certificates obtained by this function. The identifier persists across application executions until it is terminated by successful or failed completion of the CSSM_CL_CertRecoveryRetrieve function.

CALocation (input/optional)

A pointer to a network address directly or indirectly identifying the location of the CA process. If the input is NULL, the module can determine a CA process and its location based on state information associated with the ReferenceIdentifier or can assume a default CA process location. If insufficient state is associated with the ReferenceIdentifier and a default cannot be assumed, the retrieval cannot be completed and the operation fails.

UserAuthentication (input/optional)

A pointer to the CSSM_USER_AUTHENTICATION structure containing the authentication information to be used in association with this request. The authentication information may be a pass-phrase, a PIN, a completed registration form, a Certificate to facilitate a signing operation, and so on, depending on the context of the request. The required format for this credential is defined by the CL and recorded in the CLSubservice structure describing this module. If the supplied information is insufficient, additional information can be provided by the substructure field MoreAuthenticationData. This field contains an immediate data value or a callback function to collect additional information from the user. If authentication information is not required, this parameter must be NULL.

CacheHandle (output)

A reference handle which uniquely identifies the cache of recovered certificates and their associated private keys. If the certificate retrieval process has not been completed, the returned cache handle is zero. A non-zero cache handle can be used in the CSSM_CL_CertRecover function to complete the recovery of an individual certificate and its private key. The handle is not persistent. It used is terminated by calling CSSM_CL_CertAbortRecovery or by termination of the caller process.

NumberOfRetrievedCerts (output)

The number of certificates in the cache.

EstimatedTime (output)

The number of seconds estimated before the set of recovered certificates will be returned. A (default) value of zero indicates that the set has been returned as a result of this call. When the recovery process cannot estimate the time required to prepare the recovered certificates, the output value for estimated time is CSSM_ESTIMATED_TIME_UNKNOWN.

RETURN VALUE

A CSSM_RETURN value indicating whether the operation obtained a set of recovered certificates. If the result is CSSM_FAIL, and a NULL cache handle and a positive EstimatedTime are returned, then the calling application is expected to call this function again after the specified EstimatedTime. If the result is CSSM_FAIL and EstimatedTime is zero, an error has occurred. If the EstimatedTime is CSSM_ESTIMATED_TIME_UNKNOWN, the call back time is not defined and the application must periodically poll for completion. Use CSSM_GetError to obtain the error code.

ERRORS

CSSM_CL_INVALID_CL_HANDLE

Invalid Certificate Library Handle.

CSSM_CL_INVALID_IDENTIFIER

Invalid reference identifier.

CSSM_AUTHENTICATION_FAIL

Invalid/unauthorized credential for operation.

CSSM_CL_MEMORY_ERROR

Not enough memory.

SEE ALSO

CL_CertRecoveryRequest, CL_CertRecover,
CL_CertRecoverKey, CL_CertAbortRecovery