NAME
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.
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
Online Help
Functions for the CSSM API:
CSSM_TP_RetrieveCredResult, CSSM_TP_Cert_ReclaimAbort
Functions for the TP SPI:
TP_RetrieveCredResult, TP_Cert_ReclaimAbort
