com.entrust.toolkit.credentials

Class FilenameProfileWriter

java.lang.Object

com.entrust.toolkit.credentials.CredentialWriter

com.entrust.toolkit.credentials.FilenameProfileWriter

public final class FilenameProfileWriter
extends CredentialWriter

This credential writer is designed for writing an Entrust Digital Identity to an Entrust profile format (EPF) file.

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

• CredentialCreator
• CredentialRecoverer
• FilenameProfileReader
• PKCS12Reader
• StreamProfileReader
• RoamingCredentialReader

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

 SecureStringBuffer securePassword = new SecureStringBuffer(PASSWORD);
 CredentialReader credentialReader = new FilenameProfileReader(EPF_FILE_NAME);
 CredentialWriter credentialWriter = new FilenameProfileWriter(EPF_FILE_NAME);
 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 Entrust Digital Identity protection key.
static java.lang.String	DEFAULT_PROTECTION_ALGORITHM The default EPF protection algorithm.
static int	MINIMUM_HASH_COUNT The minimum hash count; this is the minimum number of iterations allowed when deriving the Entrust Digital Identity protection key.

Constructor Summary

Constructors

Modifier	Constructor and Description
	FilenameProfileWriter(java.lang.String fileName) Creates a FilenameProfileWriter object.
	FilenameProfileWriter(java.lang.String fileName, int hashCount) Creates a FilenameProfileWriter object.
protected	FilenameProfileWriter(java.lang.String fileName, java.lang.String protectionAlgorithm, int hashCount) Deprecated. use FilenameProfileWriter(String, int) Note, the protectionAlgorithm is no longer used by the toolkit. The protection algorithm is read by using the Client Settings profile protection policy. The scope is updated to protected and should only be used for internal testing.

Method Summary

Modifier and Type	Method and Description
java.lang.String	getType() Returns the type (name) of this specific credential writer, which is "FilenameProfileWriter".
boolean	setCredentialAccess(FilePermissions.FILE_ACCESS access) Set the file permissions for new Entrust profile format (EPF) files.
boolean	setCredentialAccess(FilePermissions.FILE_ACCESS access, boolean writable) Similar to the setCredentialAccess(FILE_ACCESS access) method, this method sets the file permissions on new Entrust EPF files, but also allows write access to be provided to (operating system) userids other than the owner.

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 EPF 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 Entrust Digital Identity 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 Entrust Digital Identity protection key.

Since:

7.0

See Also:

Constant Field Values

Constructor Detail

FilenameProfileWriter

public FilenameProfileWriter(java.lang.String fileName)

Creates a FilenameProfileWriter object.

When used to create a credential writer that will be used for writing an existing Entrust Digital Identity store that already contains EPF protection values (read using a FilenameProfileReader or StreamProfileReader), the EPF will be protected with the values read from the EPF.

When used to create a credential writer that will be used for writing a new Entrust Digital Identity (read using a CredentialCreator or CredentialRecoverer) or an existing Entrust Digital Identity store that does not contain EPF protection values (read using a PKCS12Reader), the EPF is automatically protected using the protection values specified by the Client Settings profile protection policy. The has count is not required, and when missing or zero, DEFAULT_HASH_COUNT) is automatically used.

Parameters:

fileName - the name of the EPF file where the user's Digital Identity will be written (usually has a .epf filename extension)

Throws:

java.lang.IllegalArgumentException - thrown if any of the required parameters are null, or fileName does not represent a file or represents a file that cannot be written to

Since:

7.0

FilenameProfileWriter

protected FilenameProfileWriter(java.lang.String fileName,
                                java.lang.String protectionAlgorithm,
                                int hashCount)

Deprecated. use FilenameProfileWriter(String, int) Note, the protectionAlgorithm is no longer used by the toolkit. The protection algorithm is read by using the Client Settings profile protection policy. The scope is updated to protected and should only be used for internal testing.

Parameters:

fileName - the name of the EPF file where the user's Digital Identity will be written (usually has a .epf filename extension)

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

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

Throws:

java.lang.IllegalArgumentException - thrown if any of the required parameters are null, fileName does not represent a file or represents a file that cannot be written to, or the EPF protection parameters are invalid

See Also:

EntrustProfileProtectionAlgorithms

FilenameProfileWriter

public FilenameProfileWriter(java.lang.String fileName,
                             int hashCount)

Creates a FilenameProfileWriter object.

When used to create a credential writer that will be used for writing an existing Entrust Digital Identity store that already contains EPF protection values (read using a FilenameProfileReader or StreamProfileReader), and the EPF protection values (protectionAlgorithm, hashCount) are not set, the EPF will be protected with the values read from the EPF.

When used to create a credential writer that will be used for writing a new Entrust Digital Identity store (read using a CredentialCreator or CredentialRecoverer) or an existing Entrust Digital Identity store that does not contain EPF protection values (read using a PKCS12Reader), the EPF is automatically protected using the protection values specified by the Client Settings profile protection policy. The has count is not required, and when missing or zero, DEFAULT_HASH_COUNT) is automatically used.

Parameters:

fileName - the name of the EPF file where the user's Digital Identity will be written (usually has a .epf filename extension)

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

Throws:

java.lang.IllegalArgumentException - thrown if any of the required parameters are null, fileName does not represent a file or represents a file that cannot be written to, or the EPF 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 "FilenameProfileWriter".

Specified by:

getType in class CredentialWriter

Returns:

String the type (name) of credential writer

setCredentialAccess

public boolean setCredentialAccess(FilePermissions.FILE_ACCESS access)
                            throws UserFatalException

Set the file permissions for new Entrust profile format (EPF) files. Permissions on existing EPF files are not changed (for example, during an update or recovery).

The permissions that can be set on a file are dependent on the capabilities of the underlying operating system. Therefore, an access level (such as OWNER) will have a similar but slightly different implementation depending on the operating system. Two models of file permissions are supported:

• Operating systems that support the POSIX standard, such as *NIX systems
• Operating systems that support the Access Control List (ACL) model as specified in RFC 3530 (Network File System Protocol), such as Microsoft Windows

The read-write file permissions that are associated with the different access levels, for these two models, are described below.

OWNER level:

• The user will be granted full read and write access
• On systems that support POSIX, all other users are not granted any access (that is, the file permission 'rw-------' is set).
• On systems that support ACLs, all others users will be granted access to read certain file metadata only (specifically they will be granted the following ACL permissions only: READ_NAMED_ATTRS, READ_ATTRIBUTES, READ_ACL).

GROUP and ALL levels:

• These two options are supported on POSIX only
• The group and other users will be granted read access only. (That is, 'rw-r----' or 'rw-r--r--' would be set.)

SYSTEM_DEFAULT level:

• File permissions are not explicitly set by the Entrust Java Toolkit when the EPF file is created, so the operating system defaults get set (as specified by the umask or ACL, for example)

The default is OWNER level. That is, if setCredentialAccess() is not called, then OWNER level will be used.

The system wide default can be changed to SYSTEM_DEFAULT by setting the following custom JVM boolean property that is supported by the Entrust Java Toolkit: com.entrust.toolkit.security.file.permissions.systemDefault. (For example, by configuring -Dcom.entrust.toolkit.security.file.permissions.systemDefault=true).

Parameters:

access - The level of access that should be set on the new EPF file

Returns:

boolean True if the file system supports the requested level of access. False otherwise (and the existing access level is not changed).

Throws:

UserFatalException

setCredentialAccess

public boolean setCredentialAccess(FilePermissions.FILE_ACCESS access,
                                   boolean writable)
                            throws UserFatalException

Similar to the setCredentialAccess(FILE_ACCESS access) method, this method sets the file permissions on new Entrust EPF files, but also allows write access to be provided to (operating system) userids other than the owner. This may be required if other userids have been granted access to the credential and should be allowed to perform an update during a login.

Parameters:

access - The level of access that should be set on the new EPF file

writable - Applies only to GROUP and ALL on POSIX systems, otherwise this setting is ignored. Indicates if 'group' and 'other' users should have write access to the EPF file. (The owner always has write access to the file.) (That is, 'rw-rw----' or 'rw-rw-rw-' would be set.)

Returns:

boolean True if the file system supports the requested level of access. False otherwise (and the existing access level is not changed).

Throws:

UserFatalException