Class AES256EncodedPassword

  • All Implemented Interfaces:
    java.io.Serializable

    @NotMutable
    @ThreadSafety(level=COMPLETELY_THREADSAFE)
    public final class AES256EncodedPassword
    extends java.lang.Object
    implements java.io.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:
    Serialized Form
    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      static AES256EncodedPassword decode​(byte[] encodedPassword)
      Decodes the provided password into its component parts.
      static AES256EncodedPassword decode​(java.lang.String encodedPassword)
      Decodes the provided password into its component parts.
      byte[] decrypt​(char[] encryptionSettingsDefinitionPassphrase)
      Decrypts this encoded password to obtain the original clear-text password used to generate it.
      byte[] decrypt​(AES256EncodedPasswordSecretKey secretKey)
      Decrypts this encoded password to obtain the original clear-text password used to generate it.
      byte[] decrypt​(java.lang.String encryptionSettingsDefinitionPassphrase)
      Decrypts this encoded password to obtain the original clear-text password used to generate it.
      static AES256EncodedPassword encode​(byte[] encryptionSettingsDefinitionID, char[] encryptionSettingsDefinitionPassphrase, byte[] clearTextPassword)
      Encodes a password using the provided information.
      static AES256EncodedPassword encode​(byte[] encryptionSettingsDefinitionID, char[] encryptionSettingsDefinitionPassphrase, byte[] keyFactorySalt, byte[] initializationVector, byte[] clearTextPassword)
      Encodes a password using the provided information.
      static AES256EncodedPassword encode​(AES256EncodedPasswordSecretKey secretKey, byte[] initializationVector, byte[] clearTextPassword)
      Encodes a password using the provided information.
      static AES256EncodedPassword encode​(java.lang.String encryptionSettingsDefinitionID, java.lang.String encryptionSettingsDefinitionPassphrase, java.lang.String clearTextPassword)
      Encodes a password using the provided information.
      byte[] getEncodedRepresentation()
      Retrieves the bytes that comprise the complete raw encoded representation of the password.
      int getEncodingVersion()
      Retrieves the encoding version for this encoded password.
      byte[] getEncryptionSettingsDefinitionIDBytes()
      Retrieves the bytes that comprise the raw ID of the encryption settings definition whose passphrase is used to generate the encryption key.
      java.lang.String getEncryptionSettingsDefinitionIDString()
      Retrieves a string representation of the ID of the encryption settings definition whose passphrase is used to generate the encryption key.
      byte[] getInitializationVector()
      Retrieves the initialization vector used to randomize the cipher output.
      byte[] getKeyFactorySalt()
      Retrieves the salt used to generate the encryption key from the encryption settings definition passphrase.
      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.
      java.lang.String getStringRepresentation​(boolean includeScheme)
      Retrieves the string representation of this AES256 password.
      java.lang.String toString()
      Retrieves a string representation of this AES256 password.
      void toString​(java.lang.StringBuilder buffer)
      Appends a string representation of this AES256 encoded password to the provided buffer.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
    • Method Detail

      • 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 java.lang.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 java.lang.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
                                                   java.lang.String encryptionSettingsDefinitionID,
                                                   @NotNull
                                                   java.lang.String encryptionSettingsDefinitionPassphrase,
                                                   @NotNull
                                                   java.lang.String clearTextPassword)
                                            throws java.security.GeneralSecurityException,
                                                   java.text.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:
        java.security.GeneralSecurityException - If a problem occurs while attempting to perform any of the cryptographic processing.
        java.text.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 java.security.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:
        java.security.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 java.security.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:
        java.security.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 java.security.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:
        java.security.GeneralSecurityException - If a problem occurs while attempting to perform any of the cryptographic processing.
      • decode

        @NotNull
        public static AES256EncodedPassword decode​(@NotNull
                                                   java.lang.String encodedPassword)
                                            throws java.text.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:
        java.text.ParseException - If the provided string does not represent a valid encoded password.
      • decode

        @NotNull
        public static AES256EncodedPassword decode​(@NotNull
                                                   byte[] encodedPassword)
                                            throws java.text.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:
        java.text.ParseException - If the provided string does not represent a valid encoded password.
      • decrypt

        @NotNull
        public byte[] decrypt​(@NotNull
                              java.lang.String encryptionSettingsDefinitionPassphrase)
                       throws java.security.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:
        java.security.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 java.security.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:
        java.security.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 java.security.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:
        java.security.GeneralSecurityException - If an error occurs while attempting to decrypt the password using the provided encryption settings ID passphrase.
      • toString

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

        public void toString​(@NotNull
                             java.lang.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.