TokenWriter ("Entrust Authority Security Toolkit for the Java Platform")

java.lang.Object
- com.entrust.toolkit.credentials.CredentialWriter
- - com.entrust.toolkit.credentials.TokenWriter

public final class TokenWriter
extends CredentialWriter

This credential writer is designed for writing an Entrust Digital Identity 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:

TokenCredentialCreator
TokenCredentialRecoverer
TokenReader

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):

 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 TokenReader(p11LibConn, slotId);
 CredentialWriter credentialWriter = new TokenWriter(ENTRUST_PATH, ENTRUST_USER);
 user.setCredentialWriter(credentialWriter);
 user.login(credentialReader, securePassword);
 user.write();

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
Modifier	Constructor and Description
	`TokenWriter()` Creates a `TokenWriter` object.
	`TokenWriter(java.lang.String entrustPath, java.lang.String entrustUser)` Creates a `TokenWriter` object.
	`TokenWriter(java.lang.String entrustPath, java.lang.String entrustUser, int hashCount)` Creates a `TokenWriter` object.
`protected`	`TokenWriter(java.lang.String entrustPath, java.lang.String entrustUser, java.lang.String protectionAlgorithm, int hashCount)` Deprecated. use `TokenWriter(String, String, int)`.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`createAuxProfile(boolean createAPF)` Specifies whether or not the auxiliary profile (APF) should be created.
`java.lang.String`	`getType()` Returns the type (name) of this specific credential writer, which is "TokenWriter".
`static void`	`setEnableKCN(boolean enable)` For INTERNAL use only by Entrust applications.
`void`	`storeAllUserCertsOnToken(boolean storeAllUserCertsOnToken)` Specifies whether the user certificates should be written to the token (only applicable to version 4).
`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 a new Digital Identity (creation or recovery).

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
  - TokenWriter
```
public TokenWriter()
```
    Creates a TokenWriter object.
    This constructor should only be used to create a token writer that will be used for writing an existing Digital Identity (read using a TokenReader). The 'Entrust Path' and 'Entrust User' values that are used to identify the location of the auxiliary profile (APF) are read from the token.
    
    When used to create a token writer that will be used for writing an Digital Identity (read using a TokenReader), the protection values read from the APF are used to protect the APF during the write. However, when used to create a token writer that will be used to write a new Digital Identity, default values the protection algorithm is read from the ClientSettings policy certificate, and theDEFAULT_HASH_COUNT is used.
    
    Warning
    
    Using this constructor to create a token writer that will be used to write a new Digital Identity (read using a TokenCredentialCreator or TokenCredentialRecoverer) IS NOT permitted, and WILL result in failure during the first write operation.
    
    Since:
    
    7.0
  - TokenWriter
```
public TokenWriter(java.lang.String entrustPath,
                   java.lang.String entrustUser)
```
    Creates a TokenWriter object.
    When used to create a token writer that will be used for writing a Digital Identity (read using a TokenReader), the 'Entrust Path' and 'Entrust User' values are optional. These values specify the location of the auxiliary profile (APF). When not set, the values read from the token are automatically used; however when set, the APF will be created at the location indicated. Thus, setting these values differently than the values on the token will cause the values on the token to be updated and the APF to be written to the new location.
    
    When used to create a token writer that will be used for writing a new Digital Identity (read using a TokenCredentialCreator or TokenCredentialRecoverer), the 'Entrust Path' and 'Entrust User' values are required. In this case, the APF protection read from the APF are used to protect the APF during the write. However, when used to create a token writer that will be used to write a new Digital Identity, default values the protection algorithm is read from the ClientSettings policy certificate, and theDEFAULT_HASH_COUNT is used.
    
    Warning
    
    Using this constructor with null 'Entrust Path' and 'Entrust User' values to create a token writer that will be used to write a new Digital Identity (read using a TokenCredentialCreator or TokenCredentialRecoverer) IS NOT permitted, and WILL result in failure during the first write operation.
    
    Parameters:
    
    entrustPath - the 'Entrust Path' component on the token, which indicates the path to the APF; when used to write a Digital Identity that was newly created or recovered, this parameter is required
    
    entrustUser - the 'Entrust User' component on the token, which indicates the name of the APF; when used to write a Digital Identity that was newly created or recovered, this parameter is required
    
    Throws:
    
    java.lang.IllegalArgumentException - thrown if the APF protection parameters are invalid
    
    Since:
    
    7.0
  - TokenWriter
```
protected TokenWriter(java.lang.String entrustPath,
                      java.lang.String entrustUser,
                      java.lang.String protectionAlgorithm,
                      int hashCount)
```
    Deprecated. use TokenWriter(String, String, int).
    
    The method is deprecated. Set the scope to protected for internal testing only. Use TokenWriter(String, String, int).
    
    Parameters:
    
    entrustPath - the 'Entrust Path' component on the token, which indicates the path to the APF; when used to write a Digital Identity that was newly created or recovered, this parameter is required
    
    entrustUser - the 'Entrust User' component on the token, which indicates the name of the APF; when used to write a Digital Identity that was newly created or recovered, this parameter is required
    
    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 MINIMUM_HASH_COUNT (OPTIONAL)
    
    Throws:
    
    java.lang.IllegalArgumentException - thrown if the APF protection parameters are invalid
    
    See Also:
    
    EntrustProfileProtectionAlgorithms
  - TokenWriter
```
public TokenWriter(java.lang.String entrustPath,
                   java.lang.String entrustUser,
                   int hashCount)
```
    Creates a TokenWriter object.
    When used to create a token writer that will be used for writing an existing Digital Identity (read using a TokenReader), the 'Entrust Path' and 'Entrust User' values are optional. These values specify the location of the auxiliary profile (APF). When not set, the values read from the token are automatically used; however when set, the APF will be created at the location indicated. Thus, setting these values differently than the values on the token will cause the values on the token to be updated and the APF to be written to a new location.
    
    When used to create a token writer that will be used to write a new Digital Identity (read using a TokenCredentialCreator or TokenCredentialRecoverer), the 'Entrust Path' and 'Entrust User' values are required. The APF protection values are not required. The protectionAlgorithm is automatically read from the ClientSettings policy certificate, and the hash Count specified in this API is used. When missing or zero, DEFAULT_HASH_COUNT is used.
    
    Warning
    
    Using this constructor with null 'Entrust Path' and 'Entrust User' values to create a token writer that will be used to write a new Digital Identity (read using a TokenCredentialCreator or TokenCredentialRecoverer) IS NOT permitted, and WILL result in failure during the first write operation.
    
    Parameters:
    
    entrustPath - the 'Entrust Path' component on the token, which indicates the path to the APF; when used to write a Digital Identity that was newly created or recovered, this parameter is required
    
    entrustUser - the 'Entrust User' component on the token, which indicates the name of the APF; when used to write a Digital Identity that was newly created or recovered, this parameter is required
    
    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 "TokenWriter".
    
    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 created.
    When a new Digital Identity is being created/recovered or an existing Digital Identity that does not have a corresponding APF is being read, this method specifies whether or not an APF should be created. When an existing Digital Identity that does have a corresponding APF is being read, this method has no effect, the APF will always be written.
    
    Parameters:
    
    createAPF - indicates whether or not an APF should be created
  - 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 a new Digital Identity (creation or recovery).
    When a user is created, their Digital Identity information contains only current key information. Thus, calling this method prior to a Digital Identity write operation for a user that was just created, will have no effect on what is written to the token. However, when a user is recovered, their Digital Identity information contains all key information, including history key information. Thus, calling this method with false prior to a Digital Identity write operation for a user that was just recovered will cause only the current key information to be written to the token.
    
    By default, all key information is 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
  - storeAllUserCertsOnToken
```
public void storeAllUserCertsOnToken(boolean storeAllUserCertsOnToken)
```
    Specifies whether the user certificates should be written to the token (only applicable to version 4).
    By default, the user 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 user certificate to also be written to the token.
    
    Parameters:
    
    storeAllUserCertsOnToken - indicates whether the user certificates should be written to the token
    
    Since:
    
    9.0
  - setEnableKCN
```
public static void setEnableKCN(boolean enable)
```
    For INTERNAL use only by Entrust applications. Enabling this will otherwise consume additional storage on the p11 device.
    
    Parameters:
    
    enable -

Class TokenWriter

Field Summary

Constructor Summary

Method Summary

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

Methods inherited from class java.lang.Object

Field Detail

DEFAULT_PROTECTION_ALGORITHM

DEFAULT_HASH_COUNT

MINIMUM_HASH_COUNT

Constructor Detail

TokenWriter

TokenWriter

TokenWriter

TokenWriter

Method Detail

getType

createAuxProfile

useKeyHistory

storeIntermediateCACertsOnToken

storeAllUserCertsOnToken

setEnableKCN