HP Open Source Security for OpenVMS Volume 1: Common Data Security Architecture > CDSA API Functions

TP_CertReclaimKey

 » Table of Contents

 » Glossary

 » Index

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