com.entrust.toolkit.credentials

Class CMPForCardMS

java.lang.Object

com.entrust.toolkit.credentials.CMPForCardMS

public final class CMPForCardMS
extends java.lang.Object

This class is designed to provide access to specific Certificate Management Protocol (CMP) operations required by a Card Management System (CardMS).

CMP is a client/server protocol that allows clients to initiate and execute various certificate management operations for users that exist in a Public Key Infrastructure (PKI). This implementation requires that the PKI be an Entrust Authority Security Manager (EASM) version 7.0 or later. The client in this case will be the Toolkit (controlled via the CardMS).

This implementation has two modes of operation:

Normal mode

In normal mode, CMP messages are protected by the end user (via reference number and authorization code). Because the requestor (the end user) is not implicitly trusted by the EASM, manual proof of possession must be provided for every certificate request that includes a client generated private key; this is done via CardMSCertReqInfo.setPOPOSigningKey(POPOSigningKey). Client requested certificate extensions ARE NOT supported in normal mode.

Administrator Authenticated (AA) mode

In AA mode, CMP message are protected by the signature of a Registration Authority (RA). Because the requestor (the RA) is implicitly trusted by the EASM, manual proof of possession is not required. However, if manual proof of possession is provided in the certificate request (for an added layer of security), it will be checked and enforced by the EASM. Client requested certificate extensions are supported in AA-mode; this allows the caller to request any custom certificate extensions that they require (see CardMSCertReqInfo.CardMSCertReqInfo(EntrustCertInfoId, PublicKey, POPOSigningKey, X509Extensions) ). For further details on AA mode and supported extensions, please refer to the class documentation of EntrustPKIXCMPInjectedCertReqInfo.

This implementation supports the following operations:

• user creation/recovery (Normal mode - EASM 7.0 or later)
• user creation/recovery (AA mode - EASM 7.1 patch 96478 or later)
• digital identity management (AA mode - EASM 7.1 SP1 or later)

In the case of user creation, the user must be setup for creation at the EASM; similarly, in the case of user recovery, the user must be setup for recovery by the EASM. For digital identity management, the user must exist in the active state at the EASM.

A typical CardMS requires that all signing keys be generated by the CardMS and never leave the CardMS (not backed-up by the EASM). They also require that all decryption keys that are generated by EASM be securely transferred back to the CardMS. In this release of the CardMS API supports creation/recovery/management of users whose keys meet the following policy requirements:

• CardMS generated, backed-up
• signing/verification, CardMS generated, not backed-up
• encryption/decryption, EASM generated, backed-up
• encryption/decryption, CardMS generated, not backed-up (AA-mode only)

Users can have any number (up to 4) of separate key pairs, as long as each falls into one of the above categories. Attempting to create/recover/manage users whose keys do not meet the above requirements will result in unexpected behavior, and most likely result in failure.

Each operation requires three message transmissions between the JTK and the EASM, they are listed in the order in which they must be executed:

General Message transmission

Initiates the CMP operation and requests user policy and various CMP related information from the EASM.

Certificate Management transmission (initialization, recovery, certificate store synchronization, key update/certification)

Requests certification of a user's signing/verification keys and retrieves the user's encryption/decryption keys and certificates (new keys/certificates in the case of initialization or key update/certification, backed-up keys and certificates in the case of recovery or certificate store synchronization).

Confirmation or Error transmission

Completes the CMP operation successfully (results in an active user) or unsuccessfully (can result in revoked certificates or a disabled user).

Following a successful operation, a software representation of the Entrust digital identity can be retrieved. Two smart card based digital identity formats are supported:

Entrust MS-CAPI format digital identity

This is a smart card based digital identity in Entrust Microsoft CryptoAPI (MS-CAPI) format. Following a user creation or recovery operation, it contains all the MS-CAPI key containers that the digital identity is composed of. Following a digital identity management operation, it contains the MS-CAPI key containers that need to be added to the digital identity. In this format, it does not matter how the digital identity information is stored on the smart card, only that the user's keys and certificates (and potentially CA certificates) are accessible though MS-CAPI. This smart card based digital identity format is recognized by applications like Entrust TruePass and Entrust Entelligence Security Provider (ESP). Following a successful operation, a software representation of the digital identity in Entrust MS-CAPI format can be retrieved via getMscapiDigitalIdRepresentation()

Entrust PKCS #11 format digital identity

This is a smart card based digital identity in Entrust PKCS #11 format. Following a user creation or recovery operation, it contains all the PKCS #11 objects that the digital identity is composed of (digital identity management is not supported for PKCS #11 format digital identities). This smart card based digital identity format is recognized by Entrust applications like Entrust Entelligence Desktop Manager and Entrust Authority Toolkits (Java, File). Following a successful operation, a software representation of the digital identity in Entrust PKCS #11 format can be retrieved via getDigitalIdRepresentation(SecureStringBuffer)

Following the certificate management transmission (initialization, recovery, certificate store synchronization, key update/certification), but before the confirmation transmission, it is the responsibility of the CardMS to retrieve a software representation of the Entrust smart card based digital identity and ensure that the identity is written to the smart card.

In MS-CAPI, keys and certificates are stored in key containers, which are associated with a key container name. Entrust has defined a key container naming schema that should be used with Entrust MS-CAPI format digital identities. This naming format provides additional information to Entrust applications about the key and certificate that exists in the key container. Without this key container naming schema, Entrust applications can still use this type of digital identity, however, management is not possible.

It is also possible to create a smart card based digital identity that is compatible with both formats. The CardMS can do so by writing all the PKCS #11 objects to the smart card and then importing the keys and certificates into MS-CAPI. One note of caution though, this type of digital identity should never be managed by an Entrust application that uses Entrust MS-CAPI format digital identities. Doing so would change the digital identity is such a way that would break compatibility with Entrust applications that use Entrust PKCS #11 format digital identities. However, managing this type of digital identity with an Entrust application that uses Entrust PKCS #11 format digital identities is permitted so long as the smart card driver automatically propagates any new keys and certificates into MS-CAPI.

Digital identity management (certificate store synchronization and/or key update/certification) is only supported in conjunction an Entrust client application that supports integration with a CardMS (CardMS enabled). Currently, this is only ESP 8.0 or later. The CardMS enabled Entrust client application will detect digital identity management operations that are required and report these to the CardMS in a CardMSDigitalIDMgmtInfo structure. The CardMS will examine this structure and then execute the appropriate digital management operations using the certStoreSynch(X509Certificate, CardMSDigitalIDMgmtInfo) and/or keyUpdateAndCertification(CardMSCertReqInfo[], X509Certificate, CardMSDigitalIDMgmtInfo) APIs. (Refer to the above links for more details on digital identity management for a CardMS).

Before using this class, please ensure that the Entrust cryptographic service provider has been installed. This can be done by making the following call:

 Initializer.getInstance().setProviders(Initializer.MODE_NORMAL);
 

Attempting to use this class to do CMP message transmissions when the Entrust cryptographic service provider has not been installed will result in a SecurityException being thrown.

Since:

7.0sp1

See Also:

RFC 2510: Certificate Management Protocols, RFC 2511: Certificate Request Message Format

Constructor Summary

Constructors

Constructor and Description
CMPForCardMS(ManagerTransport easmConnection) The constructor; creates a new CMPForCardMS object configured to operate in normal mode.
CMPForCardMS(ManagerTransport easmConnection, User raUser) The constructor; creates a new CMPForCardMS object configured to operate in AA mode.
CMPForCardMS(java.lang.String easmIP, int easmCMPPort) The constructor; creates a new CMPForCardMS object configured to operate in normal mode.

Method Summary

Methods

Modifier and Type	Method and Description
void	certStoreSynch(CardMSDigitalIDMgmtInfo digitalIdMgmtInfo, java.security.PublicKey clientProtEncKey) Executes a certificate store synchronization transmission that requests all backed up user keys and certificates from the server; refer to certStoreSynch(X509Certificate, CardMSDigitalIDMgmtInfo) for more details.
void	certStoreSynch(X509Certificate cardMSProtocolEncrCert, CardMSDigitalIDMgmtInfo digitalIdMgmtInfo) Executes a certificate store synchronization transmission that requests all backed up user keys and certificates from the server.
void	confirmation() Executes a confirmation transmission.
static java.security.PrivateKey	decryptEncryptedPrivateKey(EncryptedValue encryptedPrivateKey, java.security.PrivateKey clientProtDecKey) Decrypts a private key from an EncryptedValue structure.
void	error(java.lang.String errorMessage) Executes an error transmission.
void	generalMessage(Name userDN) Executes an administrator protected general message transmission for an initialized user (has already been created).
void	generalMessage(SecureStringBuffer refNum, AuthorizationCode authCode) Executes a general message transmission for an uninitialized user (has yet to be created) or an initialized user that will be recovered.
java.security.KeyPair	generateClientProtlEncKeys(boolean keyRecovery, java.util.Iterator<? extends EntrustPKIXCMPInjectedCertReqInfo> certificateRequests) Generates the client protocol encryption key pair in software.
PKIArchiveOptions	generatePKIArchiveOptionsForClientGenBackup(java.security.PrivateKey privateKey) Generates a PKIArchiveOptions structure representing a client generated private key that is to be backed up by the Certification Authority.
POPOSigningKeyInput	generatePOPOSigningKeyInput(java.security.PublicKey publicKey, AuthorizationCode authCode) Generates a POPOSigningKeyInput structure appropriate for use in demonstrating proof of possession of a private signing key.
EntrustCertTypeSettings	getCertPolicySettings() Returns the certificate policy information that was retrieved during a previous general message transmission.
ClientSettings	getClientSettings() Returns the client policy information that was retrieved during a previous general message transmission.
java.util.List<EntrustSigConfig>	getDefaultProtocolSigningAlgs() Gets the caller configured default value for the protocol signing algorithm configuration list.
P11StorageObject[]	getDigitalIdRepresentation(SecureStringBuffer password) Returns a representation of an Entrust digital identity in Entrust PKCS #11 format.
boolean	getIncludeUserCertHistory() Gets an indicator for whether or not the entire user certificate history will be included in the digital identity representation.
MscapiKeyContainer[]	getMscapiDigitalIdRepresentation() Returns a representation of an Entrust digital identity in Entrust MS-CAPI format.
EntrustState	getUserState() Returns the user's current state.
void	initializeAll(CardMSCertReqInfo[] injectedCertReqInfo, X509Certificate cardMSProtocolEncrCert) Executes an initialization transmission that initializes all keys and certificates for a user.
void	initializeAll(java.security.PublicKey clientProtEncKey, CardMSCertReqInfo[] injectedCertReqInfo) Executes an initialization transmission that initializes all keys and certificates for a user; refer to initializeAll(CardMSCertReqInfo[], X509Certificate) for more details.
void	initializeSelected(CardMSCertReqInfo[] injectedCertReqInfo, X509Certificate cardMSProtocolEncrCert) Executes an initialization transmission that initializes selected keys and certificates for a user.
void	initializeSelected(java.security.PublicKey clientProtEncKey, CardMSCertReqInfo[] injectedCertReqInfo) Executes an initialization transmission that initializes selected keys and certificates for a user; refer to initializeSelected(CardMSCertReqInfo[], X509Certificate) for more details.
void	keyUpdateAndCertification(CardMSCertReqInfo[] injectedCertReqInfo, X509Certificate cardMSProtocolEncrCert, CardMSDigitalIDMgmtInfo digitalIdMgmtInfo) Executes a key update/certification transmission for a user that updates existing certificates and/or requests new certificates.
void	keyUpdateAndCertification(java.security.PublicKey clientProtEncKey, CardMSCertReqInfo[] injectedCertReqInfo, CardMSDigitalIDMgmtInfo digitalIdMgmtInfo) Executes a key update/certification transmission for a user that updates existing certificates and/or requests new certificates; refer to keyUpdateAndCertification(CardMSCertReqInfo[], X509Certificate, CardMSDigitalIDMgmtInfo) for more details.
void	recoverAll(CardMSCertReqInfo[] injectedCertReqInfo, X509Certificate cardMSProtocolEncrCert) Executes a recovery transmission that recovers all keys and certificates for a user.
void	recoverAll(java.security.PublicKey clientProtEncKey, CardMSCertReqInfo[] injectedCertReqInfo) Executes a recovery transmission that recovers all keys and certificates for a user; refer to recoverAll(CardMSCertReqInfo[], X509Certificate) for more details.
void	recoverSelected(CardMSCertReqInfo[] injectedCertReqInfo, X509Certificate cardMSProtocolEncrCert) Executes a recovery transmission that recovers selected keys and certificates for a user.
void	recoverSelected(java.security.PublicKey clientProtEncKey, CardMSCertReqInfo[] injectedCertReqInfo) Executes a recovery transmission that recovers selected keys and certificates for a user; refer to recoverSelected(CardMSCertReqInfo[], X509Certificate) for more details.
void	setDefaultProtocolSigningAlgs(java.util.List<EntrustSigConfig> defaultProtocolSigningAlgs) Sets the caller configured default value for the protocol signing algorithm configuration list.
void	setIncludeUserCertHistory(boolean includeUserCertHistory) Sets an indicator for whether or not the entire user certificate history will be included in the digital identity representation.

Methods inherited from class java.lang.Object

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

Constructor Detail

CMPForCardMS

public CMPForCardMS(ManagerTransport easmConnection)

The constructor; creates a new CMPForCardMS object configured to operate in normal mode.

All that is required to instantiate this object is a connection to the EASM. This connection will be used during all message transmissions as the medium for communication with the EASM. The connection with the EASM should not be shared among various CMPForCardMS objects, every CMPForCardMS must have its own unique connection to the EASM.

Parameters:

easmConnection - the connection with the EASM

Throws:

java.lang.IllegalArgumentException - if managerTransport is null or if it represents a connection that has been closed

java.lang.SecurityException - if cryptographic algorithms provided by the 'Entrust' JCA cryptographic provider could not be found

CMPForCardMS

public CMPForCardMS(ManagerTransport easmConnection,
            User raUser)

The constructor; creates a new CMPForCardMS object configured to operate in AA mode.

The connection to the EASM will be used during all message transmissions as the medium for communication. The connection with the EASM should not be shared among various CMPForCardMS objects, every CMPForCardMS must have its own unique connection to the EASM. The

Operating in AA mode means that each CMP 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). When operating in AA mode, the caller is permitted to specify extensions that should appear in the requested certificates and proof of possession for client generated keys is not required (it is implicit since the RA is trusted). 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 signed general message requests and key update/certification requests in EASM 7.1 SP1 or later.

For details on AA mode and supported extensions, please refer to the class documentation of EntrustPKIXCMPInjectedCertReqInfo.

Parameters:

easmConnection - the connection with the EASM

raUser - the RA user

Throws:

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

java.lang.SecurityException - if cryptographic algorithms provided by the 'Entrust' JCA cryptographic provider could not be found

CMPForCardMS

public CMPForCardMS(java.lang.String easmIP,
            int easmCMPPort)

The constructor; creates a new CMPForCardMS object configured to operate in normal mode.

All that is required to instantiate this object is a connection to the EASM. This connection will be used during all message transmissions as the medium for communication with the EASM. The connection with the EASM is automatically from the IP and port specified. Using this constructor ensure that every CMPForCardMS object has its own unique connection to the EASM.

Parameters:

easmIP - the IP address of the EASM

easmCMPPort - the port on the EASM that is designated for CMP (typically 829)

Method Detail

decryptEncryptedPrivateKey

public static java.security.PrivateKey decryptEncryptedPrivateKey(EncryptedValue encryptedPrivateKey,
                                                  java.security.PrivateKey clientProtDecKey)
                                                           throws EntrustPKIXCMPException

Decrypts a private key from an EncryptedValue structure.

Parameters:

encryptedValue - the encrypted value

recipientPrivateKey - the recipient private key (used decrypt the encrypted value)

Returns:

the private key (decrypted value)

Throws:

EntrustPKIXCMPException - if an error occurred while decrypting the encrypted value

Since:

8.0 Patch

setIncludeUserCertHistory

public void setIncludeUserCertHistory(boolean includeUserCertHistory)

Sets an indicator for whether or not the entire user certificate history will be included in the digital identity representation. The default setting is false which indicates the certificate history is not included by default.

The certificate history refers to all the certificates that are backed-up at the EASM, not the private keys. The private key history is always included in the digital identity representation.

This setting only has an effect on a digital identity representation that results from a recovery operation (a certificate history does not yet exist following creation). Following recovery, all a user's keys and certificates are returned from the EASM. For users that have keys/certificate that are backed-up at the EASM this includes superseded keys/certificates (ones that have been replaced by more recent keys/certificates). These old backed-up certificates are a user's certificate history.

In a PKCS #11 formatted digital identity, the certificate history serves no purpose so these certificates are never written to the smart card. However, in CAPI, these certificates are required in order to be able to locate the corresponding private key. Without these certificates, the key history would be inaccessible from CAPI. When the getDigitalIdRepresentation(SecureStringBuffer) method is called, a P11StorageObject is returned. The P11StorageObject can be used to write keys to PKCS11 or CAPI (or any other format if required). Therefore, when using the P11StorageObject to write keys to CAPI, set this indicator to true to ensure that the certificate history is included so that the private key history can be accessed through CAPI.

This setting only has an effect on the digital identity representation when retrieved using the getDigitalIdRepresentation(SecureStringBuffer); it is ignored when the digital identity representation is retrieved using getMscapiDigitalIdRepresentation() which always includes the certificate history.

Parameters:

includeUserCertHistory - an indicator for whether or not the entire user certificate history will be included in the digital identity representation

getIncludeUserCertHistory

public boolean getIncludeUserCertHistory()

Gets an indicator for whether or not the entire user certificate history will be included in the digital identity representation.

Note: The certificate history is not the same thing as the key history. The certificate history refers to public certificates only, not the private keys. The private key history is always included in the digital identity representation.

Returns:

an indicator for whether or not the entire user certificate history will be included in the digital identity representation

See Also:

setIncludeUserCertHistory(boolean)

setDefaultProtocolSigningAlgs

public void setDefaultProtocolSigningAlgs(java.util.List<EntrustSigConfig> defaultProtocolSigningAlgs)

Sets the caller configured default value for the protocol signing algorithm configuration list.

The protocol signing algorithm configuration list is normally extracted from the client policy settings. However, if a General Message transaction has not been completed yet (e.g. when deciding what algorithm to sign the General Message transaction with), a default protocol signing algorithm configuration list is used. This API can be used to supply a caller configured custom default. For details on other configuration options for the default protocol signing algorithm configuration list refer to ClientSettings.getDefaultProtocolSigningAlgs(List).

Parameters:

protocolSigningAlgs - [OPTIONAL] the caller configured default value for the protocol signing algorithm configuration list

getDefaultProtocolSigningAlgs

public java.util.List<EntrustSigConfig> getDefaultProtocolSigningAlgs()

Gets the caller configured default value for the protocol signing algorithm configuration list.

Refer to setDefaultProtocolSigningAlgs(List) for additional details.

Returns:

the caller configured default value for the protocol signing algorithm configuration list; null if this value has not been configured yet

generalMessage

public void generalMessage(SecureStringBuffer refNum,
                  AuthorizationCode authCode)
                    throws EntrustPKIXCMPException

Executes a general message transmission for an uninitialized user (has yet to be created) or an initialized user that will be recovered.

This transmission requests/receives all general message content information known to the EASM. This consists mainly of user policy information and CMP related information. The following information is requested/received:

• Entrust Client Information - contains the main policy certificate and policy certificate for the user's role (aka: client settings).
• Entrust Certificate Policy - contains the user's certificate type identifier and policy certificate as well as all associated certificate definition identifiers and policy certificates.

The request/response is protected using MAC-protection with the user's reference number and authorization code. This message must be sent prior to all initialization or recovery transmissions.

Following this API call, all of the information received during the general message transmission can be retrieved using the following APIs:

• getClientSettings()
• getCertPolicySettings()

The policy information can be used by the CardMS to determine information about a user's key/certificate pairs. For each of the user's key/certificate pairs, a certificate definition will exist in the user's certificate type that defines policy information related to that specific key/certificate pair.

Parameters:

refNum - the user's reference number (issued by the EASM with the user is setup for creation/recovery)

authCode - the user's authorization code (issued by the EASM with the user is setup for creation/recovery)

Throws:

EntrustPKIXCMPException - if an error occurs during the general message transmission

java.lang.IllegalArgumentException - if any of the parameters are missing

generalMessage

public void generalMessage(Name userDN)
                    throws EntrustPKIXCMPException

Executes an administrator protected general message transmission for an initialized user (has already been created).

This transmission can only be executed when the CardMS API has been configured to operate in AA mode and when communicating with an EASM 7.1 SP1 or later. It requests/receives all general message content information known to the EASM. This consists mainly of user policy information and CMP related information. The following information is requested/received:

• Entrust Client Information - contains the main policy certificate and policy certificate for the user's role (aka: client settings).
• Entrust Certificate Policy - contains the user's certificate type identifier and policy certificate as well as all associated certificate definition identifiers and policy certificates.

The request/response is protected using signature protection with the administrator's signing/verification key/certificate. This message must be sent prior to a certificate store synchronization and/or key update/certification transmissions.

Following this API call, all of the information received during the general message transmission can be retrieved using the following APIs:

• getClientSettings()
• getCertPolicySettings()

The policy information can be used by the CardMS to determine information about a user's key/certificate pairs. For each of the user's key/certificate pairs, a certificate definition will exist in the user's certificate type that defines policy information related to that specific key/certificate pair.

Parameters:

userDN - the user's DN

Throws:

EntrustPKIXCMPException - if an error occurs during the general message transmission

java.lang.IllegalArgumentException - if any of the parameters are missing

java.lang.IllegalStateException - if the CardMS API is not configured to operate in AA mode

initializeAll

public void initializeAll(CardMSCertReqInfo[] injectedCertReqInfo,
                 X509Certificate cardMSProtocolEncrCert)
                   throws EntrustPKIXCMPException

Executes an initialization transmission that initializes all keys and certificates for a user.

This transmission requests/receives certification of ALL key pairs for a user that has been setup for creation. A certificate is requested for each of the certificate definitions in the user's certificate type (Encryption, Verification, ...). For certificate definitions that indicate client key generation (signing/verification key-pair generated by the CardMS), a certificate request information object MUST be provided that contains both a public key and proof of possession (when in normal mode). The certificate request information object is required to provide the actual public key being certified and to demonstrate proof of possession of the private signing key to the EASM. For certificate definitions that indicate server key generation (encryption/decryption key-pair generated by the EASM), certificate request information is not required; these keys/certificates are always automatically requested.

Proof of possession of a private signing key is demonstrated to the EASM by sending a POPOSigningKey structure in the request. It contains a signature over a known value, a POPOSigningKeyInput structure, using the corresponding private signing key. Since the private signing key is always generated by the CardMS and never leaves the CardMS, the CardMS must generate the POPOSigningKey. To make this process as easy as possible for the CardMS, an API is provided to generate the POPOSigningKeyInput structure, generatePOPOSigningKeyInput(PublicKey, AuthorizationCode). This structure contains a password based MAC (using the authorization code) of the public key. Proof of possession is not required using PKIX-CMP in AA mode; however, if provided it will be checked and enforced.

Following this transmission, the user's digital identity has been created and must be written by the CardMS. The software representation of the user's Entrust digital identity can be retrieved using the getDigitalIdRepresentation(SecureStringBuffer) or getMscapiDigitalIdRepresentation() API.

Any private keys that are generated by the EASM will be returned in the Entrust digital identity representation in protected format. They will exist as an EncryptedValue structure; this contains the user's private key encrypted using the CardMS client protocol encryption certificate that was specified. The CardMS must handle decrypting and extracting the private key from this protected format.

An initialization transmission requires information received during a general message transmission. Thus, prior to any initialization transmission, a general message transmission for the uninitialized user must be executed.

Following an initialization transmission, to complete a user create transaction, a confirmation transmission (or error transmission) must be done. If a confirmation transmission is not executed soon after the initialization transmission, the user will be active but all their certificates will be revoked by the EASM.

If an error occurs while receiving the initialization response, an error transmission is automatically executed. This causes the EASM to delete any keys/certificates that were issued to the user and return the user to the state it was in prior to the CMP transaction (setup for creation).

Parameters:

injectedCertReqInfo - information regarding the certificates that are being requested; allows the CardMS to inject information into the CMP protocol (certificate definition identifier, proof-of-possession, certificate extensions)

cardMSProtocolEncrCert - the CardMS protocol encryption certificate

Throws:

java.lang.IllegalArgumentException - if the certificate request information is not valid

EntrustPKIXCMPException - if an error occurs during the initialization transmission

initializeAll

public void initializeAll(java.security.PublicKey clientProtEncKey,
                 CardMSCertReqInfo[] injectedCertReqInfo)
                   throws EntrustPKIXCMPException

Executes an initialization transmission that initializes all keys and certificates for a user; refer to initializeAll(CardMSCertReqInfo[], X509Certificate) for more details.

Parameters:

clientProtEncKey - the CardMS client protocol encryption key

injectedCertReqInfo - information regarding the certificates that are being requested; allows the CardMS to inject information into the CMP protocol (certificate definition identifier, proof-of-possession, certificate extensions)

Throws:

java.lang.IllegalArgumentException - if the certificate request information is not valid

EntrustPKIXCMPException - if an error occurs during the initialization transmission

Since:

8.0 Patch

initializeSelected

public void initializeSelected(CardMSCertReqInfo[] injectedCertReqInfo,
                      X509Certificate cardMSProtocolEncrCert)
                        throws EntrustPKIXCMPException

Executes an initialization transmission that initializes selected keys and certificates for a user.

This transmission requests/receives certification of SELECTED key pairs for a user that has been setup for creation. A certificate is requested for each of the certificate definitions in the user's certificate type (Encryption, Verification, ...) for which a corresponding certificate request information object is provided. For certificate definitions that indicate client key generation (signing/verification key-pair generated by the CardMS), when provided, a certificate request information object MUST contain both a public key and proof of possession (when in normal mode). The certificate request information identifies the certificate definition, provides the actual public key being certified, and demonstrates proof of possession of the private signing key to the EASM. For certificate definitions that indicate server key generation (encryption/decryption key-pair generated by the EASM), when provided, a certificate request information object MUST NOT contain either the public key or proof of possession. The certificate request information identifies the certificate definition, but does not provide the public key or proof of possession.

Proof of possession of a private signing key is demonstrated to the EASM by sending a POPOSigningKey structure in the request. It contains a signature over a known value, a POPOSigningKeyInput structure, using the corresponding private signing key. Since the private signing key is always generated by the CardMS and never leaves the CardMS, the CardMS must generate the POPOSigningKey. To make this process as easy as possible for the CardMS, an API is provided to generate the POPOSigningKeyInput structure, generatePOPOSigningKeyInput(PublicKey, AuthorizationCode). This structure contains a password based MAC (using the authorization code) of the public key. Proof of possession is not required using PKIX-CMP in AA mode; however, if provided it will be checked and enforced.

Following this transmission, the user's digital identity has been created and must be written by the CardMS. The software representation of the user's Entrust digital identity can be retrieved using the getDigitalIdRepresentation(SecureStringBuffer) or getMscapiDigitalIdRepresentation() API.

Any private keys that are generated by the EASM will be returned in the Entrust digital identity representation in protected format. They will exist as an EncryptedValue structure; this contains the user's private key encrypted using the CardMS client protocol encryption certificate that was specified. The CardMS must handle decrypting and extracting the private key from this protected format.

An initialization transmission requires information received during a general message transmission. Thus, prior to any initialization transmission, a general message transmission for the uninitialized user must be executed.

Following an initialization transmission, to complete a user create transaction, a confirmation transmission (or error transmission) must be done. If a confirmation transmission is not executed soon after the initialization transmission, the user will be active but all their certificates will be revoked by the EASM.

If an error occurs while receiving the initialization response, an error transmission is automatically executed. This causes the EASM to delete any keys/certificates that were issued to the user and return the user to the state it was in prior to the CMP transaction (setup for creation).

Parameters:

injectedCertReqInfo - information regarding the certificates that are being requested; allows the CardMS to inject information into the CMP protocol (certificate definition identifier, proof-of-possession, certificate extensions)

cardMSProtocolEncrCert - the CardMS protocol encryption certificate

Throws:

java.lang.IllegalArgumentException - if the certificate request information is not valid

EntrustPKIXCMPException - if an error occurs during the initialization transmission

initializeSelected

public void initializeSelected(java.security.PublicKey clientProtEncKey,
                      CardMSCertReqInfo[] injectedCertReqInfo)
                        throws EntrustPKIXCMPException

Executes an initialization transmission that initializes selected keys and certificates for a user; refer to initializeSelected(CardMSCertReqInfo[], X509Certificate) for more details.

Parameters:

clientProtEncKey - the CardMS client protocol encryption key

injectedCertReqInfo - information regarding the certificates that are being requested; allows the CardMS to inject information into the CMP protocol (certificate definition identifier, proof-of-possession, certificate extensions)

Throws:

java.lang.IllegalArgumentException - if the certificate request information is not valid

EntrustPKIXCMPException - if an error occurs during the initialization transmission

Since:

8.0 Patch

recoverAll

public void recoverAll(CardMSCertReqInfo[] injectedCertReqInfo,
              X509Certificate cardMSProtocolEncrCert)
                throws EntrustPKIXCMPException

Executes a recovery transmission that recovers all keys and certificates for a user.

This transmission requests/receives recovery of ALL keys/certificates for a user that has been setup for recovery. A certificate is requested for each of the certificate definitions in the user's certificate type (Encryption, Verification, ...). For certificate definitions that indicate client key generation and no backup (signing/verification key-pair generated by the CardMS and not backed-up by the EASM), a new certificate is requested. In this case, a certificate request information object MUST be provided that contains both a public key and proof of possession (when in normal mode). The certificate request information object is required to provide the actual public key being certified and to demonstrate proof of possession of the private signing key to the EASM. For certificate definitions that indicate server key generation or backup (encryption/decryption key-pair backed-up by the EASM), certificate request information is not required; these keys/certificates are always automatically requested.

Proof of possession of a private signing key is demonstrated to the EASM by sending a POPOSigningKey structure in the request. It contains a signature over a known value, a POPOSigningKeyInput structure, using the corresponding private signing key. Since the private signing key is always generated by the CardMS and never leaves the CardMS, the CardMS must generate the POPOSigningKey. To make this process as easy as possible for the CardMS, an API is provided to generate the POPOSigningKeyInput structure, generatePOPOSigningKeyInput(PublicKey, AuthorizationCode). This structure contains a password based MAC (using the authorization code) of the public key. Proof of possession is not required using PKIX-CMP in AA mode; however, if provided it will be checked and enforced.

Following this transmission, the user's digital identity has been recovered and must be written by the CardMS. The software representation of the user's Entrust digital identity can be retrieved using the getDigitalIdRepresentation(SecureStringBuffer) or getMscapiDigitalIdRepresentation() API.

Any private keys that are generated by the EASM or returned from backup will be returned in the Entrust digital identity representation in protected format. They will exist as an EncryptedValue structure; this contains the user's private key encrypted using the CardMS client protocol encryption certificate that was specified. The CardMS must handle decrypting and extracting the private key from this protected format.

A recovery transmission requires information received during a General Message transmission. Thus, prior to any recovery transmission, a General Message transmission for the uninitialized user must be executed.

Following a recovery transmission, to complete a user recover transaction, a confirmation transmission (or error transmission) must be done. If a confirmation transmission is not executed soon after the recovery transmission, the user will be active but all their certificates will be revoked by the EASM.

If an error occurs while receiving the recovery response, an error transmission is automatically executed. This causes the EASM to delete any keys/certificates that were issued to the user and return the user to the state it was in prior to the CMP transaction (setup for recovery).

Parameters:

injectedCertReqInfo - information regarding the certificates that are being requested; allows the CardMS to inject information into the CMP protocol (certificate definition identifier, proof-of-possession, certificate extensions)

clientProtEncKey - the CardMS client protocol encryption key

Throws:

java.lang.IllegalArgumentException - if the certificate request information is not valid

EntrustPKIXCMPException - if an error occurs during the recovery transmission

recoverAll

public void recoverAll(java.security.PublicKey clientProtEncKey,
              CardMSCertReqInfo[] injectedCertReqInfo)
                throws EntrustPKIXCMPException

Executes a recovery transmission that recovers all keys and certificates for a user; refer to recoverAll(CardMSCertReqInfo[], X509Certificate) for more details.

Parameters:

clientProtEncKey - the CardMS client protocol encryption key

injectedCertReqInfo - information regarding the certificates that are being requested; allows the CardMS to inject information into the CMP protocol (certificate definition identifier, proof-of-possession, certificate extensions)

Throws:

java.lang.IllegalArgumentException - if the certificate request information is not valid

EntrustPKIXCMPException - if an error occurs during the recovery transmission

Since:

8.0 Patch

recoverSelected

public void recoverSelected(CardMSCertReqInfo[] injectedCertReqInfo,
                   X509Certificate cardMSProtocolEncrCert)
                     throws EntrustPKIXCMPException

Executes a recovery transmission that recovers selected keys and certificates for a user.

This transmission requests/receives recovery of SELECTED keys/certificates for a user that has been setup for recovery. A certificate is requested for each of the certificate definitions in the user's certificate type (Encryption, Verification, ...) for which a corresponding certificate request information object is provided. For certificate definitions that indicate client key generation and no backup (signing/verification key-pair generated by the CardMS and not backed-up by the EASM), a new certificate is requested. In this case, the certificate request identifies the certificate definition, provides the actual public key being certified, and demonstrates proof of possession of the private signing key to the EASM (when in normal mode). For certificate definitions that indicate server key generation or backup (encryption/decryption key-pair backed-up by the EASM), when provided, a certificate request information object MUST NOT contain either the public key or proof of possession. The certificate request information identifies the certificate definition, but does not provide the public key or proof of possession.

Proof of possession of a private signing key is demonstrated to the EASM by sending a POPOSigningKey structure in the request. It contains a signature over a known value, a POPOSigningKeyInput structure, using the corresponding private signing key. Since the private signing key is always generated by the CardMS and never leaves the CardMS, the CardMS must generate the POPOSigningKey. To make this process as easy as possible for the CardMS, an API is provided to generate the POPOSigningKeyInput structure, generatePOPOSigningKeyInput(PublicKey, AuthorizationCode). This structure contains a password based MAC (using the authorization code) of the public key. Proof of possession is not required using PKIX-CMP in AA mode; however, if provided it will be checked and enforced.

Following this transmission, the user's digital identity has been recovered and must be written by the CardMS. The software representation of the user's Entrust digital identity can be retrieved using the getDigitalIdRepresentation(SecureStringBuffer) or getMscapiDigitalIdRepresentation() API.

Any private keys that are generated by the EASM or returned from backup will be returned in the Entrust digital identity representation in protected format. They will exist as an EncryptedValue structure; this contains the user's private key encrypted using the CardMS client protocol encryption certificate that was specified. The CardMS must handle decrypting and extracting the private key from this protected format.

A recovery transmission requires information received during a General Message transmission. Thus, prior to any recovery transmission, a General Message transmission for the uninitialized user must be executed.

Following a recovery transmission, to complete a user recover transaction, a confirmation transmission (or error transmission) must be done. If a confirmation transmission is not executed soon after the recovery transmission, the user will be active but all their certificates will be revoked by the EASM.

If an error occurs while receiving the recovery response, an error transmission is automatically executed. This causes the EASM to delete any keys/certificates that were issued to the user and return the user to the state it was in prior to the CMP transaction (setup for recovery).

Parameters:

injectedCertReqInfo - information regarding the certificates that are being requested; allows the CardMS to inject information into the CMP protocol (certificate definition identifier, proof-of-possession, certificate extensions)

cardMSProtocolEncrCert - the CardMS protocol encryption certificate

Throws:

java.lang.IllegalArgumentException - if the certificate request information is not valid

EntrustPKIXCMPException - if an error occurs during the recovery transmission

recoverSelected

public void recoverSelected(java.security.PublicKey clientProtEncKey,
                   CardMSCertReqInfo[] injectedCertReqInfo)
                     throws EntrustPKIXCMPException

Executes a recovery transmission that recovers selected keys and certificates for a user; refer to recoverSelected(CardMSCertReqInfo[], X509Certificate) for more details.

Parameters:

clientProtEncKey - the CardMS client protocol encryption key

injectedCertReqInfo - information regarding the certificates that are being requested; allows the CardMS to inject information into the CMP protocol (certificate definition identifier, proof-of-possession, certificate extensions)

Throws:

java.lang.IllegalArgumentException - if the certificate request information is not valid

EntrustPKIXCMPException - if an error occurs during the recovery transmission

Since:

8.0 Patch

keyUpdateAndCertification

public void keyUpdateAndCertification(CardMSCertReqInfo[] injectedCertReqInfo,
                             X509Certificate cardMSProtocolEncrCert,
                             CardMSDigitalIDMgmtInfo digitalIdMgmtInfo)
                               throws EntrustPKIXCMPException

Executes a key update/certification transmission for a user that updates existing certificates and/or requests new certificates.

This transmission can only be executed when the CardMS API has been configured to operate in AA mode and when communicating with an EASM 7.1 SP1 or later. It requests/receives update of a user's existing certificate streams and/or certification of a user's new certificate streams. For each injected certificate request that is provided by the caller, a new certificate is requested. In an injected certificate request that corresponds to a certificate definition that indicates client key generation, the public key MUST be provided. In an injected certificate request that corresponds to a certificate definition that indicates server key generation, the public key MUST NOT be provided.

A key update/certification transmission is one component of a digital identity management operation. Digital identity management is supported in conjunction with a CardMS enabled Entrust client; currently this is only ESP 8.0. The CardMS enabled Entrust client will detect when digital identity management is necessary and notify the CardMS by passing it a CardMSDigitalIDMgmtInfo structure. This data structure will contain details regarding the management operation. It will indicate when a certificate store synchronization operation is required and when a key update/certification operation is required. When a key update/certification operation is required, it identifies each certificate stream for which update/certification is necessary and the reason why. In the case of update, it also indicates the current certificate in the certificate stream that requires the update. When the CardMS receives the digital identity management structure, it is responsible for carrying out the actions it indicates are required.

Below is an example of the steps that would be required to execute a digital identity management operation for a user setup for DN change by the EASM:

1. Receive and examine CardMSDigitalIDMgmtInfo structure which indicates that digital identity management is necessary.
2. Execute a general message transmission for the initialized user by calling generalMessage(Name).
3. Examine the CardMSDigitalIDMgmtInfo structure to see if a certificate store synchronization is necessary
4. Since the CardMSDigitalIDMgmtInfo structure indicates a certificate store synchronization operation is not necessary, move on to handling the update/certification operations.
5. Examine the CardMSDigitalIDMgmtInfo structure to see if any key update/certification operations are required.
6. Since the CardMSDigitalIDMgmtInfo structure indicates a key update operation is necessary, generate the necessary certificate requests and perform the operation by calling keyUpdateAndCertification(CardMSCertReqInfo[], X509Certificate, CardMSDigitalIDMgmtInfo) .
7. Retrieve the digital identity representation by calling getMscapiDigitalIdRepresentation() and write it to the smart card (this may include decrypting user private keys that were returned from the CA in encrypted format).
8. Complete the digital identity management operation by performing a confirmation transmission by calling confirmation().

Below is an example of the steps that would be required to execute a digital identity management operation for a user setup for forced key update by the EASM:

1. Receive and examine CardMSDigitalIDMgmtInfo structure which indicates that digital identity management is necessary.
2. Execute a general message transmission for the initialized user by calling generalMessage(Name).
3. Examine the CardMSDigitalIDMgmtInfo structure to see if a certificate store synchronization is necessary
4. Since the CardMSDigitalIDMgmtInfo structure indicates a certificate store synchronization operation is necessary, begin it by calling certStoreSynch(X509Certificate, CardMSDigitalIDMgmtInfo) .
5. Complete the certificate store synchronization operation by performing a confirmation transmission by calling confirmation().
6. Examine the CardMSDigitalIDMgmtInfo structure again to see if any key update/certification operations are still required (some may have been addressed by the certificate store synchronization operation).
7. Since the CardMSDigitalIDMgmtInfo structure indicates a key update operation is necessary, generate the necessary certificate requests and perform the operation by calling keyUpdateAndCertification(CardMSCertReqInfo[], X509Certificate, CardMSDigitalIDMgmtInfo) .
8. Retrieve the digital identity representation by calling getMscapiDigitalIdRepresentation() and write it to the smart card (this may include decrypting user private keys that were returned from the CA in encrypted format).
9. Complete the digital identity management operation by performing a confirmation transmission by calling confirmation().

Following this transmission, the additions to the user's digital identity must be written to the smart card by the CardMS. The software representation of the user's Entrust digital identity can be retrieved using the getMscapiDigitalIdRepresentation() API (management is only supported for Entrust MS-CAPI digital identities).

Any private keys that are generated by the EASM will be returned in the Entrust digital identity representation in protected format. They will exist as an EncryptedValue structure; this contains the user's private key encrypted using the CardMS client protocol encryption certificate that was specified. The CardMS must handle decrypting and extracting the private key from this protected format.

A key update/certification transmission requires information received during a general message transmission. Thus, prior to any key update/certification transmission, a general message transmission for the initialized user must be executed.

Following a key update/certification transmission, to complete the management transaction, a confirmation transmission (or error transmission) must be done. If a confirmation transmission is not executed soon after the key update/certification transmission, the user will be active but all the certificates that were requested will be revoked by the EASM.

If an error occurs while receiving the key update/certification response, an error transmission is automatically executed. This causes the EASM to delete any keys/certificates that were issued to the user and leave the user in the active state.

Parameters:

injectedCertReqInfo - information regarding the certificates that are being requested; allows the CardMS to inject information into the CMP protocol (certificate definition identifier, public key, certificate extensions)

cardMSProtocolEncrCert - the CardMS protocol encryption certificate

digitalIdMgmtInfo - digital identity management information; indicates what type of key management operations are necessary and provides information about the keys and certificates that currently exist in the user's digital identity

Throws:

EntrustPKIXCMPException - if an error occurs during the key update/certification transmission

java.lang.IllegalArgumentException - if any of the parameters contain invalid values

java.lang.IllegalStateException - if a general message transaction for an initialized user has not yet been successfully completed

keyUpdateAndCertification

public void keyUpdateAndCertification(java.security.PublicKey clientProtEncKey,
                             CardMSCertReqInfo[] injectedCertReqInfo,
                             CardMSDigitalIDMgmtInfo digitalIdMgmtInfo)
                               throws EntrustPKIXCMPException

Executes a key update/certification transmission for a user that updates existing certificates and/or requests new certificates; refer to keyUpdateAndCertification(CardMSCertReqInfo[], X509Certificate, CardMSDigitalIDMgmtInfo) for more details.

Parameters:

clientProtEncKey - the CardMS client protocol encryption key

injectedCertReqInfo - information regarding the certificates that are being requested; allows the CardMS to inject information into the CMP protocol (certificate definition identifier, public key, certificate extensions)

digitalIdMgmtInfo - digital identity management information; indicates what type of key management operations are necessary and provides information about the keys and certificates that currently exist in the user's digital identity

Throws:

EntrustPKIXCMPException - if an error occurs during the key update/certification transmission

java.lang.IllegalArgumentException - if any of the parameters contain invalid values

java.lang.IllegalStateException - if a general message transaction for an initialized user has not yet been successfully completed

Since:

8.0 Patch

certStoreSynch

public void certStoreSynch(X509Certificate cardMSProtocolEncrCert,
                  CardMSDigitalIDMgmtInfo digitalIdMgmtInfo)
                    throws EntrustPKIXCMPException

Executes a certificate store synchronization transmission that requests all backed up user keys and certificates from the server.

This transmission can only be executed when the CardMS API has been configured to operate in AA mode and when communicating with an EASM 7.1 SP1 or later. It requests/receives all of a user's keys/certificates that are backed up at the server. A certificate store synchronization operation is required when the CA has one or more newer keys/certificates for the user than exist in their digital identity. This most commonly occurs during a CA forced key update operation; setting up a user for a CA forced key update operation causes the CA to issue a new key/certificate for each certificate stream for which the key is server generated. It is also possible for a certificate store synchronization operation to be necessary when two copies of the digital identity exist (can happen with key recovery), and a key update is done using one; at this point the other copy of the digital identity is out of synch. A certificate store synchronization operation is addressed by executing a PKIX-CMP signed key recovery operation.

A certificate store synchronization transmission is one component of a digital identity management operation. Digital identity management is supported in conjunction with a CardMS enabled Entrust client; currently this is only ESP 8.0. The CardMS enabled Entrust client will detect when digital identity management is necessary and notify the CardMS by passing it a CardMSDigitalIDMgmtInfo structure. This data structure will contain details regarding the management operation. It will indicate when a certificate store synchronization operation is required and when a key update/certification operation is required. When a key update/certification operation is required, it identifies each certificate stream for which update/certification is necessary and the reason why. In the case of update, it also indicates the current certificate in the certificate stream that requires the update. When the CardMS receives the digital identity management structure, it is responsible for carrying out the actions it indicates are required.

Below is an example of the steps that would be required to execute a digital identity management operation for a user setup for forced key update by the EASM:

1. Receive and examine CardMSDigitalIDMgmtInfo structure which indicates that digital identity management is necessary.
2. Execute a general message transmission for the initialized user by calling generalMessage(Name).
3. Examine the CardMSDigitalIDMgmtInfo structure to see if a certificate store synchronization is necessary
4. Since the CardMSDigitalIDMgmtInfo structure indicates a certificate store synchronization operation is necessary, begin it by calling certStoreSynch(X509Certificate, CardMSDigitalIDMgmtInfo) .
5. Complete the certificate store synchronization operation by performing a confirmation transmission by calling confirmation().
6. Examine the CardMSDigitalIDMgmtInfo structure again to see if any key update/certification operations are still required (some may have been addressed by the certificate store synchronization operation).
7. Since the CardMSDigitalIDMgmtInfo structure indicates a key update operation is necessary, generate the necessary certificate requests and begin the the operation by calling keyUpdateAndCertification(CardMSCertReqInfo[], X509Certificate, CardMSDigitalIDMgmtInfo) .
8. Retrieve the digital identity representation by calling getMscapiDigitalIdRepresentation() and write it to the smart card (this may include decrypting user private keys that were returned from the CA in encrypted format).
9. Complete the digital identity management operation by performing a confirmation transmission by calling confirmation().

Following this transmission, the additions to the user's digital identity must be written to the smart card by the CardMS. The software representation of the user's Entrust digital identity can be retrieved using the getMscapiDigitalIdRepresentation() API (management is only supported for Entrust MS-CAPI digital identities).

Any private keys that are backed up by the EASM will be returned in the Entrust digital identity representation in protected format. They will exist as an EncryptedValue structure; this contains the user's private key encrypted using the CardMS client protocol encryption public key that was specified. The CardMS must handle decrypting and extracting the private key from this protected format.

A certificate store synchronization transmission requires information received during a general message transmission. Thus, prior to any certificate store synchronization transmission, a general message transmission for the initialized user must be executed.

Following a certificate store synchronization transmission, to complete the management transaction, a confirmation transmission (or error transmission) must be done. If a confirmation transmission is not executed soon after the key update/certification transmission, the user will be active but all the certificates that were requested will be revoked by the EASM.

If an error occurs while receiving the key update/certification response, an error transmission is automatically executed. This causes the EASM to leave the user in the active state.

Parameters:

cardMSProtocolEncrCert - the CardMS protocol encryption certificate

digitalIdMgmtInfo - digital identity management information; indicates what type of key management operations are necessary and provides information about the keys and certificates that currently exist in the user's digital identity

Throws:

EntrustPKIXCMPException - if an error occurs during the Certificate Store Synchronization transmission

java.lang.IllegalArgumentException - if any of the parameters contain invalid values

java.lang.IllegalStateException - if a general message transaction for an initialized user has not yet been successfully completed

certStoreSynch

public void certStoreSynch(CardMSDigitalIDMgmtInfo digitalIdMgmtInfo,
                  java.security.PublicKey clientProtEncKey)
                    throws EntrustPKIXCMPException

Executes a certificate store synchronization transmission that requests all backed up user keys and certificates from the server; refer to certStoreSynch(X509Certificate, CardMSDigitalIDMgmtInfo) for more details.

Parameters:

digitalIdMgmtInfo - digital identity management information; indicates what type of key management operations are necessary and provides information about the keys and certificates that currently exist in the user's digital identity

clientProtEncKey - the CardMS client protocol encryption key

Throws:

EntrustPKIXCMPException - if an error occurs during the Certificate Store Synchronization transmission

java.lang.IllegalArgumentException - if any of the parameters contain invalid values

java.lang.IllegalStateException - if a general message transaction for an initialized user has not yet been successfully completed

Since:

8.0 Patch

confirmation

public void confirmation()
                  throws EntrustPKIXCMPException

Executes a confirmation transmission.

This transmission indicates successful completion of a certificate management (initialization, recovery, certificate store synchronization, key update/certification) transaction with the EASM. This API must be called by the CardMS once it has completed the certificate management transmission and successfully written the user's Entrust digital identity to the card.

The EASM will be listening on the connection for a confirmation message. If it does not receive confirmation soon after the certificate management transmission, then the certificates that were issued during the transmission will automatically be revoked. Once the confirmation message has been sent an attempt to receive a TCP-level negPollRep message is made. The negPollRep message provides an assurance that the Security Manager successfully received the confirmation message (and thus has not revoked the requested user certificates). Successful completion of this API indicates that the EASM has received the confirmation message.

If an error occurs while attempting to send the confirmation message, an attempt is automatically made to send an error message to the EASM. This causes the EASM to delete any keys/certificates that were issued to the user and return the user to the state it was in prior to the CMP transaction.

IMPORTANT: It is strongly recommended that the confirmation transmission be executed within a few seconds of the certificate management transmission. From the time that the certificate management transmission is started until the confirmation transmission has completed, one of the CMP processes at the EASM is reserved and dedicated to handling this transaction (i.e. it cannot serve any other clients). Completing each certificate management transaction as quickly as possible optimizes the EASM PKIX-CMP transaction throughput.

Throws:

EntrustPKIXCMPException - if an error occurs during the confirmation transmission

error

public void error(java.lang.String errorMessage)

Executes an error transmission.

This transmission indicates unsuccessful completion of a certificate management (initialization, recovery, certificate store synchronization, key update/certification) transaction with the EASM. This API must be called by the CardMS when it encounters an error while attempting to write the Entrust digital identity to the card. This causes the EASM to delete any keys/certificates that were issued to the user and return the user to the state it was in prior to the CMP transaction.

Parameters:

errorMessage - a text message describing the error that occurred

generatePOPOSigningKeyInput

public POPOSigningKeyInput generatePOPOSigningKeyInput(java.security.PublicKey publicKey,
                                              AuthorizationCode authCode)

Generates a POPOSigningKeyInput structure appropriate for use in demonstrating proof of possession of a private signing key.

Proof of possession of a private signing key is demonstrated to the EASM by signing a known structure, which the EASM can verify using the corresponding public verification key. For demonstrating proof of possession during an initialization or recovery transmission, the POPOSigningKeyInput structure must contain a password based MAC (using the authorization code) of the public verification key. This method takes care of appropriately calculating the password based MAC.

Once the POPOSigningKeyInput structure has been generated, the CardMS must create a signature over it's DER encoded ASN.1 representation. The DER encoding can be done as follows:

 POPOSigningKeyInput popoSigningKeyInput = generatePOPOSigningKeyInput(verificationKey, authCode);
 DerCoder.encode(popoSigningKeyInput.toASN1Object());
 

After the signature has been calculated, the CardMS must create a POPOSigningKey structure that will be included in the injected key information.

Parameters:

publicKey - the public verification key that corresponds to the private signing key

authCode - the user's authorization code (issued by the EASM with the user is setup for creation/recovery)

Returns:

a POPOSigningKeyInput structure

generatePKIArchiveOptionsForClientGenBackup

public PKIArchiveOptions generatePKIArchiveOptionsForClientGenBackup(java.security.PrivateKey privateKey)
                                                              throws EntrustPKIXCMPException

Generates a PKIArchiveOptions structure representing a client generated private key that is to be backed up by the Certification Authority.

The symmetric protocol encryption algorithm used is selected from the user's policy settings; the first suitable algorithm from this list will be used to protect the payload.

Parameters:

privateKey - a client generated private key

Returns:

PKIArchiveOptions structure

Throws:

EntrustPKIXCMPException - if an error occurs while attempting to encrypt the client generated private key

java.lang.IllegalStateException - if a General Message transaction has not been completed yet

Since:

8.0 Patch

getClientSettings

public ClientSettings getClientSettings()

Returns the client policy information that was retrieved during a previous general message transmission.

Client policy information contains the main and role policy certificates and their associated policy settings. These settings provide information regarding the EASM configuration and the user's role.

The CardMS may not find any of this information useful; it is made available for completeness.

Returns:

the client policy information

getCertPolicySettings

public EntrustCertTypeSettings getCertPolicySettings()

Returns the certificate policy information that was retrieved during a previous general message transmission.

Certificate policy information contains both certificate type and certificate definition policy certificates and their associated policy settings. These settings provide information regarding each of the user's certificate streams (initial key/certificate pairs).

The certificate policy information will contain a certificate definition and associated policy (certificate definition settings) for each of the user's key pairs. The following certificate definition settings may be useful to the CardMS (for information on each policy setting, follow the link):

Key Type

EntrustCertDefnSettings.getKeyType()

Key Backup

EntrustCertDefnSettings.isKeyBackup()

Key Client Generated

EntrustCertDefnSettings.isKeyClientGen()

Key Usage

EntrustCertDefnSettings.getKeyUsage()

The CardMS can access the certificate definition settings as follows:

 // At this point the 'cmpForCardMS' object has completed a general message
 // transmission
 EntrustCertTypeSettings certPolicySettings = cmpForCardMS.getCertPolicySettings();
 Iterator iterator = certPolicySettings.getCertdefns();
 while (iterator.hasNext())
 {
     EntrustCertDefnSettings certDefnSettings = (EntrustCertDefnSettings) iterator.next();
 
     // Access the certificate definition identifier
     EntrustCertInfoId certDefnId = certDefnSettings.getCertdefn();
 
     // Determine the key/certificate type
     String keyType = certDefnSettings.getKeyType();
 
     // Determine whether the key/certificate is backed-up at the EASM
     boolean keyBackup = certDefnSettings.isKeyBackup();
 
     // Determine whether the key is to be generated by the CardMS or the EASM
     boolean keyClientGen = certDefnSettings.isKeyClientGen();
 
     // Determine the key usage (encryption, verification)
     String keyUsage = certDefnSettings.getKeyUsage();
 
     // At this point, the CardMS can use this policy information to determine
     // the keys it must generate and inject in a following initialization
     // or recovery transmission 
 }
 

Returns:

the certificate policy information

generateClientProtlEncKeys

public java.security.KeyPair generateClientProtlEncKeys(boolean keyRecovery,
                                               java.util.Iterator<? extends EntrustPKIXCMPInjectedCertReqInfo> certificateRequests)
                                                 throws EntrustPKIXCMPException

Generates the client protocol encryption key pair in software.

The protocol encryption key type is selected appropriately based on policy and the type of operation being performed (key recovery, other).

Parameters:

keyRecovery - indicates the PKIX-CMP operation is a 'key recovery'

certificateRequests - the certificate requests being sent in the PKIX-CMP operation

Returns:

the client protocol encryption key pair; null if a protocol encryption key pair is not required (client private keys are not being returned to the client from the server)

Throws:

EntrustPKIXCMPException - if an error occurred while generating the client protocol encryption key pair

Since:

8.0 Patch

getUserState

public EntrustState getUserState()

Returns the user's current state.

If a General Message transaction has not been done yet, or the communication is not being done with an Entrust Security Manager 7.0 or later, null is returned.

Returns:

the user's state

Since:

8.0 Patch

getDigitalIdRepresentation

public P11StorageObject[] getDigitalIdRepresentation(SecureStringBuffer password)

Returns a representation of an Entrust digital identity in Entrust PKCS #11 format.

This allows the CardMS to obtain a representation of the Entrust digital identity in PKCS #11 format so that it can write this digital identity to a smart card. This must be done following an initialization or recovery transmission, but before the confirmation (or error) transmission. The digital identity returned will correspond to the user the CMP transaction is being executed for.

This representation specifies all the PKCS #11 objects that must be written to the smart card; each of the individual object attributes is specified. These objects must be created on the smart card exactly as specified in this software representation. For more information on how each PKCS #11 object should be written to the smart card, please refer to the individual PKCS #11 storage object implementations:

• P11DataObject
• P11X509CertificateObject
• P11PrivateKeyObject

The representation of the Entrust digital identity in PKCS #11 format that is returned will be composed entirely of these objects.

The user's password is used to create a password history. When this digital identity is used by certain Entrust applications, the password history can be used to ensure passwords are not reused and notify/enforce when password change is necessary (controlled by policy). The password history is not required, but is a recommended component of an Entrust digital identity.

Parameters:

password - the user's password; the password that will protect the digital identity once stored on the smart card (OPTIONAL)

Returns:

a representation of the digital identity in Entrust PKCS #11 format

getMscapiDigitalIdRepresentation

public MscapiKeyContainer[] getMscapiDigitalIdRepresentation()

Returns a representation of an Entrust digital identity in Entrust MS-CAPI format.

This allows the CardMS to obtain a representation of the Entrust digital identity in MS-CAPI format so that it can write this digital identity to a smart card. This must be done following a certificate management (initialization, recovery, certificate store synchronization, key update/certification) transmission, but before the confirmation (or error) transmission. The digital identity returned will correspond to the user the CMP transaction is being executed for.

This representation specifies all the MS-CAPI key containers that must be written to MS-CAPI (and propagated to the smart card). These key containers must be created in MS-CAPI exactly as specified in this software representation. For more information on how each MS-CAPI object should be written, please refer to documentation of the MS-CAPI key container representation MscapiKeyContainer.

Following an initialization or recovery operation, the digital identity representation will contain all key containers that make up the user's digital identity (complete identity). Following a key update/certification or certificate store synchronization operation, the digital identity representation will contain only key containers that represent the keys/certificates received during that particular operation (partial identity).

Returns:

a representation of the digital identity in Entrust MS-CAPI format