com.entrust.toolkit.credentials

Class PKIXCMPUtils

java.lang.Object

com.entrust.toolkit.credentials.PKIXCMPUtils

public class PKIXCMPUtils
extends java.lang.Object

Constructor Summary

Constructors

Constructor and Description
PKIXCMPUtils(ManagerTransport mantransport) Construct an EntrustPKIXCMP message given a ManagerTransport object.
PKIXCMPUtils(ManagerTransport mantransport, boolean silentErrorFlag) Construct an EntrustPKIXCMP message given a ManagerTransport object.

Method Summary

Modifier and Type	Method and Description
static byte[]	createCmpRfc4210PasswordBasedMac(byte[] data, byte[] password, AlgorithmID passwordBasedMac) Creates a password based MAC over the specified data using an RFC 4210 section 5.1.3.1 compliant hasher.
static byte[]	createPasswordBasedMac(byte[] data, byte[] password, AlgorithmID passwordBasedMac) Creates a password based MAC over the specified data using an RFC 4210 section 5.1.3.1 compliant hasher if using hmacs, and using the EntrustPBKDF hasher if using a CBC-MAC algorithm.
GeneralMessageInfo	getGeneralMessageInfo(SecureStringBuffer refNum, AuthorizationCode authCode) This API performs a PKIX general message transaction using the supplied reference number and authorization code.
GeneralMessageInfo	getGeneralMessageInfo(User user) This API performs a PKIX general message transaction using the supplied User object.
GeneralMessageInfo	getGeneralMessageInfo(X509Certificate verificationCert, ValidationInfo certVerifier) This API performs a PKIX general message transaction using the supplied user's verification certificate.
GeneralMessageInfo	getGeneralMessageInfo(X509Certificate verificationCert, ValidationInfo certVerifier, EntrustEventIdentifier eventIdentifier) This API performs a PKIX general message transaction using the supplied user's verification certificate.
GeneralMessageInfo	getGeneralMessageInfoWithV2Upgrade(SecureStringBuffer refNum, AuthorizationCode authCode) This API performs a PKIX general message transaction using the supplied reference number and authorization code.
PKIMessage	receive() Receives a PKIX-CMP response message over the Manager Transport.
void	send(PKIMessage request) Sends a PKIX-CMP request over the Manager Transport.
void	setApplicationName(java.lang.String applicationName) Sets the application name to use in PKIHeader.

Methods inherited from class java.lang.Object

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

Constructor Detail

PKIXCMPUtils

public PKIXCMPUtils(ManagerTransport mantransport)

Construct an EntrustPKIXCMP message given a ManagerTransport object. This method will create an Entrust70PKIXCMPv1 object suitable for sending and receiving PKIX messages.

Parameters:

mantransport -

PKIXCMPUtils

public PKIXCMPUtils(ManagerTransport mantransport,
                    boolean silentErrorFlag)

Construct an EntrustPKIXCMP message given a ManagerTransport object. This method will create an Entrust70PKIXCMPv1 object suitable for sending and receiving PKIX messages.

Parameters:

mantransport -

silentErrorFlag - Enable/disable silent error mode on protocol version errors in the Security Manager log. Set silentErrorFlag to 'true' to not showing the protocol version related errors: (-02548,-01685, and -11092) in the log.

Method Detail

send

public void send(PKIMessage request)
          throws EntrustPKIXCMPException

Sends a PKIX-CMP request over the Manager Transport. This is done as follows:

• DER encode the request message
• Create a TCP message by adding a TCP header to the DER encoded request message
• Send the TCP request message over the ManagerTransport

If this class has been set to operate in DEBUG mode, a file containing the DER encoded request message will be written to the working directory.

Parameters:

request - the request message to be sent to the CA

Throws:

EntrustPKIXCMPException - thrown if there was a problem sending the PKIX-CMP request

receive

public PKIMessage receive()
                   throws EntrustPKIXCMPException

Receives a PKIX-CMP response message over the Manager Transport. This is done as follows:

• Receive a TCP response message over the ManagerTransport
• Remove the TCP header creating a DER encoded response message
• DER decode the response message to a PKIMessage

If this class has been set to operate in DEBUG mode, a file containing the DER encoded response message will be written to the working directory.

Returns:

PKIMessage the response message received from the CA

Throws:

EntrustPKIXCMPException - thrown if there was a problem receiving the PKIX-CMP response

getGeneralMessageInfo

public GeneralMessageInfo getGeneralMessageInfo(SecureStringBuffer refNum,
                                                AuthorizationCode authCode)
                                         throws EntrustPKIXCMPException

This API performs a PKIX general message transaction using the supplied reference number and authorization code. It can be used for a user that has not yet been created and is in the 'added' stated at the Entrust CA. This method returns a GeneralMessageInfo object whose purpose is to encapsulate information contained in a PKIX CMP General Message.

Note: If this API is called by a V2 key pair user, the manager log at the PKI may generate an error that says "A V1 client can no longer be used to manage user". This error message can be ignored.

Parameters:

refNum - The reference number

authCode - The authorization code

Returns:

The GeneralMessageInfo object that encapsulated PKIX GeneralMessage Information

Throws:

EntrustPKIXCMPException

Since:

8.0

getGeneralMessageInfoWithV2Upgrade

public GeneralMessageInfo getGeneralMessageInfoWithV2Upgrade(SecureStringBuffer refNum,
                                                             AuthorizationCode authCode)
                                                      throws EntrustPKIXCMPException

This API performs a PKIX general message transaction using the supplied reference number and authorization code. It can be used for a user that has not yet been created and is in the 'added' stated at the Entrust CA. This method returns a GeneralMessageInfo object whose purpose is to encapsulate information contained in a PKIX CMP General Message.

Warning: If this API is called by a V1 key pair user, the user will be automatically upgraded to a V2 key pair user. This V1 key pair to V2 keypair upgrade operation cannot be undone by the toolkit. An administrator will be required to perform an operation at the CA to undo this operation if a V1 to V2 keypair upgrade was not intended. Therefore, this method should only be called by users that require V2 keypair information such as certificate definition policy information.

Parameters:

refNum - The reference number

authCode - The authorization code

Returns:

The GeneralMessageInfo object that encapsulated PKIX GeneralMessage Information

Throws:

EntrustPKIXCMPException

Since:

9.0

getGeneralMessageInfo

public GeneralMessageInfo getGeneralMessageInfo(User user)
                                         throws EntrustPKIXCMPException,
                                                UserNotLoggedInException

This API performs a PKIX general message transaction using the supplied User object. This method returns a GeneralMessageInfo object whose purpose is to encapsulate information contained in a PKIX CMP General Message.

Parameters:

user - The User object

Returns:

The GeneralMessageInfo object that encapsulated PKIX GeneralMessage Information

Throws:

EntrustPKIXCMPException

UserNotLoggedInException

Since:

8.0 patch

getGeneralMessageInfo

public GeneralMessageInfo getGeneralMessageInfo(X509Certificate verificationCert,
                                                ValidationInfo certVerifier,
                                                EntrustEventIdentifier eventIdentifier)
                                         throws EntrustPKIXCMPException

This API performs a PKIX general message transaction using the supplied user's verification certificate. It also requires a configured CertVerifier object so that the response from the general message request can be verified (it is signed by the PKI). Note: This API only works with V2-keypair users. It does not work with V1Keypair users.

Parameters:

verificationCert - The user's verification certificate used to calculate the protection on the PKIX-CMP message

certVerifier - The Certificate verifier used to verify the response from the CA. This certVerifier should be configured to trust the CA which is signing the response.

eventIdentifier - The event identifier assigned to the user (not required for communication with a pre-7.0 Security Manager). This parameter is required when the user has completed a DN change in the CA, but the verificationCert being passed in here is still for the old DN. In this case, the eventIdentifier is the only link (in Security Manager) that ties the old DN (which is contained in the previous/old certificate) to the new DN entry in the CA. Otherwise, without the eventIdentifier, an "uninitialized user" error (which means the specified DN entry was not found) will be returned. (Can be null otherwise, if the verificationCert being passed in is the most recent certificate or contains the current DN.)

Returns:

The GeneralMessageInfo object that encapsulated PKIX GeneralMessage Information

Throws:

EntrustPKIXCMPException

Since:

9.0

getGeneralMessageInfo

public GeneralMessageInfo getGeneralMessageInfo(X509Certificate verificationCert,
                                                ValidationInfo certVerifier)
                                         throws EntrustPKIXCMPException

This API performs a PKIX general message transaction using the supplied user's verification certificate. It also requires a configured CertVerifier object so that the response from the general message request can be verified (it is signed by the PKI). Note: This API only works with V2-keypair users. It does not work with V1Keypair users.

Parameters:

verificationCert - The user's verification certificate used to calculate the protection on the PKIX-CMP message

certVerifier - The Certificate verifier used to verify the response from the CA. This certVerifier should be configured to trust the CA which is signing the response.

Returns:

The GeneralMessageInfo object that encapsulated PKIX GeneralMessage Information

Throws:

EntrustPKIXCMPException

Since:

9.0

createPasswordBasedMac

public static byte[] createPasswordBasedMac(byte[] data,
                                            byte[] password,
                                            AlgorithmID passwordBasedMac)
                                     throws EntrustPKIXCMPException

Creates a password based MAC over the specified data using an RFC 4210 section 5.1.3.1 compliant hasher if using hmacs, and using the EntrustPBKDF hasher if using a CBC-MAC algorithm.

The MAC is calculated as a PasswordBasedMac with the salt, iteration count, one-way function algorithm, and MAC algorithm all extracted from the algorithm parameters. The password used is created from the authorization code provided.

First a key is created by appending the salt to the password and hashing this value with the one-way function the number of times specified in iteration count. Then the MAC using this key and the specified MAC algorithm.

Parameters:

data - the data to protect with the password based MAC

password - the password to MAC with (authorization code, ...)

passwordBasedMac - the password based MAC algorithm identifier that the MAC will be created for

Returns:

the MAC value

Throws:

EntrustPKIXCMPException - if an error occurs during MAC creation

createCmpRfc4210PasswordBasedMac

public static byte[] createCmpRfc4210PasswordBasedMac(byte[] data,
                                                      byte[] password,
                                                      AlgorithmID passwordBasedMac)
                                               throws EntrustPKIXCMPException

Creates a password based MAC over the specified data using an RFC 4210 section 5.1.3.1 compliant hasher. This function should not be used if communicating directly with SM/ECA using a CBC-MAC algorithm (e.g. DESEDE, DES, CAST). This function is intended to be used for validating the MAC protection on CMP messages from 3rd party CMP clients.

The MAC is calculated as a PasswordBasedMac with the salt, iteration count, one-way function algorithm, and MAC algorithm all extracted from the algorithm parameters. The password used is created from the authorization code provided.

First a key is created by appending the salt to the password and hashing this value with the one-way function the number of times specified in iteration count. Then the MAC using this key and the specified MAC algorithm.

Parameters:

data - the data to protect with the password based MAC

password - the password to MAC with (authorization code, ...)

passwordBasedMac - the password based MAC algorithm identifier that the MAC will be created for. It must be one of: AlgorithmID.MacAlgs.id_hmacWithSHA256, AlgorithmID.MacAlgs.id_hmacWithSHA384, AlgorithmID.MacAlgs.id_hmacWithSHA512, AlgorithmID.MacAlgs.dod_hmacWithSHA1, AlgorithmID.MacAlgs.cast5MAC, AlgorithmID.MacAlgs.desEDEMAC, & AlgorithmID.MacAlgs.desMAC

Returns:

the MAC value

Throws:

EntrustPKIXCMPException - if an error occurs during MAC creation including use of an invalid passwordBasedMac algorithm

setApplicationName

public void setApplicationName(java.lang.String applicationName)

Sets the application name to use in PKIHeader.

Parameters:

applicationName - application name shown in ECA logs

Since:

9.0