public final class TokenWriter extends CredentialWriter
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:
TokenCredentialCreatorTokenCredentialRecovererTokenReaderBelow 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();
| 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.
|
| 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.
|
| 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).
|
addConfiguration, writePossiblepublic static final java.lang.String DEFAULT_PROTECTION_ALGORITHM
public static final int DEFAULT_HASH_COUNT
public static final int MINIMUM_HASH_COUNT
public TokenWriter()
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.
TokenCredentialCreator or
TokenCredentialRecoverer) IS NOT permitted, and WILL
result in failure during the first write operation.
public TokenWriter(java.lang.String entrustPath,
java.lang.String entrustUser)
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.
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.
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 requiredentrustUser - 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 requiredjava.lang.IllegalArgumentException - thrown if the APF protection parameters are invalidprotected TokenWriter(java.lang.String entrustPath,
java.lang.String entrustUser,
java.lang.String protectionAlgorithm,
int hashCount)
TokenWriter(String, String, int).TokenWriter(String, String, int).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 requiredentrustUser - 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 requiredprotectionAlgorithm - 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)java.lang.IllegalArgumentException - thrown if the APF protection parameters are invalidEntrustProfileProtectionAlgorithmspublic TokenWriter(java.lang.String entrustPath,
java.lang.String entrustUser,
int hashCount)
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.
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.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 requiredentrustUser - 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 requiredhashCount - the number of iterations used by when deriving the APF protection key;
must be no less than MINIMUM_HASH_COUNT (OPTIONAL)java.lang.IllegalArgumentException - thrown if the APF protection parameters are invalidEntrustProfileProtectionAlgorithmspublic java.lang.String getType()
getType in class CredentialWriterpublic void createAuxProfile(boolean createAPF)
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.
createAPF - indicates whether or not an APF should be createdpublic void useKeyHistory(boolean useKeyHistory)
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.
useKeyHistory - indicates whether the entire key history or just the current key
information should be written to the tokenpublic void storeIntermediateCACertsOnToken(boolean intermediateCACertsOnToken)
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.
intermediateCACertsOnToken - indicates whether the Intermediate CA certificate should be written
to the tokenpublic void storeAllUserCertsOnToken(boolean storeAllUserCertsOnToken)
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.
storeAllUserCertsOnToken - indicates whether the user certificates should be written
to the tokenpublic static void setEnableKCN(boolean enable)
enable -