NAME
   TP_CertReclaimKey,
   CSSM_TP_CertReclaimKey - Get private key associated with a
                            certificate (CDSA)

 SYNOPSIS
   # include <cssm.h>

    API:
        CSSM_RETURN CSSMAPI CSSM_TP_CertReclaimKey
        (CSSM_TP_HANDLE TPHandle,
        const CSSM_CERTGROUP *CertGroup,
        uint32 CertIndex,
        CSSM_LONG_HANDLE KeyCacheHandle,
        CSSM_CSP_HANDLE CSPHandle,
        const CSSM_RESOURCE_CONTROL_CONTEXT *CredAndAclEntry)
    SPI:
        CSSM_RETURN CSSMTPI TP_CertReclaimKey
        (CSSM_TP_HANDLE TPHandle,
        const CSSM_CERTGROUP *CertGroup,
        uint32 CertIndex,
        CSSM_LONG_HANDLE KeyCacheHandle,
        CSSM_CSP_HANDLE CSPHandle,
        const CSSM_RESOURCE_CONTROL_CONTEXT *CredAndAclEntry)

 LIBRARY
   Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE)

 PARAMETERS
   TPHandle (input)
           The handle that describes the service provider module used
           to perform this operation.

   CertGroup (input)
           A pointer to a structure containing a reference to a group
           of certificates and the number of certificates contained in
           that group. The certificate group contains all certificates
           that are candidates for reclamation.

   CertIndex (input)
           An index value that identifies the certificate whose
           associated private key is to be recovered and stored in
           the local CSP. This index value I references the I-th
           certificate in CertGroup.

   KeyCacheHandle (input)
           A reference handle that uniquely identifies the cache of
           protected private keys associated with the reclaimed
           certificates contained in CertGroup. The structure of the
           cache is opaque to the caller.

   CSPHandle (input)
           The handle that describes the CSP module where the private
           key is to be stored. Optionally, the CA service provider
           can use this CSP to perform additional cryptographic
           operations or may use another default CSP for that purpose.

   CredAndAclEntry (input/optional)
           A structure containing one or more credentials authorized
           for creating a key and the prototype ACL entry that will
           control future use of the newly created key. The credentials
           and ACL entry prototype can be presented as immediate values
           or callback functions can be provided for use by the CSP to
           acquire the credentials and/or the ACL entry interactively.
           If the CSP provides public access for creating a key, then
           the credentials can be NULL.  If the CSP defines a default
           initial ACL entry for the new key, then the ACL entry
           prototype can be an empty list.

 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 reclaimed from a certificate authority.

   The particular private key to be recovered to the local system
   is identified by its associated certificate. The certificate is
   identified by its CertIndex position within the CertGroup.

   The reclamation process associates the private key with the public
   key contained in the certificate, and securely stores the private
   key in the specified cryptographic service provider. The CSP can
   require that the caller provide access credentials authorizing
   inserting a new key into the CSP through an UnwrapKey operation.
   The caller should also provide an initial Access Control List (ACL)
   entry for the newly inserted key. The ACL entry is used to control
   future use of the recovered private key. These inputs are provided
   in CredAndAclEntry.

   When all required private keys have been reclaimed, the key cache
   can be discarded using the function CSSM_TP_CertReclaimAbort()
   (CSSM API), or TP_CertReclaimAbort() (TP SPI). The caller must free
   the CertGroup when it is no longer needed.

 RETURN VALUE
   A CSSM_RETURN value indicating success or specifying a particular
   error condition. The value CSSM_OK indicates success. All other
   values represent an error condition.

 ERRORS
   Errors are described in the CDSA technical standard.  See CDSA.

        CSSMERR_TP_INVALID_CERTGROUP_POINTER
        CSSMERR_TP_INVALID_CERTGROUP
        CSSMERR_TP_INVALID_CERTIFICATE
        CSSMERR_TP_INVALID_INDEX
        CSSMERR_TP_INVALID_KEYCACHE_HANDLE
        CSSMERR_TP_INVALID_CSP_HANDLE
        CSSMERR_TP_AUTHENTICATION_FAILED
        CSSMERR_TP_INSUFFICIENT_CREDENTIALS

 SEE ALSO
   Books

   Intel CDSA Application Developer's Guide (see CDSA)

   Other Help Topics

   Functions for the CSSM API:

       CSSM_TP_RetrieveCredResult
       CSSM_TP_Cert_ReclaimAbort

   Functions for the TP SPI:

       TP_RetrieveCredResult
       TP_Cert_ReclaimAbort