NAME    [Toc]    [Back]

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

SYNOPSIS    [Toc]    [Back]

       # include <cdsa/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    [Toc]    [Back]

       Common Security Services Manager library (libcssm.so)

PARAMETERS    [Toc]    [Back]

       The handle that describes the service provider module used
       to perform this operation.  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.  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.  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.  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.  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    [Toc]    [Back]

       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    [Toc]    [Back]

       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    [Toc]    [Back]

       Errors  are described in the CDSA technical standard.  See
       CDSA_intro(3).  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    [Toc]    [Back]

       Books

       Intel   CDSA   Application    Developer's    Guide    (see
       CDSA_intro(3))

       Reference Pages    [Toc]    [Back]

       Functions for the CSSM API:

       CSSM_TP_RetrieveCredResult(3),
       CSSM_TP_Cert_ReclaimAbort(3)

       Functions for the TP SPI:

       TP_RetrieveCredResult(3), TP_Cert_ReclaimAbort(3)



                                             TP_CertReclaimKey(3)