Index for Section 3

Alphabetical listing for T

Bottom of page

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

SYNOPSIS
  # 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
  Common Security Services Manager library (libcssm.so)

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_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
  Books

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

  Reference Pages

  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)

Index for Section 3

Alphabetical listing for T

Top of page