com.unboundid.ldap.sdk.unboundidds

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:

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

Field Summary

Fields

Modifier and Type	Field and 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

Modifier and Type	Method and 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(AES256EncodedPasswordSecretKey secretKey) Decrypts this encoded password to obtain the original clear-text password used to generate it.
byte[]	decrypt(char[] encryptionSettingsDefinitionPassphrase) 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(AES256EncodedPasswordSecretKey secretKey, byte[] initializationVector, byte[] clearTextPassword) Encodes a password using the provided information.
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(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

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 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.