TP_CertReclaimKey

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