NAME

CSSM_CL_CertKeyRecover

SYNOPSIS

CSSM_RETURN CSSMAPI CSSM_CL_CertKeyRecover
    (CSSM_CL_HANDLE CLHandle,
    CSSM_HANDLE CacheHandle,
    const uint32 CacheIndex,
    CSSM_CSP_HANDLE CSPHandle,
    const CSSM_CRYPTO_DATA_PTR PassPhrase)

DESCRIPTION

This function recovers the private key associated with a certificate and securely stores that key in the specified cryptographic service provider. The key (and its associated certificate) are among a set of certificates and private keys contained in the cache specified by the CacheHandle.

Cache entries are in unspecified order. The private key to be retrieved is specified by the CacheIndex parameter, which is a simple counter from one to the number of certificates in the cache.

The recovery process associates the private key with the public key contained in the certificate, securely stores the private key in the specified cryptographic service provider, and associates the new PassPhrase with the recovered, stored, private key.

To selectively recover private keys from the cache, the function CSSM_CL_CertRecover can be used to review recovered certificates and determine the appropriate CacheIndex to use when recovering the associated private key.

PARAMETERS

CLHandle (input)

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

CacheHandle (input)

A reference handle which uniquely identifies the cache of retrieved, recovered certificates and their associated private keys.

CacheIndex (input)

An index value that selects a certificate from the cache of retrieved, recovered certificates and associated keys. The value must be less than or equal to the number of certificates in the cache.

CSPHandle (input)

The handle that describes the add-in CSP module where the private key is to be stored. Optionally, the CL module can use this CSP to perform additional cryptographic operations or may use another default CSP for that purpose.

PassPhrase (input)

A pointer to the CSSM_CRYPTO_DATA structure containing the new passphrase to be associated with the recovered certificate and private key. The passphrase can be specified by immediate data in this parameter or a callback function to request a passphrase from the caller's process.

RETURN VALUE

CSSM_OK if the function was successful. CSSM_FAIL if an error condition 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_HANDLE

Invalid cache handle.

CSSM_CL_INVALID_INDEX

Cache index value is out of range.

CSSM_CL_PRIVATE_KEY_STORE_FAIL

Unable to store private key in CSP.

CSSM_CL_MEMORY_ERROR

Not enough memory.

SEE ALSO

CL_CertRecoveryRequest, CSSM_CL_CertRecoveryRetrieve,
CSSM_CL_CertRecover, CSSM_CL_CertAbortRecovery