TP_CertReclaimKey
» Table of Contents |  | | » Glossary | | | » Index | | |
| | |
| ||
| ||
SYNOPSIS
# include <cssm.h>
|
|
|
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.
|
|
|