com.entrust.toolkit.credentials

Class TokenInitializer

java.lang.Object

com.entrust.toolkit.credentials.CredentialWriter

com.entrust.toolkit.credentials.TokenInitializer

public final class TokenInitializer
extends CredentialWriter

This credential writer is designed for writing an Entrust Digital Identity that currently exists in software to a PKCS#11 device (token).

All communication with the token is done using the PKCS#11 version 2.01 API. Writing a token-based Digital Identity involves writing all Entrust Digital Identity information to the token, and a subset of this information to an auxiliary profile (APF).

The following credential readers can all be used with this credential writer:

• FilenameProfileReader
• PKCS12Reader
• StreamProfileReader

Below is an example of how a user's Digital Identity can be logged into and then written (all capitalized values must be provided by the user):

A token initializer DOES NOT provide key management, password change, or multiple write capabilities. To do so, once the file-based Digital Identity has been written to the token, the user should logout, and then log in using a TokenReader and TokenWriter.

 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 securePassword = new SecureStringBuffer(PASSWORD);
 CredentialReader credentialReader = new FilenameProfileReader(EPF_FILE_NAME);
 CredentialWriter credentialWriter = new TokenInitializer(slotId, p11LibConn, ENTRUST_PATH, ENTRUST_USER);
 user.setCredentialWriter(credentialWriter);
 user.login(credentialReader, securePassword);
 user.write();
 user.logout();
 

Field Summary

Fields

Modifier and Type	Field and Description
static int	DEFAULT_HASH_COUNT The default hash count; this is the number of iterations used by default when deriving the APF protection key.
static java.lang.String	DEFAULT_PROTECTION_ALGORITHM The default APF protection algorithm.
static int	MINIMUM_HASH_COUNT The minimum hash count; this is the minimum number of iterations allowed when deriving the APF protection key.

Constructor Summary

Constructors

Constructor and Description
TokenInitializer(long slotId, PKCS11LibraryConnection pkcs11LibraryConnection, SecureStringBuffer currentSoPin, SecureStringBuffer newSoPin, java.lang.String entrustPath, java.lang.String entrustUser) Creates a TokenInitializer object.
TokenInitializer(long slotId, PKCS11LibraryConnection pkcs11LibraryConnection, SecureStringBuffer currentSoPin, SecureStringBuffer newSoPin, java.lang.String entrustPath, java.lang.String entrustUser, int hashCount) Creates a TokenInitializer object.
TokenInitializer(long slotId, PKCS11LibraryConnection pkcs11LibraryConnection, SecureStringBuffer currentSoPin, SecureStringBuffer newSoPin, java.lang.String entrustPath, java.lang.String entrustUser, java.lang.String protectionAlgorithm, int hashCount) Deprecated. use {@link TokenInitializer#TokenInitializer(long, PKCS11LibraryConnection, SecureStringBuffer, SecureStringBuffer, String, String, int)
TokenInitializer(long slotId, PKCS11LibraryConnection pkcs11LibraryConnection, SecureStringBuffer soPin, java.lang.String label, java.lang.String entrustPath, java.lang.String entrustUser) Creates a TokenInitializer object.
TokenInitializer(long slotId, PKCS11LibraryConnection pkcs11LibraryConnection, SecureStringBuffer soPin, java.lang.String label, java.lang.String entrustPath, java.lang.String entrustUser, int hashCount) Creates a TokenInitializer object.
TokenInitializer(long slotId, PKCS11LibraryConnection pkcs11LibraryConnection, SecureStringBuffer soPin, java.lang.String label, java.lang.String entrustPath, java.lang.String entrustUser, java.lang.String protectionAlgorithm, int hashCount) Deprecated. use TokenInitializer(long, PKCS11LibraryConnection, SecureStringBuffer, String, String, String, int)
TokenInitializer(long slotId, PKCS11LibraryConnection pkcs11LibraryConnection, java.lang.String entrustPath, java.lang.String entrustUser) Creates a TokenInitializer object.
TokenInitializer(long slotId, PKCS11LibraryConnection pkcs11LibraryConnection, java.lang.String entrustPath, java.lang.String entrustUser, java.lang.String protectionAlgorithm, int hashCount) Creates a TokenInitializer object.

Method Summary

Methods

Modifier and Type	Method and Description
void	createAuxProfile(boolean createAPF) Specifies whether or not the auxiliary profile (APF) should be written.
java.lang.String	getType() Returns the type (name) of this specific credential writer, which is "TokenInitializer".
void	setDeletionMechanism(TokenDeletionMechanism deletionMechanism) Sets the deletion mechanism to be used to prepare the PKCS#11 device (token) for the Digital Identity.
void	storeIntermediateCACertsOnToken(boolean intermediateCACertsOnToken) Specifies whether the Intermediate CA certificates should be written to the token (only applicable to version 4).
void	useKeyHistory(boolean useKeyHistory) Specifies whether the entire key history or just current key information should be written to the token when writing the Digital Identity.

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

addConfiguration, writePossible

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_PROTECTION_ALGORITHM

public static final java.lang.String DEFAULT_PROTECTION_ALGORITHM

The default APF protection algorithm.

Since:

7.0

See Also:

Constant Field Values

DEFAULT_HASH_COUNT

public static final int DEFAULT_HASH_COUNT

The default hash count; this is the number of iterations used by default when deriving the APF protection key.

Since:

7.0

See Also:

Constant Field Values

MINIMUM_HASH_COUNT

public static final int MINIMUM_HASH_COUNT

The minimum hash count; this is the minimum number of iterations allowed when deriving the APF protection key.

Since:

7.0

See Also:

Constant Field Values

Constructor Detail

TokenInitializer

public TokenInitializer(long slotId,
                PKCS11LibraryConnection pkcs11LibraryConnection,
                java.lang.String entrustPath,
                java.lang.String entrustUser)

Creates a TokenInitializer object.

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 (the Normal User PIN must be identical to the password of the file-based Digital Identity). Prior to Digital Identity write, 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 a Digital Identity write operation is attempted, 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 (same password as for the file-based Digital Identity). Finally, all Digital Identity information is written to the token and the Auxiliary Profile (APF).

The APF will automatically be protected using the protection algorithm specified in the ClientSettings policy certificate, and the DEFAULT_HASH_COUNT.

Note

This class is designed for transferring a file-based Digital Identity onto a token. It does not provide key management or password change capabilities and is only capable of doing a single write operation.

Parameters:

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

entrustPath - the 'Entrust Path' component on the token, which indicates the path to the APF

entrustUser - the 'Entrust User' component on the token, which indicates the name of the APF

Since:

7.0

TokenInitializer

public TokenInitializer(long slotId,
                PKCS11LibraryConnection pkcs11LibraryConnection,
                java.lang.String entrustPath,
                java.lang.String entrustUser,
                java.lang.String protectionAlgorithm,
                int hashCount)

Creates a TokenInitializer object.

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 (the Normal User PIN must be identical to the password of the file-based Digital Identity). Prior to Digital Identity write, 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 a Digital Identity write operation is attempted, 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 (same password as for the file-based Digital Identity). Finally, all Digital Identity information is written to the token and the Auxiliary Profile (APF).

The APF protection values (protectionAlgorithm, hashCount) indicate the protection that will be used in the APF. The protectionAlgorithm is automatically read from the ClientSettings policy certificate, only the hash count is used in this API. When missing or zero, DEFAULT_HASH_COUNT is used.

Note

This class is designed for transferring a file-based Digital Identity onto a token. It does not provide key management or password change capabilities and is only capable of doing a single write operation.

Parameters:

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

entrustPath - the 'Entrust Path' component on the token, which indicates the path to the APF

entrustUser - the 'Entrust User' component on the token, which indicates the name of the APF

protectionAlgorithm - the algorithm used to protect the APF; only the algorithms defined in EntrustProfileProtectionAlgorithms are supported (OPTIONAL)

hashCount - the number of iterations used by when deriving the APF protection key; must be no less than 2 (OPTIONAL)

Throws:

java.lang.IllegalArgumentException - thrown if the APF protection parameters are invalid

Since:

7.0

See Also:

EntrustProfileProtectionAlgorithms

TokenInitializer

public TokenInitializer(long slotId,
                PKCS11LibraryConnection pkcs11LibraryConnection,
                SecureStringBuffer currentSoPin,
                SecureStringBuffer newSoPin,
                java.lang.String entrustPath,
                java.lang.String entrustUser)

Creates a TokenInitializer object.

This constructor should be used when the PKCS#11 device (token) that will be used to store the Digital Identity has already been setup with a Normal User. It also provides the ability to change the Security Officer PIN. Prior to Digital Identity write, 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 a Digital Identity write operation is attempted, 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. Finally, all Digital Identity information is written to the token and the Auxiliary Profile (APF).

The APF will automatically be protected using the protection algorithm specified in the ClientSettings policy certificate, and the DEFAULT_HASH_COUNT.

Note

This class is designed for transferring a file-based Digital Identity onto a token. It does not provide key management or password change capabilities and is only capable of doing a single write operation.

Parameters:

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 the Security Officer user on the token; when set (along with currentSoPin) the Security Officer PIN will be changed to this value (OPTIONAL)

entrustPath - the 'Entrust Path' component on the token, which indicates the path to the APF

entrustUser - the 'Entrust User' component on the token, which indicates the name of the APF

Since:

7.0

TokenInitializer

public TokenInitializer(long slotId,
                PKCS11LibraryConnection pkcs11LibraryConnection,
                SecureStringBuffer currentSoPin,
                SecureStringBuffer newSoPin,
                java.lang.String entrustPath,
                java.lang.String entrustUser,
                int hashCount)

Creates a TokenInitializer object.

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 write, 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 a Digital Identity write operation is attempted, 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. Finally, all Digital Identity information is written to the token and the Auxiliary Profile (APF).

The APF will automatically be protected using the protection algorithm specified in the ClientSettings policy certificate, and the DEFAULT_HASH_COUNT.

Note

This class is designed for transferring a file-based Digital Identity onto a token. It does not provide key management or password change capabilities and is only capable of doing a single write operation.

Parameters:

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 the Security Officer user on the token; when set (along with currentSoPin) the Security Officer PIN will be changed to this value (OPTIONAL)

entrustPath - the 'Entrust Path' component on the token, which indicates the path to the APF

entrustUser - the 'Entrust User' component on the token, which indicates the name of the APF

hashCount - the number of iterations used by when deriving the APF protection key; must be no less than MINIMUM_HASH_COUNT (OPTIONAL)

Throws:

java.lang.IllegalArgumentException - thrown if the APF protection parameters are invalid

Since:

7.0

See Also:

EntrustProfileProtectionAlgorithms

TokenInitializer

public TokenInitializer(long slotId,
                PKCS11LibraryConnection pkcs11LibraryConnection,
                SecureStringBuffer currentSoPin,
                SecureStringBuffer newSoPin,
                java.lang.String entrustPath,
                java.lang.String entrustUser,
                java.lang.String protectionAlgorithm,
                int hashCount)

Deprecated. use {@link TokenInitializer#TokenInitializer(long, PKCS11LibraryConnection, SecureStringBuffer, SecureStringBuffer, String, String, int)

Parameters:

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 the Security Officer user on the token; when set (along with currentSoPin) the Security Officer PIN will be changed to this value (OPTIONAL)

entrustPath - the 'Entrust Path' component on the token, which indicates the path to the APF

entrustUser - the 'Entrust User' component on the token, which indicates the name of the APF

protectionAlgorithm - the algorithm used to protect the APF; The value specified here is never used. The value is read from a ClientSettings policy value.

hashCount - the number of iterations used by when deriving the APF protection key; must be no less than MINIMUM_HASH_COUNT (OPTIONAL)

Throws:

java.lang.IllegalArgumentException - thrown if the APF protection parameters are invalid

Since:

7.0

See Also:

EntrustProfileProtectionAlgorithms

TokenInitializer

public TokenInitializer(long slotId,
                PKCS11LibraryConnection pkcs11LibraryConnection,
                SecureStringBuffer soPin,
                java.lang.String label,
                java.lang.String entrustPath,
                java.lang.String entrustUser)

Creates a TokenInitializer object.

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 write, 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 a Digital Identity write operation is attempted, 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. Finally, all Digital Identity information is written to the token and the Auxiliary Profile (APF).

The APF will automatically be protected using the protection algorithm specified in the ClientSettings policy certificate, and the DEFAULT_HASH_COUNT.

Note

This class is designed for transferring a file-based Digital Identity onto a token. It does not provide key management or password change capabilities and is only capable of doing a single write operation.

Parameters:

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

entrustPath - the 'Entrust Path' component on the token, which indicates the path to the APF

entrustUser - the 'Entrust User' component on the token, which indicates the name of the APF

Since:

7.0

TokenInitializer

public TokenInitializer(long slotId,
                PKCS11LibraryConnection pkcs11LibraryConnection,
                SecureStringBuffer soPin,
                java.lang.String label,
                java.lang.String entrustPath,
                java.lang.String entrustUser,
                int hashCount)

Creates a TokenInitializer object.

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 write, 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 a Digital Identity write operation is attempted, 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. Finally, all Digital Identity information is written to the token and the Auxiliary Profile (APF).

The APF will automatically be protected using the protection algorithm specified in the ClientSettings policy certificate, and the specified hash count.

Note

This class is designed for transferring a file-based Digital Identity onto a token. It does not provide key management or password change capabilities and is only capable of doing a single write operation.

Parameters:

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

entrustPath - the 'Entrust Path' component on the token, which indicates the path to the APF

entrustUser - the 'Entrust User' component on the token, which indicates the name of the APF

hashCount - the number of iterations used by when deriving the APF protection key; must be no less than MINIMUM_HASH_COUNT (OPTIONAL)

Throws:

java.lang.IllegalArgumentException - thrown if the APF protection parameters are invalid

See Also:

EntrustProfileProtectionAlgorithms

TokenInitializer

public TokenInitializer(long slotId,
                PKCS11LibraryConnection pkcs11LibraryConnection,
                SecureStringBuffer soPin,
                java.lang.String label,
                java.lang.String entrustPath,
                java.lang.String entrustUser,
                java.lang.String protectionAlgorithm,
                int hashCount)

Deprecated. use TokenInitializer(long, PKCS11LibraryConnection, SecureStringBuffer, String, String, String, int)

Parameters:

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

entrustPath - the 'Entrust Path' component on the token, which indicates the path to the APF

entrustUser - the 'Entrust User' component on the token, which indicates the name of the APF

protectionAlgorithm - the algorithm used to protect the APF; The value specified here is never used. The value is read from a ClientSettings policy value.

hashCount - the number of iterations used by when deriving the APF protection key; must be no less than MINIMUM_HASH_COUNT (OPTIONAL)

Throws:

java.lang.IllegalArgumentException - thrown if the APF protection parameters are invalid

See Also:

EntrustProfileProtectionAlgorithms

Method Detail

getType

public java.lang.String getType()

Returns the type (name) of this specific credential writer, which is "TokenInitializer".

Specified by:

getType in class CredentialWriter

Returns:

the type (name) of credential writer

createAuxProfile

public void createAuxProfile(boolean createAPF)

Specifies whether or not the auxiliary profile (APF) should be written.

Parameters:

createAPF - indicates whether or not an APF should be written

useKeyHistory

public void useKeyHistory(boolean useKeyHistory)

Specifies whether the entire key history or just current key information should be written to the token when writing the Digital Identity.

By default, all key information is written to the token. Thus, calling this method with false prior to Digital Identity write, will cause only the current key information to be written to the token. Also, calling this method does not have any effect on what is written to the APF; when the APF is written, it is always done using all key information. This method also has no effect on writes to an existing Digital Identity.

Parameters:

useKeyHistory - indicates whether the entire key history or just the current key information should be written to the token

storeIntermediateCACertsOnToken

public void storeIntermediateCACertsOnToken(boolean intermediateCACertsOnToken)

Specifies whether the Intermediate CA certificates should be written to the token (only applicable to version 4).

By default, the intermediate CA certificates are not written to the token. Instead, in the interests of preserving memory on the token, they are only written to the APF. Calling this method with true will cause the intermediate CA certificate to also be written to the token.

Parameters:

intermediateCACertsOnToken - indicates whether the Intermediate CA certificate should be written to the token

Since:

7.0

setDeletionMechanism

public void setDeletionMechanism(TokenDeletionMechanism deletionMechanism)

Sets the deletion mechanism to be used to prepare the PKCS#11 device (token) for the Digital Identity.

Prior to Digital Identity write, the token may already contain information that the user wants removed. The default behaviour (when not initializing the token, which automatically deletes all objects) is to delete all objects created by Entrust from the token. However, there are other alternatives, such as deleting all objects or not deleting any objects.

Parameters:

deletionMechanism - the token deletion mechanism

Since:

7.0