Package com.unboundid.util

Class PasswordFileReader

java.lang.Object
com.unboundid.util.PasswordFileReader
@ThreadSafety(level=NOT_THREADSAFE) public final class PasswordFileReader extends 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
    Description
    PasswordFileReader()
    Creates a new instance of this password file reader.
    PasswordFileReader(boolean allowPromptingForPassphrase)
    Creates a new instance of this password file reader.
    PasswordFileReader(PrintStream standardOutput, 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

    Modifier and Type
    Method
    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(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.
    List<char[]>
    getCachedEncryptionPasswords()
    Retrieves a list of the encryption passwords currently held in the cache.
    char[]
    readPassword(File file)
    Attempts to read a password from the specified file.
    char[]
    readPassword(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 Details

    • 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 PrintStream standardOutput, @NotNull 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 Details

    • readPassword

      @NotNull public char[] readPassword(@NotNull String path) throws 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:
      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 File file) throws 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:
      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 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 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.