com.unboundid.ldap.listener

Class SaltedMessageDigestInMemoryPasswordEncoder

java.lang.Object

com.unboundid.ldap.listener.InMemoryPasswordEncoder

com.unboundid.ldap.listener.SaltedMessageDigestInMemoryPasswordEncoder

@ThreadSafety(level=NOT_THREADSAFE)
public final class SaltedMessageDigestInMemoryPasswordEncoder
extends InMemoryPasswordEncoder

This class provides an implementation of an in-memory directory server password encoder that uses a message digest to encode passwords. Encoded passwords will also include some number of randomly generated bytes, called a salt, to ensure that encoding the same password multiple times will yield multiple different encoded representations.

Constructor Summary

Constructors

Constructor and Description
SaltedMessageDigestInMemoryPasswordEncoder(java.lang.String prefix, PasswordEncoderOutputFormatter outputFormatter, java.security.MessageDigest messageDigest, int numSaltBytes, boolean saltAfterClearPassword, boolean saltAfterMessageDigest) Creates a new instance of this in-memory directory server password encoder with the provided information.

Method Summary

Modifier and Type	Method and Description
protected byte[]	encodePassword(byte[] clearPassword, ReadOnlyEntry userEntry, java.util.List<Modification> modifications) Encodes the provided clear-text password for storage in the in-memory directory server.
protected void	ensurePreEncodedPasswordAppearsValid(byte[] unPrefixedUnFormattedEncodedPasswordBytes, ReadOnlyEntry userEntry, java.util.List<Modification> modifications) Verifies that the provided pre-encoded password (with the prefix removed and any output formatting reverted) is compatible with the validation performed by this password encoder.
protected byte[]	extractClearPassword(byte[] unPrefixedUnFormattedEncodedPasswordBytes, ReadOnlyEntry userEntry) Attempts to extract the clear-text password used to generate the provided encoded representation, if possible.
java.lang.String	getDigestAlgorithm() Retrieves the digest algorithm that will be used when encoding passwords.
int	getDigestLengthBytes() Retrieves the digest length, in bytes.
int	getNumSaltBytes() Retrieves the number of bytes of salt that will be generated when encoding a password.
boolean	isSaltAfterClearPassword() Indicates whether the salt should be appended or prepended to the clear-text password when computing the message digest.
boolean	isSaltAfterMessageDigest() Indicates whether the salt should be appended or prepended to the digest when generating the encoded representation for the password.
protected boolean	passwordMatches(byte[] clearPasswordBytes, byte[] unPrefixedUnFormattedEncodedPasswordBytes, ReadOnlyEntry userEntry) Indicates whether the provided clear-text password could have been used to generate the given encoded password.
void	toString(java.lang.StringBuilder buffer) Appends a string representation of this password encoder to the provided buffer.

Methods inherited from class com.unboundid.ldap.listener.InMemoryPasswordEncoder

clearPasswordMatchesEncodedPassword, encodePassword, ensurePreEncodedPasswordAppearsValid, extractClearPasswordFromEncodedPassword, getOutputFormatter, getPrefix, passwordStartsWithPrefix, toString

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

SaltedMessageDigestInMemoryPasswordEncoder

public SaltedMessageDigestInMemoryPasswordEncoder(@NotNull
                                                  java.lang.String prefix,
                                                  @Nullable
                                                  PasswordEncoderOutputFormatter outputFormatter,
                                                  @NotNull
                                                  java.security.MessageDigest messageDigest,
                                                  int numSaltBytes,
                                                  boolean saltAfterClearPassword,
                                                  boolean saltAfterMessageDigest)

Creates a new instance of this in-memory directory server password encoder with the provided information.

Parameters:

prefix - The string that will appear at the beginning of encoded passwords. It must not be null or empty.

outputFormatter - The output formatter that will be used to format the encoded representation of clear-text passwords. It may be null if no special formatting should be applied to the raw bytes.

messageDigest - The message digest that will be used to actually perform the encoding. It must not be null.

numSaltBytes - The number of salt bytes to generate when encoding passwords. It must be greater than zero.

saltAfterClearPassword - Indicates whether the salt should be placed after or before the clear-text password when computing the message digest. If this is true, then the digest will be computed from the concatenation of the clear-text password and the salt, in that order. If this is false, then the digest will be computed from the concatenation of the salt and the clear-text password.

saltAfterMessageDigest - Indicates whether the salt should be placed after or before the computed digest when creating the encoded representation. If this is true, then the encoded password will consist of the concatenation of the computed message digest and the salt, in that order. If this is false, then the encoded password will consist of the concatenation of the salt and the message digest.

Method Detail

getDigestAlgorithm

@NotNull
public java.lang.String getDigestAlgorithm()

Retrieves the digest algorithm that will be used when encoding passwords.

Returns:

The message digest

getDigestLengthBytes

public int getDigestLengthBytes()

Retrieves the digest length, in bytes.

Returns:

The digest length, in bytes.

getNumSaltBytes

public int getNumSaltBytes()

Retrieves the number of bytes of salt that will be generated when encoding a password. Note that this is used only when encoding new clear-text passwords. When comparing a clear-text password against an existing encoded representation, the number of salt bytes from the existing encoded password will be used.

Returns:

The number of bytes of salt that will be generated when encoding a password.

isSaltAfterClearPassword

public boolean isSaltAfterClearPassword()

Indicates whether the salt should be appended or prepended to the clear-text password when computing the message digest.

Returns:

true if the salt should be appended to the clear-text password when computing the message digest, or false if the salt should be prepended to the clear-text password.

isSaltAfterMessageDigest

public boolean isSaltAfterMessageDigest()

Indicates whether the salt should be appended or prepended to the digest when generating the encoded representation for the password.

Returns:

true if the salt should be appended to the digest when generating the encoded representation for the password, or false if the salt should be prepended to the digest.

encodePassword

@NotNull
protected byte[] encodePassword(@NotNull
                                         byte[] clearPassword,
                                         @NotNull
                                         ReadOnlyEntry userEntry,
                                         @NotNull
                                         java.util.List<Modification> modifications)
                                  throws LDAPException

Encodes the provided clear-text password for storage in the in-memory directory server. The encoded password that is returned must not include the prefix, and no output formatting should have been applied.

This method will be invoked when adding data into the server, including through LDAP add operations or LDIF imports, and when modifying existing entries through LDAP modify operations.

Specified by:

encodePassword in class InMemoryPasswordEncoder

Parameters:

clearPassword - The bytes that comprise the clear-text password to be encoded. It must not be null or empty.

userEntry - The entry in which the encoded password will appear. It must not be null. If the entry is in the process of being modified, then this will be a representation of the entry as it appeared before any changes have been applied.

modifications - A set of modifications to be applied to the user entry. It must not be [@code null}. It will be an empty list for entries created via LDAP add and LDIF import operations. It will be a non-empty list for LDAP modifications.

Returns:

The bytes that comprise encoded representation of the provided clear-text password, without the prefix, and without any output formatting applied.

Throws:

LDAPException - If a problem is encountered while trying to encode the provided clear-text password.

ensurePreEncodedPasswordAppearsValid

protected void ensurePreEncodedPasswordAppearsValid(@NotNull
                                                    byte[] unPrefixedUnFormattedEncodedPasswordBytes,
                                                    @NotNull
                                                    ReadOnlyEntry userEntry,
                                                    @NotNull
                                                    java.util.List<Modification> modifications)
                                             throws LDAPException

Verifies that the provided pre-encoded password (with the prefix removed and any output formatting reverted) is compatible with the validation performed by this password encoder.

Note that this method should return true if the provided unPrefixedUnFormattedEncodedPasswordBytes value could be used in conjunction with the InMemoryPasswordEncoder.passwordMatches(byte[], byte[], com.unboundid.ldap.sdk.ReadOnlyEntry) method, even if it does not exactly match the format of the output that would have been generated by the InMemoryPasswordEncoder.encodePassword(com.unboundid.asn1.ASN1OctetString, com.unboundid.ldap.sdk.ReadOnlyEntry, java.util.List<com.unboundid.ldap.sdk.Modification>) method. For example, if this password encoder uses a salt, then it may be desirable to accept passwords encoded with a salt that has a different length than the encodePassword method would use when encoding a clear-test password. This may allow the in-memory directory server to support pre-encoded passwords generated from other types of directory servers that may use different settings when encoding passwords, but still generates encoded passwords that are compatible with this password encoder.

Specified by:

ensurePreEncodedPasswordAppearsValid in class InMemoryPasswordEncoder

Parameters:

unPrefixedUnFormattedEncodedPasswordBytes - The bytes that comprise the pre-encoded password to validate, with the prefix stripped off and the output formatting reverted.

userEntry - The entry in which the password will appear. It must not be null. If the entry is in the process of being modified, then this will be a representation of the entry as it appeared before any changes have been applied.

modifications - A set of modifications to be applied to the user entry. It must not be [@code null}. It will be an empty list for entries created via LDAP add and LDIF import operations. It will be a non-empty list for LDAP modifications.

Throws:

LDAPException - If the provided encoded password is not compatible with the validation performed by this password encoder, or if a problem is encountered while making the determination.

passwordMatches

protected boolean passwordMatches(@NotNull
                                  byte[] clearPasswordBytes,
                                  @NotNull
                                  byte[] unPrefixedUnFormattedEncodedPasswordBytes,
                                  @NotNull
                                  ReadOnlyEntry userEntry)
                           throws LDAPException

Indicates whether the provided clear-text password could have been used to generate the given encoded password. This method will be invoked when verifying a provided clear-text password during bind processing, or when removing an existing password in a modify operation.

Specified by:

passwordMatches in class InMemoryPasswordEncoder

Parameters:

clearPasswordBytes - The bytes that comprise the clear-text password to be compared against the encoded password. It must not be null or empty.

unPrefixedUnFormattedEncodedPasswordBytes - The bytes that comprise the encoded password, with the prefix stripped off and the output formatting reverted.

userEntry - The entry in which the encoded password appears. It must not be null.

Returns:

true if the provided clear-text password could have been used to generate the given encoded password, or false if not.

Throws:

LDAPException - If a problem is encountered while attempting to make the determination.

extractClearPassword

@NotNull
protected byte[] extractClearPassword(@NotNull
                                               byte[] unPrefixedUnFormattedEncodedPasswordBytes,
                                               @NotNull
                                               ReadOnlyEntry userEntry)
                                        throws LDAPException

Attempts to extract the clear-text password used to generate the provided encoded representation, if possible. Many password encoder implementations may use one-way encoding mechanisms, so it will often not be possible to obtain the original clear-text password from its encoded representation.

Specified by:

extractClearPassword in class InMemoryPasswordEncoder

Parameters:

unPrefixedUnFormattedEncodedPasswordBytes - The bytes that comprise the encoded password, with the prefix stripped off and the output formatting reverted.

userEntry - The entry in which the encoded password appears. It must not be null.

Returns:

The clear-text password used to generate the provided encoded representation.

Throws:

LDAPException - If this password encoder is not reversible, or if a problem occurs while trying to extract the clear-text representation from the provided encoded password.

toString

public void toString(@NotNull
                     java.lang.StringBuilder buffer)

Appends a string representation of this password encoder to the provided buffer.

Specified by:

toString in class InMemoryPasswordEncoder

Parameters:

buffer - The buffer to which the information should be appended.