TP_CertReclaimKey

If both a Table of Contents and Search form are not displayed in separate frames along with this one, you may wish to redisplay this book in a frameset, beginning with the first page.

HP Open Source Security for OpenVMS Volume 1:...

API Functions

TP_CertReclaimAbort

TP_CertRemoveFromCrlTemplate

TP_CertReclaimKey

Library
Description
Errors

Parameters
Return Value
See Also

NAME

TP_CertReclaimKey: 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 moduleused to perform this operation.
`CertGroup` (input)
		A pointer to a structure containing a referenceto a group of certificates and the number of certificates containedin that group. The certificate group contains all certificates thatare candidates for reclamation.
`CertIndex` (input)
		An index value that identifies the certificate whoseassociated private key is to be recovered and stored in the localCSP. This index value I references the I-th certificate in `CertGroup`.
`KeyCacheHandle` (input)
		A reference handle that uniquely identifies thecache of protected private keys associated with the reclaimed certificatescontained in `CertGroup`. The structure of thecache is opaque to the caller.
`CSPHandle` (input)
		The handle that describes the CSP module where theprivate key is to be stored. Optionally, the CA service providercan use this CSP to perform additional cryptographic operationsor may use another default CSP for that purpose.
`CredAndAclEntry` (input/optional)
		A structure containing one or more credentials authorizedfor creating a key and the prototype ACL entry that will controlfuture use of the newly created key. The credentials and ACL entryprototype can be presented as immediate values or callback functionscan be provided for use by the CSP to acquire the credentials and/orthe ACL entry interactively. If the CSP provides public access forcreating a key, then the credentials can be NULL. If the CSP definesa default initial ACL entry for the new key, then the ACL entryprototype can be an empty list.

DESCRIPTION

This function recovers the private key associated with a certificateand securely stores that key in the specified Cryptographic ServiceProvider. The key and its associated certificate are among a setof certificates and private keys reclaimed from a certificate authority.

The particular private key to be recovered to the local systemis identified by its associated certificate. The certificate isidentified by its CertIndex position within the CertGroup.

The reclamation process associates the private key with thepublic key contained in the certificate, and securely stores theprivate key in the specified Cryptographic Service Provider. TheCSP can require that the caller provide access credentials authorizinginserting 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 controlfuture use of the recovered private key. These inputs are providedin CredAndAclEntry.

When all required private keys have been reclaimed, the keycache can be discarded using the function CSSM_TP_CertReclaimAbort() (CSSM API), or TP_CertReclaimAbort() (TP SPI). The caller must free the CertGroup whenit is no longer needed.

RETURN VALUE

A CSSM_RETURN value indicating success or specifying a particularerror condition. The value CSSM_OK indicates success. All othervalues represent an error condition.

ERRORS

Errors are described in the CDSA Technical Standard.

CSSMERR_TP_INVALID_CERTGROUP_POINTERCSSMERR_TP_INVALID_CERTGROUPCSSMERR_TP_INVALID_CERTIFICATECSSMERR_TP_INVALID_INDEXCSSMERR_TP_INVALID_KEYCACHE_HANDLECSSMERR_TP_INVALID_CSP_HANDLECSSMERR_TP_AUTHENTICATION_FAILEDCSSMERR_TP_INSUFFICIENT_CREDENTIALS