TP_CertReclaimKey(3)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 TPHan‐
dle, const CSSM_CERTGROUP *CertGroup, uint32 CertIndex, CSSM_LONG_HAN‐
DLE KeyCacheHandle, CSSM_CSP_HANDLE CSPHandle, const CSSM_RESOURCE_CON‐
TROL_CONTEXT *CredAndAclEntry) SPI: CSSM_RETURN CSSMTPI TP_CertRe‐
claimKey (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
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 candi‐
dates 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 pri‐
vate keys associated with the reclaimed certificates contained in Cert‐
Group. 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 addi‐
tional 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
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 iden‐
tified 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 recov‐
ered 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 repre‐
sent an error condition.
ERRORS
Errors are described in the CDSA technical standard. See
CDSA_intro(3). CSSMERR_TP_INVALID_CERTGROUP_POINTER CSS‐
MERR_TP_INVALID_CERTGROUP CSSMERR_TP_INVALID_CERTIFICATE CSS‐
MERR_TP_INVALID_INDEX CSSMERR_TP_INVALID_KEYCACHE_HANDLE CSS‐
MERR_TP_INVALID_CSP_HANDLE CSSMERR_TP_AUTHENTICATION_FAILED CSS‐
MERR_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)TP_CertReclaimKey(3)
