com.unboundid.util

Class PasswordFileReader

java.lang.Object

com.unboundid.util.PasswordFileReader

@ThreadSafety(level=NOT_THREADSAFE)
public final class PasswordFileReader
extends java.lang.Object

This class provides a mechanism for reading a password from a file. Password files must contain exactly one line, which must be non-empty, and the entire content of that line will be used as the password.

The contents of the file may have optionally been encrypted with the PassphraseEncryptedOutputStream, and may have optionally been compressed with the GZIPOutputStream. If the data is both compressed and encrypted, then it must have been compressed before it was encrypted, so that it is necessary to decrypt the data before it can be decompressed.

If the file is encrypted, then the encryption key may be obtained in one of the following ways:

• If this code is running in a tool that is part of a Ping Identity Directory Server installation (or a related product like the Directory Proxy Server or Data Synchronization Server, or an alternately branded version of these products, like the Alcatel-Lucent or Nokia 8661 versions), and the file was encrypted with a key from that server's encryption settings database, then the tool will try to get the key from the corresponding encryption settings definition. In many cases, this may not require any interaction from the user at all.
• The reader maintains a cache of passwords that have been previously used. If the same password is used to encrypt multiple files, it may only need to be requested once from the user. The caller can also manually add passwords to this cache if they are known in advance.
• The user can be interactively prompted for the password.

Constructor Summary

Constructors

Constructor and Description
PasswordFileReader() Creates a new instance of this password file reader.
PasswordFileReader(boolean allowPromptingForPassphrase) Creates a new instance of this password file reader.
PasswordFileReader(java.io.PrintStream standardOutput, java.io.PrintStream standardError) Creates a new instance of this password file reader using the specified output and error streams if it is necessary to interactively prompt the user for an encryption passphrase.

Method Summary

Methods

Modifier and Type	Method and Description
void	addToEncryptionPasswordCache(char[] encryptionPassword) Adds the provided password to the cache of passwords that will be tried as potential encryption keys if an encrypted password file is encountered.
void	addToEncryptionPasswordCache(java.lang.String encryptionPassword) Adds the provided password to the cache of passwords that will be tried as potential encryption keys if an encrypted password file is encountered.
void	clearEncryptionPasswordCache(boolean zeroArrays) Clears the cache of passwords that will be tried as potential encryption keys if an encrypted password file is encountered.
java.util.List<char[]>	getCachedEncryptionPasswords() Retrieves a list of the encryption passwords currently held in the cache.
char[]	readPassword(java.io.File file) Attempts to read a password from the specified file.
char[]	readPassword(java.lang.String path) Attempts to read a password from the specified file.

Methods inherited from class java.lang.Object

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

Constructor Detail

PasswordFileReader

public PasswordFileReader()

Creates a new instance of this password file reader. The JVM-default standard output and error streams will be used if it is necessary to interactively prompt the user for an encryption passphrase.

PasswordFileReader

public PasswordFileReader(boolean allowPromptingForPassphrase)

Creates a new instance of this password file reader. The JVM-default standard output and error streams will be used if it is necessary to interactively prompt the user for an encryption passphrase.

Parameters:

allowPromptingForPassphrase - Indicates whether to allow interactively prompting the end user for the encryption passphrase if the file is encrypted and the key cannot be automatically obtained (for example, from a Ping Identity server's encryption settings database).

PasswordFileReader

public PasswordFileReader(@NotNull
                  java.io.PrintStream standardOutput,
                  @NotNull
                  java.io.PrintStream standardError)

Creates a new instance of this password file reader using the specified output and error streams if it is necessary to interactively prompt the user for an encryption passphrase.

Parameters:

standardOutput - The print stream that should be used as standard output if an encrypted password file is encountered and it is necessary to prompt for the password used as the encryption key. This must not be null.

standardError - The print stream that should be used as standard error if an encrypted password file is encountered and it is necessary to prompt for the password used as the encryption key. This must not be null.

Method Detail

readPassword

@NotNull
public char[] readPassword(@NotNull
                          java.lang.String path)
                    throws java.io.IOException,
                           LDAPException

Attempts to read a password from the specified file.

Parameters:

path - The path to the file from which the password should be read. It must not be null, and the file must exist.

Returns:

The characters that comprise the password read from the specified file.

Throws:

java.io.IOException - If a problem is encountered while trying to read the password from the file.

LDAPException - If the file does not exist, if it does not contain exactly one line, or if that line is empty.

readPassword

@NotNull
public char[] readPassword(@NotNull
                          java.io.File file)
                    throws java.io.IOException,
                           LDAPException

Attempts to read a password from the specified file.

Parameters:

file - The path file from which the password should be read. It must not be null, and the file must exist.

Returns:

The characters that comprise the password read from the specified file.

Throws:

java.io.IOException - If a problem is encountered while trying to read the password from the file.

LDAPException - If the file does not exist, if it does not contain exactly one line, or if that line is empty.

getCachedEncryptionPasswords

@NotNull
public java.util.List<char[]> getCachedEncryptionPasswords()

Retrieves a list of the encryption passwords currently held in the cache.

Returns:

A list of the encryption passwords currently held in the cache, or an empty list if there are no cached passwords.

addToEncryptionPasswordCache

public void addToEncryptionPasswordCache(@NotNull
                                java.lang.String encryptionPassword)

Adds the provided password to the cache of passwords that will be tried as potential encryption keys if an encrypted password file is encountered.

Parameters:

encryptionPassword - A password to add to the cache of passwords that will be tried as potential encryption keys if an encrypted password file is encountered. It must not be null or empty.

addToEncryptionPasswordCache

public void addToEncryptionPasswordCache(@NotNull
                                char[] encryptionPassword)

Adds the provided password to the cache of passwords that will be tried as potential encryption keys if an encrypted password file is encountered.

Parameters:

encryptionPassword - A password to add to the cache of passwords that will be tried as potential encryption keys if an encrypted password file is encountered. It must not be null or empty.

clearEncryptionPasswordCache

public void clearEncryptionPasswordCache(boolean zeroArrays)

Clears the cache of passwords that will be tried as potential encryption keys if an encrypted password file is encountered.

Parameters:

zeroArrays - Indicates whether to zero out the contents of the cached passwords before clearing them. If this is true, then all of the backing arrays for the cached passwords will be overwritten with all null characters to erase the original passwords from memory.