com.entrust.toolkit.credentials

Class EntrustPKIXCMPInjectedCertReqInfo

java.lang.Object

com.entrust.toolkit.credentials.EntrustPKIXCMPInjectedCertReqInfo

Direct Known Subclasses:

CardMSCertReqInfo, EntrustP10CertReqInfo

public class EntrustPKIXCMPInjectedCertReqInfo
extends java.lang.Object

Represents certificate request information that can be injected into the Entrust Certificate Management Protocol (PKIX-CMP) implementation.

It simply defines the interface for which the various components of the injected certificate request information can be retrieved. These components are the following:

Certificate Type Identifier

An identifier for the certificate type assigned to the user that this certificate request information corresponds to. (OPTIONAL)

Certificate Definition Identifier

An identifier for the certificate definition that this certificate request information corresponds to.

Public Key

The public key for which certification is being requested. (OPTIONAL - required when the certificate definition policy indicates the key pair is client generated)

Private Key

The private key for which certification is being requested. (OPTIONAL)

Proof of Possession of Signing Key

Provides proof of possession for a signing private key. (OPTIONAL - required when requesting a certificate that corresponds to a certificate definition that indicates either 'verification' or 'both' key usage when using PKIX-CMP in normal mode (not AA mode); not required and ignored when using PKIX-CMP in AA mode)

Private Key Archive Information

Provides information regarding whether or not the private key should be backed up by the server; in the case of client generated keys, it should contain the encrypted private key when backup is required. This value is ignored for server generated keys, which are always backed up. (OPTIONAL - ignored for server generated keys; when not set, no backup is assumed client generated private keys)

X509 Certificate Extensions

A set of X.509 certificate extensions the client is requesting be included in the requested certificate. (OPTIONAL - allows the caller to provide specific extensions that are requested to appear in the certificate; this is only supported when using PKIX-CMP in AA mode)

Request Reason

A request reason indicator; indicates why the certificate is being requested. (OPTIONAL - only required when doing a PKIX-CMP key update/certification operation)

Latest Certificate

The latest certificate in the certificate stream. (OPTIONAL - only required when doing a PKIX-CMP key update operation)

Peak Certificate Stream Index

The highest stream index of all certificates in the stream. (OPTIONAL - only required when doing a PKIX-CMP key update operation)

AA mode PKIX-CMP refers to Administrator Authenticated mode. To operate PKIX-CMP in AA mode, a user with administrative privileges (a Registration Authority or RA) must be present during the PKIX-CMP transaction. The RA user signs the PKIX-CMP messages, proving to the Entrust Authority Security Manager (EASM) that they approve the request. This removes the requirement for proof of possession (since the RA user is trusted) and allows the caller to request certificate extensions. PKIX-CMP in AA mode is supported for Initialization and Recovery requests in EASM 7.1 patch 96478 or later. PKIX-CMP in AA mode is supported for Key Update/Certification and Certificate Store Synchronization requests in EASM 7.1 SP1 or later.

The EASM is aware of a specific set of X.509 extensions; this group of extensions is called 'known' extensions. However, the EASM only allows a subset of these extensions to be requested/controlled via PKIX-CMP for end entity certificates (user certificates). Known extensions that cannot be requested/controlled via PKIX-CMP for end entity certificates SHOULD NOT be provided using this API; doing so is unsupported (EASM may ignore extension or return error). Below is a list all known extensions that the EASM does not allow in PKIX-CMP certificate requests:

• authorityKeyIdentifier (2.5.29.35)
• basicConstraints (2.5.29.19)
• cRLDistributionPoints (2.5.29.31)
• cRLNumber (2.5.29.20)
• entrustVersInfo (1.2.840.113533.7.65.0)
• invalidityDate (1 2.5.29.24)
• issuingDistributionPoint (2.5.29.28)
• netscapeRevocationUrl (2.16.840.1.113730.1.3)
• reasonCode (2.5.29.21)
• subjectKeyIdentifier (2.5.29.14)

Known extensions that can be requested/controlled via PKIX-CMP for end entity certificates can be provided by the caller. Below is a list all known extensions that the EASM does allow to be requested via PKIX-CMP when used in AA mode:

• certificatePolicies (2.5.29.32)
  

  PKIX-CMP (in AA mode) can be used to set the value and criticality of the certificiatePolicies extension and also to set policyQualifiers. The value specified via PKIX-CMP is overridden (ignored) when a per-user setting exists or when the extension is set in the master certificate specification.

• extendedKeyUsage (2.5.29.37)
  

  PKIX-CMP (in AA mode) can be used to set the value and criticality of the extendedKeyUsage extension. The value specified via PKIX-CMP is overridden (ignored) when the extension is set in the master certificate specification.

• keyUsage (2.5.29.15)
  

  PKIX-CMP (in AA mode) can be used to set the value and criticality of the keyUsage extension. Since PKIX-CMP is used to request end entity certificates, the EASM will not accept key usage bits keyCertSign or cRLSign in a PKIX-CMP certificate request (request will be refused). The value specified via PKIX-CMP is overridden (ignored) when the extension is set in the master certificate specification. An invalid key usage will result in an error from the EASM (keyEncipherment with a DSA key pair).

• netscapeCertType (2.16.840.1.113730.1.1)
  

  PKIX-CMP (in AA mode) can be used to set the value and criticality of the netscapeCertType extension. The value specified via PKIX-CMP is overridden (ignored) when the extension is set in the master certificate specification.

• privateKeyUsagePeriod (2.5.29.16)
  

  PKIX-CMP (in AA mode) can be used to set the value and criticality of the privateKeyUsagePeriod extension for verification certificate requests only. For encryption certificate requests, the EASM will ignore and not include the extension in the certificate. If the user has no key rollover set or a custom private key usage setting, the privateKeyUsage will be changed to the custom values. If the privateKeyUsagePeriod received via from PKIX-CMP is invalid, it will be changed by the EASM.

• subjectAltName (2.5.29.17)
  

  PKIX-CMP (in AA mode) can be used to set the value and criticality of the subjectAltName extension (only a Security Officer can set criticality). The subjectAltName can also be set by an administrator with a per-user policy setting. SubjectAltName values are merged when values are set for the user and received in a PKIX-CMP request.

• subjectDirectoryAttributes (2.5.29.9)
  

  PKIX-CMP (in AA mode) can be used to set the value and criticality of the subjectDirectoryAttributes extension. The subjectDirectoryAttributes can also be set in the master certificate specification. SubjectDirectoryAttributes values are merged when values are set in the master certificate specification and received in a PKIX-CMP request.

All remaining extensions are considered unknown extensions, all of which can also be requested via PKIX-CMP in AA mode. The value specified via PKIX-CMP is overridden (ignored) when the extension is set in the master certificate specification. When operating in AA mode, proof of possession is not required; however, if provided it will be checked and enforced by the EASM.

Certain extensions are included by default in end user certificates issued by an EASM (authorityKeyIdentifier, basicConstraints, ...). This automatic inclusion can be disabled for specific extensions via certificate definition policy. For more information, please refer to EASM documentation.

Since:

7.1sp1

Method Summary

Methods

Modifier and Type	Method and Description
EntrustCertInfoId	getCertDefnId() Returns the identifier of the certificate definition that this certificate request information corresponds to.
OptionalValidity	getOptionalValidity() Returns the certificate request optional validity.
PKIArchiveOptions	getPKIArchiveOptions() Returns archive information pertaining to the private key.
POPOSigningKey	getPOPOSigningKey() Returns the proof of possession of a signing private key.
java.security.PrivateKey	getPrivateKey() Returns the private key for which certification is being requested.
java.security.PublicKey	getPublicKey() Returns the public key for which certification is being requested.
X509Extensions	getX509Extensions() Returns the X.509 extensions (including extension values) that are requested to be included in the end user certificate.
void	setOptionalValidity(OptionalValidity validity) Sets the OptionalValidity in the Certificate Request.
void	setPKIArchiveOptions(PKIArchiveOptions pkiArchiveOptions) Sets the archive information pertaining to the private key.
void	setPOPOSigningKey(POPOSigningKey popoSigningKey) Sets the proof of possession of a signing private key.
void	setPrivateKey(java.security.PrivateKey privateKey) Set the Private key for which certification is being requested
void	setPublicKey(java.security.PublicKey publicKey) Sets the public key for which certification is being requested.
void	setX509Extensions(X509Extensions x509Extensions) Sets the X.509 extensions (including extension values) that are requested to be included in the end user certificate.

Methods inherited from class java.lang.Object

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

Method Detail

getCertDefnId

public EntrustCertInfoId getCertDefnId()

Returns the identifier of the certificate definition that this certificate request information corresponds to.

Returns:

the certificate definition identifier

getPublicKey

public java.security.PublicKey getPublicKey()

Returns the public key for which certification is being requested.

This value should only be set when the key pair is client generated.

Returns:

the public key

setPublicKey

public void setPublicKey(java.security.PublicKey publicKey)

Sets the public key for which certification is being requested.

Parameters:

publicKey - the public key

See Also:

getPublicKey()

getPrivateKey

public java.security.PrivateKey getPrivateKey()

Returns the private key for which certification is being requested.

This should only be set when the key pair is client generated.

Returns:

the private key

setPrivateKey

public void setPrivateKey(java.security.PrivateKey privateKey)

Set the Private key for which certification is being requested

Note. The private key is NEVER sent to the CA in this form. This key will be used to generate the proof of possession for a client generated key. Therefore this should only be set when the key pair is client generated.

Parameters:

privateKey - the Private key used to generate a proof of possession

getPOPOSigningKey

public POPOSigningKey getPOPOSigningKey()

Returns the proof of possession of a signing private key.

Proof of possession must be set for a signing/verification key pair when using PKIX-CMP in normal mode (not AA mode). It is required by the EASM to demonstrate that the CMS actually has the private signing key. Proof of possession is not required using PKIX-CMP in AA mode; however, if provided it will be checked and enforced by the EASM.

Returns:

proof of possession of a signing private key

setPOPOSigningKey

public void setPOPOSigningKey(POPOSigningKey popoSigningKey)

Sets the proof of possession of a signing private key.

Parameters:

popoSigningKey - proof of possession of a signing private key

getX509Extensions

public X509Extensions getX509Extensions()

Returns the X.509 extensions (including extension values) that are requested to be included in the end user certificate.

Requesting extensions is only supported when operating PKIX-CMP in AA mode.

Returns:

requested X.509 extensions (including extension values)

setX509Extensions

public void setX509Extensions(X509Extensions x509Extensions)

Sets the X.509 extensions (including extension values) that are requested to be included in the end user certificate.

Parameters:

x509Extensions - requested X.509 extensions (including extension values)

See Also:

getX509Extensions()

getOptionalValidity

public OptionalValidity getOptionalValidity()

Returns the certificate request optional validity.

The optional validity allows the client to specify the NotBefore and NotAfter dates for the certificate that is being requested. This can be used to over ride the policy configured at the CA if the CA is configured to accept this optional validity.

Returns:

the Optional Validity

setOptionalValidity

public void setOptionalValidity(OptionalValidity validity)

Sets the OptionalValidity in the Certificate Request. This is used to request optional validity periods from a client generated key.

Parameters:

validity - the OptionalValidity period for this injected request

See Also:

getOptionalValidity()

getPKIArchiveOptions

public PKIArchiveOptions getPKIArchiveOptions()

Returns archive information pertaining to the private key.

Archive information must be provided to the EASM for each certificate that is requested. When not set, a default structure indicating that the private key is not backed up is sent to the server. Currently, both the encryptedPrivKey and archiveRemGenPrivKey formats of archive information are supported. For a client generated private key that requires backup, the encryptedPrivKey format is used to indicate that backup is required and securely transfer the private key to the server for backup. For a private key that is server generated or does not require backup, the archiveRemGenPrivKey format is used to indicate whether or not the key should be backed up by the server.

Returns:

archive information pertaining to the private key

setPKIArchiveOptions

public void setPKIArchiveOptions(PKIArchiveOptions pkiArchiveOptions)

Sets the archive information pertaining to the private key.

Parameters:

pkiArchiveOptions - archive information pertaining to the private key (OPTIONAL)

Since:

8.0 Patch

See Also:

getPKIArchiveOptions()