Class AES256EncodedPassword
- java.lang.Object
-
- com.unboundid.ldap.sdk.unboundidds.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:-
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
- 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.
- 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.
- 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.
- The bytes that comprise the raw ID of the encryption settings definition whose passphrase will be used to generate the encryption key.
- 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
-
-
Field Summary
Fields Modifier and Type Field Description static int
ENCODING_VERSION_0
The integer value for encoding version 0.static java.lang.String
ENCODING_VERSION_0_CIPHER_ALGORITHM
The name of the cipher algorithm that should be used with an encoding version of zero.static java.lang.String
ENCODING_VERSION_0_CIPHER_TRANSFORMATION
The name of the cipher transformation that should be used with an encoding version of zero.static int
ENCODING_VERSION_0_GCM_TAG_LENGTH_BITS
The GCM tag length in bits to use with an encoding version of zero.static int
ENCODING_VERSION_0_GENERATED_KEY_LENGTH_BITS
The generated secret key length in bits to use with an encoding version of zero.static int
ENCODING_VERSION_0_IV_LENGTH_BYTES
The size in bytes to use for the initialization vector with an encoding version of zero.static java.lang.String
ENCODING_VERSION_0_KEY_FACTORY_ALGORITHM
The name of the key factory algorithm should be used with an encoding version of zero.static int
ENCODING_VERSION_0_KEY_FACTORY_ITERATION_COUNT
The key factory iteration count to use with an encoding version of zero.static int
ENCODING_VERSION_0_KEY_FACTORY_SALT_LENGTH_BYTES
The size in bytes to use for the key factory salt with an encoding version of zero.static byte
ENCODING_VERSION_0_MASK
The bitmask that will be used to indicate an encoding version of zero.static int
ENCODING_VERSION_0_PADDING_MODULUS
The padding modulus to use with an encoding version of zero.static java.lang.String
PASSWORD_STORAGE_SCHEME_PREFIX
The prefix that will appear at the beginning of the string representation for an encoded password.
-
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.
-
-
-
Field Detail
-
ENCODING_VERSION_0_MASK
public static final byte ENCODING_VERSION_0_MASK
The bitmask that will be used to indicate an encoding version of zero. Only the most significant four bits of this byte will be used. The least significant four bits of the first byte will be used to indicate the number of padding bytes that must be appended to the clear-text password to make its length a multiple of sixteen bytes.- See Also:
- Constant Field Values
-
ENCODING_VERSION_0
public static final int ENCODING_VERSION_0
The integer value for encoding version 0.- See Also:
- Constant Field Values
-
ENCODING_VERSION_0_GCM_TAG_LENGTH_BITS
public static final int ENCODING_VERSION_0_GCM_TAG_LENGTH_BITS
The GCM tag length in bits to use with an encoding version of zero.- See Also:
- Constant Field Values
-
ENCODING_VERSION_0_GENERATED_KEY_LENGTH_BITS
public static final int ENCODING_VERSION_0_GENERATED_KEY_LENGTH_BITS
The generated secret key length in bits to use with an encoding version of zero.- See Also:
- Constant Field Values
-
ENCODING_VERSION_0_IV_LENGTH_BYTES
public static final int ENCODING_VERSION_0_IV_LENGTH_BYTES
The size in bytes to use for the initialization vector with an encoding version of zero.- See Also:
- Constant Field Values
-
ENCODING_VERSION_0_KEY_FACTORY_ITERATION_COUNT
public static final int ENCODING_VERSION_0_KEY_FACTORY_ITERATION_COUNT
The key factory iteration count to use with an encoding version of zero.- See Also:
- Constant Field Values
-
ENCODING_VERSION_0_KEY_FACTORY_SALT_LENGTH_BYTES
public static final int ENCODING_VERSION_0_KEY_FACTORY_SALT_LENGTH_BYTES
The size in bytes to use for the key factory salt with an encoding version of zero.- See Also:
- Constant Field Values
-
ENCODING_VERSION_0_PADDING_MODULUS
public static final int ENCODING_VERSION_0_PADDING_MODULUS
The padding modulus to use with an encoding version of zero.- See Also:
- Constant Field Values
-
ENCODING_VERSION_0_CIPHER_ALGORITHM
@NotNull public static final java.lang.String ENCODING_VERSION_0_CIPHER_ALGORITHM
The name of the cipher algorithm that should be used with an encoding version of zero.- See Also:
- Constant Field Values
-
ENCODING_VERSION_0_CIPHER_TRANSFORMATION
@NotNull public static final java.lang.String ENCODING_VERSION_0_CIPHER_TRANSFORMATION
The name of the cipher transformation that should be used with an encoding version of zero.- See Also:
- Constant Field Values
-
ENCODING_VERSION_0_KEY_FACTORY_ALGORITHM
@NotNull public static final java.lang.String ENCODING_VERSION_0_KEY_FACTORY_ALGORITHM
The name of the key factory algorithm should be used with an encoding version of zero.- See Also:
- Constant Field Values
-
PASSWORD_STORAGE_SCHEME_PREFIX
@NotNull public static final java.lang.String PASSWORD_STORAGE_SCHEME_PREFIX
The prefix that will appear at the beginning of the string representation for an encoded password.- See Also:
- Constant Field Values
-
-
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 benull
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 benull
or empty.clearTextPassword
- The clear-text password to encode. It must not benull
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 benull
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 benull
or empty.clearTextPassword
- The bytes that comprise the clear-text password to encode. It must not benull
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 benull
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 benull
or empty.keyFactorySalt
- The salt used to generate the encryption key from the encryption settings definition passphrase. It must not benull
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 benull
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 benull
. The secret key can be reused wheninitializationVector
- 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 benull
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 benull
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 benull
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 benull
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 benull
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 benull
.- 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 classjava.lang.Object
- Returns:
- A string representation of this encoded password.
-
-