com.entrust.toolkit.credentials

Class TokenCredentialRecoverer

java.lang.Object

com.entrust.toolkit.credentials.CredentialReader

com.entrust.toolkit.credentials.CMPCredentialReader

com.entrust.toolkit.credentials.CMPTokenCredentialReader

com.entrust.toolkit.credentials.TokenCredentialRecoverer

public final class TokenCredentialRecoverer
extends CMPTokenCredentialReader

This credential reader is designed for recovering an Entrust user's Digital Identity on a PKCS#11 device (token).

All communication with the token is done using the PKCS#11 version 2.01 API. All communication with the Entrust Security Manager is done using the PKIX-CMP protocol.

Recovering a Digital Identity involves generating all client generated key pairs on the token, requesting all server generated key pairs from the Security Manager, and securely storing all Digital Identity information on the token.

When recovering a Digital Identity, the user must have a connection to the Security Manager and Directory set, and must have a credential writer set. The only credential writer that can be used with this credential reader is a TokenWriter. Below is an example of how a user's Digital Identity can be recovered (all capitalized values must be provided by the user):

 User user = new User();
 
 JNDIDirectory directory = new JNDIDirectory(DIRECTORY_IP, DIRECTORY_PORT);
 ManagerTransport transport = new ManagerTransport(MANAGER_IP, MANAGER_PORT);
 user.setConnections(directory, transport);

 PKCS11LibraryConnection p11LibConn = new PKCS11LibraryConnection(P11_LIB);
 long slotId = new PKCS11Information(p11LibConn).getSlotList(true).getSlotIDs()[0];

 SecureStringBuffer secureRefNum = new SecureStringBuffer(REF_NUM);
 AuthorizationCode secureAuthCode = new AuthorizationCode(AUTH_CODE);
 SecureStringBuffer securePassword = new SecureStringBuffer(PASSWORD);
 CredentialReader credentialReader = new TokenCredentialRecoverer(secureRefNum, secureAuthCode, slotId, p11LibConn);
 CredentialWriter credentialWriter = new TokenWriter(ENTRUST_PATH, ENTRUST_USER);
 user.setCredentialWriter(credentialWriter);
 user.login(credentialReader, securePassword);
 

Field Summary

Fields inherited from class com.entrust.toolkit.credentials.CMPCredentialReader

DSASignature, ECDSASignature, PKIX4Version, PKIX5Version, RSASignature

Constructor Summary

Constructors

Constructor and Description
TokenCredentialRecoverer(SecureStringBuffer referenceNumber, AuthorizationCode authorizationCode, int signingKeyAlgorithm, int signingKeyStrength, int pkixVersion, long slotId, PKCS11LibraryConnection pkcs11LibraryConnection, SecureStringBuffer currentSoPin, SecureStringBuffer newSoPin) Deprecated. this constructor contains obsolete parameters; use another constructor that does not
TokenCredentialRecoverer(SecureStringBuffer referenceNumber, AuthorizationCode authorizationCode, int signingKeyAlgorithm, int signingKeyStrength, int pkixVersion, long slotId, PKCS11LibraryConnection pkcs11LibraryConnection, SecureStringBuffer soPin, java.lang.String label) Deprecated. this constructor contains obsolete parameters; use another constructor that does not
TokenCredentialRecoverer(SecureStringBuffer referenceNumber, AuthorizationCode authorizationCode, long slotId, PKCS11LibraryConnection pkcs11LibraryConnection) A constructor; create a new TokenCredentialRecoverer object configured for use with a PKCS#11 device that has already been initialized.
TokenCredentialRecoverer(SecureStringBuffer referenceNumber, AuthorizationCode authorizationCode, long slotId, PKCS11LibraryConnection pkcs11LibraryConnection, SecureStringBuffer currentSoPin, SecureStringBuffer newSoPin) A constructor; create a new TokenCredentialRecoverer object configured for use with a PKCS#11 device that has already been initialized and allows Security Officer PIN change.
TokenCredentialRecoverer(SecureStringBuffer referenceNumber, AuthorizationCode authorizationCode, long slotId, PKCS11LibraryConnection pkcs11LibraryConnection, SecureStringBuffer soPin, java.lang.String label) A constructor; create a new TokenCredentialRecoverer object configured for use with a PKCS#11 device that has not yet been initialized.

Method Summary

Modifier and Type	Method and Description
java.lang.String	getType() Returns the type (name) of this specific credential reader.
void	setPreserveUserKeyPairVersion(boolean preserveUserKeyPairVersion) Allows the caller to maintain the client key-pair version during a recover operation.

Methods inherited from class com.entrust.toolkit.credentials.CMPTokenCredentialReader

setDeletionMechanism

Methods inherited from class com.entrust.toolkit.credentials.CMPCredentialReader

setClientKeyGenParams, setForceV1KeyPair

Methods inherited from class com.entrust.toolkit.credentials.CredentialReader

checkPwd

Methods inherited from class java.lang.Object

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

Constructor Detail

TokenCredentialRecoverer

public TokenCredentialRecoverer(SecureStringBuffer referenceNumber,
                                AuthorizationCode authorizationCode,
                                long slotId,
                                PKCS11LibraryConnection pkcs11LibraryConnection)

A constructor; create a new TokenCredentialRecoverer object configured for use with a PKCS#11 device that has already been initialized.

This constructor should be used when the PKCS#11 device (token) that will be used to store the Digital Identity has already been set up with a Normal User. Prior to Digital Identity recovery, the token will be prepared using one of the deletion mechanisms. A deletion mechanism indicates which objects on the token must be deleted; this can be set by calling setDeletionMechanism(TokenDeletionMechanism). The default deletion mechanism will simply delete all objects created by Entrust from the token.

When the user logs in, the token located at the indicated slot ID will be connected to using the PKCS#11 library provided. The token is then prepared, which may delete some of the objects it currently contains. Next, the Normal User is logged in to the token using the user's log-on password. At this point the token is ready for the Digital Identity recover operation.

Using the reference number and authentication code, the user's Digital Identity is recovered using the PKIX-CMP protocol. Any keys that are to be client generated are generated directly on the token. All other Digital Identity information is retrieved from the Security Manager and written to the token.

Parameters:

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

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

slotId - the slot ID indicating the location on the token where the user's Digital Identity will be stored

Note

A list of slot IDs can be retrieved from the token by calling the getSlotList() method from the PKCS11Information class.

pkcs11LibraryConnection - a connection to the PKCS#11 library of the token

Throws:

java.lang.IllegalArgumentException - thrown if any of the required parameters are null

Since:

7.0

TokenCredentialRecoverer

public TokenCredentialRecoverer(SecureStringBuffer referenceNumber,
                                AuthorizationCode authorizationCode,
                                long slotId,
                                PKCS11LibraryConnection pkcs11LibraryConnection,
                                SecureStringBuffer currentSoPin,
                                SecureStringBuffer newSoPin)

A constructor; create a new TokenCredentialRecoverer object configured for use with a PKCS#11 device that has already been initialized and allows Security Officer PIN change.

This constructor should be used when the PKCS#11 device (token) that will be used to store the Digital Identity has already been set up with a Normal User. It also provides the ability to change the Security Officer PIN. Prior to Digital Identity recovery, the token will be prepared using one of the deletion mechanisms. A deletion mechanism indicates which objects on the token must be deleted; this can be set by calling setDeletionMechanism(TokenDeletionMechanism). The default deletion mechanism will simply delete all objects created by Entrust from the token.

When the user logs in, the token located at the indicated slot ID will be connected to using the PKCS#11 library provided. The token is then prepared, which may delete some of the objects it currently contains. If the current and new Security Officer PIN were provided, the PIN of the Security Officer is changed. Next, the Normal User is logged in to the token using the user's log-on password. At this point the token is ready for the Digital Identity recover operation.

Using the reference number and authentication code, the user's Digital Identity is recovered using the PKIX-CMP protocol. Any keys that are to be client generated are generated directly on the token. All other Digital Identity information is retrieved from the Security Manager and written to the token.

Parameters:

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

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

slotId - the slot ID indicating the location on the token where the user's Digital Identity will be stored

Note

A list of slot IDs can be retrieved from the token by calling the getSlotList() method from the PKCS11Information class.

pkcs11LibraryConnection - a connection to the PKCS#11 library of the token

currentSoPin - the current PIN of the Security Officer user on the token; when set (along with newSoPin) the Security Officer PIN will be changed to the new value indicated (OPTIONAL)

newSoPin - the new PIN for the Security Officer user on the token; when set (along with currentSoPin) the Security Officer PIN will be changed to this value (OPTIONAL)

Throws:

java.lang.IllegalArgumentException - thrown if any of the required parameters are null

Since:

7.0

TokenCredentialRecoverer

public TokenCredentialRecoverer(SecureStringBuffer referenceNumber,
                                AuthorizationCode authorizationCode,
                                int signingKeyAlgorithm,
                                int signingKeyStrength,
                                int pkixVersion,
                                long slotId,
                                PKCS11LibraryConnection pkcs11LibraryConnection,
                                SecureStringBuffer currentSoPin,
                                SecureStringBuffer newSoPin)

Deprecated. this constructor contains obsolete parameters; use another constructor that does not

A constructor; create a new TokenCredentialRecoverer object configured for use with a PKCS#11 device that has already been initialized and allows Security Officer PIN change (legacy).

This constructor should be used when the PKCS#11 device (token) that will be used to store the Digital Identity has already been set up with a Normal User. It also provides the ability to change the Security Officer PIN. Prior to Digital Identity recovery, the token will be prepared using one of the deletion mechanisms. A deletion mechanism indicates which objects on the token must be deleted; this can be set by calling setDeletionMechanism(TokenDeletionMechanism). The default deletion mechanism will simply delete all objects created by Entrust from the token.

When the user logs in, the token located at the indicated slot ID will be connected to using the PKCS#11 library provided. The token is then prepared, which may delete some of the objects it currently contains. If the current and new Security Officer PIN were provided, the PIN of the Security Officer is changed. Next, the Normal User is logged in to the token using the user's log-on password. At this point the token is ready for the Digital Identity recover operation.

Using the reference number and authentication code, the user's Digital Identity is recovered using the PKIX-CMP protocol. Any keys that are to be client generated are generated directly on the token. All other Digital Identity information is retrieved from the Security Manager and written to the token.

Parameters:

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

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

signingKeyAlgorithm - this parameter is no longer used; as of JTK 7.0 the algorithm of the signing key pair is always extracted from the user's policy settings

signingKeyStrength - this parameter is no longer used; as of JTK 7.0 the strength of the signing key pair is always extracted from the user's policy settings

pkixVersion - this parameter is no longer used; as of JTK 7.0 proto-PKIX is not supported and instead PKIX-CMP is always used for communication with the Security Manager

slotId - the slot ID indicating the location on the token where the user's Digital Identity will be stored

Note

A list of slot IDs can be retrieved from the token by calling the getSlotList() method from the PKCS11Information class.

pkcs11LibraryConnection - a connection to the PKCS#11 library of the token

currentSoPin - the current PIN of the Security Officer user on the token; when set (along with newSoPin) the Security Officer PIN will be changed to the new value indicated (OPTIONAL)

newSoPin - the new PIN for the Security Officer user on the token; when set (along with currentSoPin) the Security Officer PIN will be changed to this value (OPTIONAL)

Throws:

java.lang.IllegalArgumentException - thrown if any of the required parameters are null

TokenCredentialRecoverer

public TokenCredentialRecoverer(SecureStringBuffer referenceNumber,
                                AuthorizationCode authorizationCode,
                                long slotId,
                                PKCS11LibraryConnection pkcs11LibraryConnection,
                                SecureStringBuffer soPin,
                                java.lang.String label)

A constructor; create a new TokenCredentialRecoverer object configured for use with a PKCS#11 device that has not yet been initialized.

This constructor should be used when the PKCS#11 device (token) that will be used to store the Digital Identity has not yet been initialized, or is to be re-initialized. Prior to Digital Identity recovery the token will be initialized by calling the PKCS#11 function C_InitPIN. Be aware that not all tokens support this action; in this case, the token must be manually set up with a Normal User by some external means (custom token utilities).

When the user logs in, the token located at the indicated slot ID will be connected to using the PKCS#11 library provided. The token is then initialized, which will delete all information it currently contains, set the Security Officer PIN, and set the token label. Next, the Normal User PIN is initialized to the user's log-on password, and the Normal User is logged in to the token. At this point the token is ready for the Digital Identity recover operation.

Using the reference number and authentication code, the user's Digital Identity is recovered using the PKIX-CMP protocol. Any keys that are to be client generated are generated directly on the token. All other Digital Identity information is retrieved from the Security Manager and written to the token.

Note

Setting a deletion mechanism after using this constructor will not have any effect on how the token is prepared for the Digital Identity recovery operation. This constructor always initializes the token, which automatically deletes all objects from the token.

Parameters:

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

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

slotId - the slot ID indicating the location on the token where the user's Digital Identity will be stored

Note

A list of slot IDs can be retrieved from the token by calling the getSlotList() method from the PKCS11Information class.

pkcs11LibraryConnection - a connection to the PKCS#11 library of the token

soPin - the PIN of the Security Officer user on the token; this is automatically set when the token is initialized

label - a label for the token; this is automatically set when the token is initialized

Throws:

java.lang.IllegalArgumentException - thrown if any of the required parameters are null

Since:

7.0

TokenCredentialRecoverer

public TokenCredentialRecoverer(SecureStringBuffer referenceNumber,
                                AuthorizationCode authorizationCode,
                                int signingKeyAlgorithm,
                                int signingKeyStrength,
                                int pkixVersion,
                                long slotId,
                                PKCS11LibraryConnection pkcs11LibraryConnection,
                                SecureStringBuffer soPin,
                                java.lang.String label)

Deprecated. this constructor contains obsolete parameters; use another constructor that does not

A constructor; create a new TokenCredentialRecoverer object configured for use with a PKCS#11 device that has not yet been initialized. (legacy)

This constructor should be used when the PKCS#11 device (token) that will be used to store the Digital Identity has not yet been initialized, or is to be re-initialized. Prior to Digital Identity recovery the token will be initialized by calling the PKCS#11 function C_InitPIN. Be aware that not all tokens support this action; in this case, the token must be manually set up with a Normal User by some external means (custom token utilities).

When the user logs in, the token located at the indicated slot ID will be connected to using the PKCS#11 library provided. The token is then initialized, which will delete all information it currently contains, set the Security Officer PIN, and set the token label. Next, the Normal User PIN is initialized to the user's log-on password, and the Normal User is logged in to the token. At this point the token is ready for the Digital Identity recover operation.

Using the reference number and authentication code, the user's Digital Identity is recovered using the PKIX-CMP protocol. Any keys that are to be client generated are generated directly on the token. All other Digital Identity information is retrieved from the Security Manager and written to the token.

Note

Setting a deletion mechanism after using this constructor will not have any effect on how the token is prepared for the Digital Identity recovery operation. This constructor always initializes the token, which automatically deletes all objects from the token.

Parameters:

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

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

signingKeyAlgorithm - this parameter is no longer used; as of JTK 7.0 the algorithm of the signing key pair is always extracted from the user's policy settings

signingKeyStrength - this parameter is no longer used; as of JTK 7.0 the strength of the signing key pair is always extracted from the user's policy settings

pkixVersion - this parameter is no longer used; as of JTK 7.0 proto-PKIX is not supported and instead PKIX-CMP is always used for communication with the Security Manager

slotId - the slot ID indicating the location on the token where the user's Digital Identity will be stored

Note

A list of slot IDs can be retrieved from the token by calling the getSlotList() method from the PKCS11Information class.

pkcs11LibraryConnection - a connection to the PKCS#11 library of the token

soPin - the PIN of the Security Officer user on the token; this is automatically set when the token is initialized

label - a label for the token; this is automatically set when the token is initialized

Throws:

java.lang.IllegalArgumentException - thrown if any of the required parameters are null

Method Detail

getType

public java.lang.String getType()

Description copied from class: CredentialReader

Returns the type (name) of this specific credential reader.

Specified by:

getType in class CredentialReader

Returns:

the type (name) of credential reader

setPreserveUserKeyPairVersion

public void setPreserveUserKeyPairVersion(boolean preserveUserKeyPairVersion)

Allows the caller to maintain the client key-pair version during a recover operation.

The user will be recovered using the protocol version that matches the users key-pair type.

Parameters:

preserveUserKeyPairVersion - when true the user key-pair version will not change. When false the user key-pair version will be handled as described in setForceV1KeyPair. This setting takes precedence over the setForceV1KeyPair setting.

Since:

8.0 patch

See Also:

setForceV1KeyPair