com.entrust.toolkit.credentials

Class EntrustP10CertRetriever

java.lang.Object

com.entrust.toolkit.credentials.EntrustP10CertRetriever

public class EntrustP10CertRetriever
extends java.lang.Object

Enables unmanaged end user certificates to be retrieved from an Entrust Authority Security Manager (EASM) when the key pair is generated externally.

This capability is only available with an EASM that supports PKIX-CMP operation in "Administrator Authenticated" (AA) mode; (EASM version 7.1 patch 96478 or later).

Requirement:

EASM version 7.1 patch 96478 or later.

Certificates can be retrieved for end user's that exist on the EASM in the 'added' or 'keyrecover' state. When in either state, a reference number and authorization code will be available at the EASM for the end user. The reference number and authorization code, along with one or more pieces of certificate request information, are required in order to request unmanaged end user certificates.

Each piece of certificate request information will contain the public key for which certification is being requested, an identifier for the certificate definition policy that the request corresponds to, and any requested X.509 certificate extensions. Every Entrust user is given a certificate type, which in turn contains a set of certificate definitions. Each certificate definition represents one of the user's key/certificate pairs, and contains the client policy settings governing this key/certificate. The certificate definition identifier itself is represented as a EntrustCertInfoId structure, which simply contains a string name and/or integer id. For example, the following are some of the pre-defined certificate types and the certificate definitions they contain.

ent_twokeypair_p10 (33)

Encryption_p10 (56)

Verification_p10 (57)

ent_default (3)

Encryption (1)

Verification (2)

ent_skp_dualusage (24)

Dual Usage (46)

ent_nonrepud_and_efs (23)

Encryption (42)

Verification (43)

Nonrepudiation (44)

EFS (45)

The above certificate types and definitions are represented with their corresponding identifiers using 'name (id)' format. All certificate types and the certificate definitions they contain are defined in the master certificate specification. The certificate definition identifier names can be obtained from the master certificate specification or viewed using the Security Manager Administration application.

Because the key pair is being generated externally, certain certificate definition policy settings are automatically over ridden when using this API. Regardless of the actual certificate definition policy settings, the following settings are ignored and the indicated values instead implied:

entrustCertDefnAllowCMPOverride

true (values in the PKIX-CMP protocol over-ride other CMP related certificate definition policy settings).

entrustCertDefnKeyClientGenerated

true (keys are always client generated; the key-pair is generated externally and the public key is injected via the certificate request information).

entrustCertDefnKeyBackup

false (keys are always client generated and only the public key is injected via the certificate request information; private key backup is not possible).

entrustCertDefnKeyType

client selected (the key type is defined by the client at key generation time).

Unmanaged certificates can be requested/retrieved for an end user by calling either of the retrieveUserCert or retrieveUserCerts APIs. In either case the PKIX-CMP protocol is used to communicate with the EASM. A General Message transaction is done followed by an Initialization or Key Recovery transaction (depending on the user's state). Following a successful request the retrieved end user certificate will be attached to the appropriate certificate request information that was passed in.

The EASM imposes the following restrictions on how certificates are requested/retrieved:

Restrictions:

The EASM only permits one certificate to be requested at a time for each certificate definition defined in the user's certificate type.

The EASM does not permit certificates to be requested for certificate definitions that that are not defined in the user's certificate type.

However, the EASM does not require that a request be made for each and every certificate definition in the user's certificate type. A request can be made for only one of the user's certificate definitions if necessary.

The key usage extension that will appear in the requested certificate is extracted from the master certificate specification (if it has been defined). The master certificate specification allows a key usage to be defined for every certificate definition in every certificate type. When requesting a certificate for a certificate definition that does not have a key usage defined in the master certificate specification, a default key usage will automatically be included by the EASM (based on policy). A key usage set in the master certificate specification always takes precedence over a value passed in with via certificate request information.

Other extensions (and their values) can also be requested/specified in the certificate request information; for more details on this, refer to EntrustPKIXCMPInjectedCertReqInfo.setX509Extensions(X509Extensions).

A new certificate type 'ent_twokeypair_p10' was defined specifically for use with this Toolkit feature. The CMP related policy values for each certificate definition in this certificate type have been set to reflect the operation of PKIX-CMP in AA mode. Also, for these certificate definitions, no X.509 extensions have been pre-defined in the master certificate specification. The gives the client complete control over X.509 extensions (when X.509 extension are defined in the master certificate specification they over-ride values provided in PKIX-CMP). This API is can be used to request certificates that correspond to any certificate definition, not only the ones in the 'ent_twokeypair_p10' certificate type.

Since:

7.1sp1

See Also:

EntrustP10CertReqInfo

Constructor Summary

Constructors

Constructor and Description
EntrustP10CertRetriever(ManagerTransport managerTransport, User raUser) The constructor; creates an EntrustP10CertRetriever that will communicated with the specified Entrust Authority Security Manager (EASM).

Method Summary

Methods

Modifier and Type	Method and Description
void	retrieveUserCert(SecureStringBuffer referenceNumber, AuthorizationCode authorizationCode, EntrustP10CertReqInfo certReqInfo) Requests and retrieves a single unmanaged certificate for an end user using the provided injected public key information.
void	retrieveUserCerts(SecureStringBuffer referenceNumber, AuthorizationCode authorizationCode, EntrustP10CertReqInfo[] certReqInfo) Requests and retrieves one or more unmanaged certificates for an end user using the provided certificate request information.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

EntrustP10CertRetriever

public EntrustP10CertRetriever(ManagerTransport managerTransport,
                       User raUser)

The constructor; creates an EntrustP10CertRetriever that will communicated with the specified Entrust Authority Security Manager (EASM).

Each CMP Initialization or Recovery request will contain a signature generated by an administrator (RA); this allows the EASM to verify that the request originated from an RA (an administrator authenticated request).

Parameters:

managerTransport - the connection to the Security Manager

raUser - the RA user

Throws:

java.lang.IllegalArgumentException - thrown if any of the parameters are null, the connection to the Security Manager has been closed, or the RA user is not logged in or does not have have a signing/verification key/certificate

Method Detail

retrieveUserCert

public void retrieveUserCert(SecureStringBuffer referenceNumber,
                    AuthorizationCode authorizationCode,
                    EntrustP10CertReqInfo certReqInfo)
                      throws EntrustPKIXCMPException

Requests and retrieves a single unmanaged certificate for an end user using the provided injected public key information.

Following a successful request, the retrieved end user certificate will be attached to the certificate request information that was passed in. The certificate can be accessed via EntrustP10CertReqInfo.getUserCertificate().

Parameters:

referenceNumber - the reference number assigned to the user; an 8 digit integer obtained from the Security Manager by the PKI Administrator

authorizationCode - the authorization code assigned to the user; an alphanumeric string (of the form ABCD-EFGH-IJKL) obtained from the Security Manager by the PKI Administrator

certReqInfo - certificate request information (public key, certificate definition identifier, certificate extensions)

Throws:

java.lang.IllegalArgumentException - if any of the parameters are null or if the certificate request information is invalid

EntrustPKIXCMPException - if an error occurs while communicating with the EASM or if an error is returned by the EASM

retrieveUserCerts

public void retrieveUserCerts(SecureStringBuffer referenceNumber,
                     AuthorizationCode authorizationCode,
                     EntrustP10CertReqInfo[] certReqInfo)
                       throws EntrustPKIXCMPException

Requests and retrieves one or more unmanaged certificates for an end user using the provided certificate request information.

Following a successful request, the retrieved end user certificate will be attached to the certificate request information that was passed in. The certificate can be accessed via EntrustP10CertReqInfo.getUserCertificate().

Parameters:

referenceNumber - the reference number assigned to the user; an 8 digit integer obtained from the Security Manager by the PKI Administrator

authorizationCode - the authorization code assigned to the user; an alphanumeric string (of the form ABCD-EFGH-IJKL) obtained from the Security Manager by the PKI Administrator

certReqInfo - certificate request information (public key, certificate definition identifier, certificate extensions)

Throws:

java.lang.IllegalArgumentException - if any of the parameters are null or if the certificate request information is invalid

EntrustPKIXCMPException - if an error occurs while communicating with the EASM or if an error is returned by the EASM