Package com.unboundid.ldap.sdk.unboundidds

Class AES256EncodedPassword

java.lang.Object
com.unboundid.ldap.sdk.unboundidds.AES256EncodedPassword
All Implemented Interfaces:
Serializable
@NotMutable @ThreadSafety(level=COMPLETELY_THREADSAFE) public final class AES256EncodedPassword extends Object implements Serializable
This class provides a mechanism that can be used to encrypt and decrypt passwords using the same mechanism that the Ping Identity Directory Server uses for the AES256 password storage scheme (for clients that know the passphrase used to generate the encryption key).
NOTE: This class, and other classes within the com.unboundid.ldap.sdk.unboundidds package structure, are only supported for use against Ping Identity, UnboundID, and Nokia/Alcatel-Lucent 8661 server products. These classes provide support for proprietary functionality or for external specifications that are not considered stable or mature enough to be guaranteed to work in an interoperable way with other types of LDAP servers.

Note that this class requires strong encryption support in the underlying JVM. For Java 7 JVMs, and for Java 8 JVMs prior to update 161, this requires installing unlimited strength jurisdiction policy files in the JVM. For Java 8 JVMs starting with update 161, and for all later Java versions, strong encryption should be available by default.

The raw representation for encoded passwords is constructed as follows:
  1. A single byte that combines the encoding version and the padding length. The least significant four bits represent a two's complement integer that indicate the number of zero bytes that will be appended to the provided password to make it a multiple of sixteen bytes. The most significant four bits represent the encoding version. At present, we only support a single encoding version in which all of those bits must be set to zero. With this encoding version, the following properties will be used:
    • Cipher Transformation: AES/GCM/NoPadding
    • Key Factory Algorithm: PBKDF2WithHmacSHA512
    • Key Factory Iteration Count: 32,768
    • Key Factory Salt Length: 128 bits (16 bytes)
    • Key Factory Generated Key length: 256 bits (32 bytes)
    • Initialization Vector Length: 128 bits (16 bytes)
    • GCM Tag Length: 128 bits
    • Padding Modulus: 16
  2. Sixteen bytes of random data generated by a secure random number generator. This represents the salt provided to the key factory for the purpose of generating the secret key.
  3. Sixteen bytes of random data generated by a secure random number generator. This represents the initialization vector that will be used to randomize the cipher output.
  4. One byte that represents a two's complement integer that indicates the number of bytes in the ID of the encryption settings definition whose passphrase is used to generate the encryption key. The value must be less than or equal to 255. For current versions of the Ping Identity Directory Server, it will typically be 32 bytes.
  5. The bytes that comprise the raw ID of the encryption settings definition whose passphrase will be used to generate the encryption key.
  6. The bytes that comprise the encrypted password using the above settings.

The string representation of the encoded password is generated by appending the base64-encoded representation of the raw encoded bytes to the prefix "{AES256}".

When encrypting a password using this algorithm, the first step is to generate the encryption key. This is done using a key factory, which combines a passphrase (obtained from an encryption settings definition), an iteration count, and a salt.

The second step is to apply any necessary padding to the password. Because AES used in Galois Counter mode (GCM) behaves as a stream cipher, the size of the encrypted data can be used to determine the size of the plaintext that was encrypted. This is undesirable when encrypting passwords because it can let an attacker know how long the user's password is. Padding the password (by appending enough zero bytes to make its length a multiple of sixteen bytes) makes it impossible for an attacker to determine the size of the clear-text password.

The final step is to perform the encryption. A cipher is created using the generated secret key and initialization vector, and it is used to encrypt the padded password.

Because this encoding uses reversible encryption rather than a one-way algorithm, there are two possible ways to verify that a provided plain-text password matches an encoded representation. Both involve decoding the encoded representation of the password to extract the padding length, salt, initialization vector, and encryption settings definition ID. Then, you can either encrypt the provided plaintext password with the same settings to verify that it yields the same encoded representation, or you can decrypt the encoded password and remove any padding to verify that it yields the same plaintext representation.
See Also:

  • Field Details

  • Method Details

    • getEncodingVersion

      public int getEncodingVersion()
      Retrieves the encoding version for this encoded password.
      Returns:
      The encoding version for this encoded password.

    • getPaddingBytes

      public int getPaddingBytes()
      Retrieves the number of bytes of padding that need to be appended to the clear-text password to make its length a multiple of sixteen bytes.
      Returns:
      The number of bytes of padding that need to be appended to the clear-text password to make its length a multiple of sixteen bytes.

    • getKeyFactorySalt

      @NotNull public byte[] getKeyFactorySalt()
      Retrieves the salt used to generate the encryption key from the encryption settings definition passphrase.
      Returns:
      The salt used to generate the encryption key from the encryption settings definition passphrase.

    • getInitializationVector

      @NotNull public byte[] getInitializationVector()
      Retrieves the initialization vector used to randomize the cipher output.
      Returns:
      The initialization vector used to randomize the cipher output.

    • getEncryptionSettingsDefinitionIDBytes

      @NotNull public byte[] getEncryptionSettingsDefinitionIDBytes()
      Retrieves the bytes that comprise the raw ID of the encryption settings definition whose passphrase is used to generate the encryption key.
      Returns:
      A bytes that comprise the raw ID of the encryption settings definition whose passphrase is used to generate the encryption key.

    • getEncryptionSettingsDefinitionIDString

      @NotNull public String getEncryptionSettingsDefinitionIDString()
      Retrieves a string representation of the ID of the encryption settings definition whose passphrase is used to generate the encryption key.
      Returns:
      A string representation of the ID of the encryption settings definition whose passphrase is used to generate the encryption key.

    • getEncodedRepresentation

      @NotNull public byte[] getEncodedRepresentation()
      Retrieves the bytes that comprise the complete raw encoded representation of the password.
      Returns:
      The bytes that comprise the complete raw encoded representation of the password.

    • getStringRepresentation

      @NotNull public String getStringRepresentation(boolean includeScheme)
      Retrieves the string representation of this AES256 password.
      Parameters:
      includeScheme - Indicates whether to include the "{AES256}" prefix at the beginning of the string representation.
      Returns:
      The string representation of this encoded password.

    • encode

      @NotNull public static AES256EncodedPassword encode(@NotNull String encryptionSettingsDefinitionID, @NotNull String encryptionSettingsDefinitionPassphrase, @NotNull String clearTextPassword) throws GeneralSecurityException, ParseException
      Encodes a password using the provided information.
      Parameters:
      encryptionSettingsDefinitionID - A string with the hexadecimal representation of the encryption settings definition whose passphrase was used to generate the encoded password. It must not be null or empty, and it must represent a valid hexadecimal string whose length is an even number less than or equal to 510 bytes.
      encryptionSettingsDefinitionPassphrase - The passphrase associated with the specified encryption settings definition. It must not be null or empty.
      clearTextPassword - The clear-text password to encode. It must not be null or empty.
      Returns:
      An object with all of the encoded password details.
      Throws:
      GeneralSecurityException - If a problem occurs while attempting to perform any of the cryptographic processing.
      ParseException - If the provided encryption settings definition ID cannot be parsed as a valid hexadecimal string.

    • encode

      @NotNull public static AES256EncodedPassword encode(@NotNull byte[] encryptionSettingsDefinitionID, @NotNull char[] encryptionSettingsDefinitionPassphrase, @NotNull byte[] clearTextPassword) throws GeneralSecurityException
      Encodes a password using the provided information.
      Parameters:
      encryptionSettingsDefinitionID - The bytes that comprise the raw encryption settings definition ID whose passphrase was used to generate the encoded password. It must not be null or empty, and its length must be less than or equal to 255 bytes.
      encryptionSettingsDefinitionPassphrase - The passphrase associated with the specified encryption settings definition. It must not be null or empty.
      clearTextPassword - The bytes that comprise the clear-text password to encode. It must not be null or empty.
      Returns:
      An object with all of the encoded password details.
      Throws:
      GeneralSecurityException - If a problem occurs while attempting to perform any of the cryptographic processing.

    • encode

      @NotNull public static AES256EncodedPassword encode(@NotNull byte[] encryptionSettingsDefinitionID, @NotNull char[] encryptionSettingsDefinitionPassphrase, @NotNull byte[] keyFactorySalt, @NotNull byte[] initializationVector, @NotNull byte[] clearTextPassword) throws GeneralSecurityException
      Encodes a password using the provided information.
      Parameters:
      encryptionSettingsDefinitionID - The bytes that comprise the raw encryption settings definition ID whose passphrase was used to generate the encoded password. It must not be null or empty, and its length must be less than or equal to 255 bytes.
      encryptionSettingsDefinitionPassphrase - The passphrase associated with the specified encryption settings definition. It must not be null or empty.
      keyFactorySalt - The salt used to generate the encryption key from the encryption settings definition passphrase. It must not be null and it must have a length of exactly 16 bytes.
      initializationVector - The initialization vector used to randomize the cipher output. It must not be [@code null} and it must have a length of exactly 16 bytes.
      clearTextPassword - The bytes that comprise the clear-text password to encode. It must not be null or empty.
      Returns:
      An object with all of the encoded password details.
      Throws:
      GeneralSecurityException - If a problem occurs while attempting to perform any of the cryptographic processing.

    • encode

      @NotNull public static AES256EncodedPassword encode(@NotNull AES256EncodedPasswordSecretKey secretKey, @NotNull byte[] initializationVector, @NotNull byte[] clearTextPassword) throws GeneralSecurityException
      Encodes a password using the provided information.
      Parameters:
      secretKey - The secret key that should be used to encrypt the password. It must not be null. The secret key can be reused when
      initializationVector - The initialization vector used to randomize the cipher output. It must not be [@code null} and it must have a length of exactly 16 bytes.
      clearTextPassword - The bytes that comprise the clear-text password to encode. It must not be null or empty.
      Returns:
      An object with all of the encoded password details.
      Throws:
      GeneralSecurityException - If a problem occurs while attempting to perform any of the cryptographic processing.

    • decode

      @NotNull public static AES256EncodedPassword decode(@NotNull String encodedPassword) throws ParseException
      Decodes the provided password into its component parts.
      Parameters:
      encodedPassword - The string representation of the encoded password to be decoded. It must not be null or empty, and it must contain the base64-encoded representation of the raw encoded password, optionally preceded by the "{AES256}" prefix.
      Returns:
      The decoded representation of the provided password.
      Throws:
      ParseException - If the provided string does not represent a valid encoded password.

    • decode

      @NotNull public static AES256EncodedPassword decode(@NotNull byte[] encodedPassword) throws ParseException
      Decodes the provided password into its component parts.
      Parameters:
      encodedPassword - The bytes that comprise the complete raw encoded representation of the password. It must not be null or empty.
      Returns:
      The decoded representation of the provided password.
      Throws:
      ParseException - If the provided string does not represent a valid encoded password.

    • decrypt

      @NotNull public byte[] decrypt(@NotNull String encryptionSettingsDefinitionPassphrase) throws GeneralSecurityException
      Decrypts this encoded password to obtain the original clear-text password used to generate it.
      Parameters:
      encryptionSettingsDefinitionPassphrase - The passphrase associated with the encryption settings definition used to encrypt the password. It must not be null or empty.
      Returns:
      The original clear-txt password used to generate this encoded representation.
      Throws:
      GeneralSecurityException - If an error occurs while attempting to decrypt the password using the provided encryption settings ID passphrase.

    • decrypt

      @NotNull public byte[] decrypt(@NotNull char[] encryptionSettingsDefinitionPassphrase) throws GeneralSecurityException
      Decrypts this encoded password to obtain the original clear-text password used to generate it.
      Parameters:
      encryptionSettingsDefinitionPassphrase - The passphrase associated with the encryption settings definition used to encrypt the password. It must not be null or empty.
      Returns:
      The original clear-txt password used to generate this encoded representation.
      Throws:
      GeneralSecurityException - If an error occurs while attempting to decrypt the password using the provided encryption settings ID passphrase.

    • decrypt

      @NotNull public byte[] decrypt(@NotNull AES256EncodedPasswordSecretKey secretKey) throws GeneralSecurityException
      Decrypts this encoded password to obtain the original clear-text password used to generate it.
      Parameters:
      secretKey - The that will be used to decrypt the password. It must not be null.
      Returns:
      The original clear-txt password used to generate this encoded representation.
      Throws:
      GeneralSecurityException - If an error occurs while attempting to decrypt the password using the provided encryption settings ID passphrase.

    • toString

      @NotNull public String toString()
      Retrieves a string representation of this AES256 password.
      Overrides:
      toString in class Object
      Returns:
      A string representation of this encoded password.

    • toString

      public void toString(@NotNull StringBuilder buffer)
      Appends a string representation of this AES256 encoded password to the provided buffer.
      Parameters:
      buffer - The buffer to which the information should be appended.