NAME

CL_CertRecoveryRequest

SYNOPSIS

CSSM_RETURN CSSMCLI CL_CertRecoveryRequest
    (CSSM_CL_HANDLE CLHandle,
    const CSSM_DATA_PTR CACert,
    const CSSM_NET_ADDRESS_PTR CALocation,
    const CSSM_USER_AUTHENTICATION_PTR UserAuthentication,
    const CSSM_FIELD_PTR SelectedCertFieldValues,
    const uint32 NumberOfFieldValues,
    uint32 *EstimatedTime,
    const CSSM_DATA_PTR ReferenceIdentifier)

DESCRIPTION

This function submits a certificate recovery request to a Certificate Authority (CA) process (or other trusted backup facility) to prepare for the recovery of a set of certificates and their associated private keys. The CA process is identified by the CA certificate, available to applications via a query to the CSSM registry. The caller can specify one or more certificate field values to limit the set of certificates selected for potential recovery. The recovery facility process may be local or remote. The CL module incorporates knowledge of the name, location, and interface protocol for communicating with the CA.

The caller is required to provide authentication information so the CA process can determine whether the caller is authorized to recover a certificate. The specific format of the credential is specified by the CL module. The caller can query the CL Module Info structure to obtain this information. Additional authentication information may also be required. It can be provided in the substructure field named MoreAuthenticationData.

This function returns a ReferenceIdentifier and an EstimatedTime (specified in seconds). The estimate time defines the expected certificate recovery time. This time may be substantial when many certificates are being recovered or manual procedures are required. In contrast, the estimated time can be zero, meaning the set of recovered certificates can be obtained immediately. After the specified time has elapsed, the caller must use the CL module interface CSSM_CL_CertRecoveryRetrieve, with the reference identifier, to obtain the set of recovered certificates from the CA process.

PARAMETERS

CLHandle (input)

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

CACert (input/optional)

A pointer to the CSSM_DATA structure containing the certificate of the issuer of the certificate to be recovered. This certificate identifies the CA to be contacted for certificate recovery. If the CACert is NULL, the CL module can attempt certificate recovery from a default CA process.

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 the SignerCert input parameter or can assume a default CA process location. If SignerCert is not specified and a default cannot be assumed, the request cannot be initiated 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.

SelectedCertFieldValues (input/optional)

An array of one or more field values that must be matched as part of the process of selecting certificates for recovery. If no certificate field values are specified, then the all of the caller's certificates (known to this CL module) will be selected for possible recovery.

NumberOfFieldValues (input)

The number of selected certificate field values listed in the array SelectedCertFieldValues. If no certificate field values are specified, then this value must be zero.

EstimatedTime (output)

The number of seconds estimated before the set of recovered certificates will be ready to be retrieved. A (default) value of zero indicates that the recovered certificates can be retrieved immediately via the corresponding CL_CertRecoveryRetrieve function 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.

ReferenceIdentifier (output)

A reference identifier which uniquely identifies this specific request. The handle must be used in all subsequent calls to retrieve the set of recovered certificates. The identifier persists across application executions until it is terminated by successful or failed completion of the CSSM_CL_CertRecoveryRetrieve function.

RETURN VALUE

A CSSM_OK return value signifies the requested operation has proceeded and that CL_CertRecoveryRetrieve should be called (after the specified amount of time) in order to retrieve the results. If CSSM_FAIL is returned, an error has occurred. Use CSSM_GetError to obtain the error code.

ERRORS

CSSM_CL_INVALID_CL_HANDLE

Invalid Certificate Library Handle.

CSSM_CL_INVALID_CSP_HANDLE

Invalid CSP Handle.

CSSM_CL_INVALID_DATA_POINTER

Invalid pointer input.

CSSM_AUTHENTICATION_FAIL

Invalid/unauthorized credential.

CSSM_CL_MEMORY_ERROR

Not enough memory.

CSSM_CL_CERT_REQUEST_FAIL

Unable to submit certificate recovery request.

SEE ALSO

CL_CertRecoveryRetrieve, CL_CertRecover,
CL_CertRecoverKey, CL_CertAbortRecovery