/*
* CDDL HEADER START
*
* The contents of this file are subject to the terms of the
* Common Development and Distribution License, Version 1.0 only
* (the "License"). You may not use this file except in compliance
* with the License.
*
* You can obtain a copy of the license at
* docs/licenses/cddl.txt
* or http://www.opensource.org/licenses/cddl1.php.
* See the License for the specific language governing permissions
* and limitations under the License.
*
* When distributing Covered Code, include this CDDL HEADER in each
* file and include the License file at
* docs/licenses/cddl.txt. If applicable,
* add the following below this CDDL HEADER, with the fields enclosed
* by brackets "[]" replaced with your own identifying information:
* Portions Copyright [yyyy] [name of copyright owner]
*
* CDDL HEADER END
*
*
* Portions Copyright 2013-2024 Ping Identity Corporation
*/
package com.unboundid.directory.sdk.examples;
import java.security.MessageDigest;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.Collections;
import java.util.List;
import java.util.LinkedHashMap;
import java.util.Map;
import com.unboundid.directory.sdk.common.schema.AttributeType;
import com.unboundid.directory.sdk.common.types.Entry;
import com.unboundid.directory.sdk.ds.api.EnhancedPasswordStorageScheme;
import com.unboundid.directory.sdk.ds.config.PasswordStorageSchemeConfig;
import com.unboundid.directory.sdk.ds.types.DirectoryServerContext;
import com.unboundid.ldap.sdk.Attribute;
import com.unboundid.ldap.sdk.LDAPException;
import com.unboundid.ldap.sdk.Modification;
import com.unboundid.ldap.sdk.ResultCode;
import com.unboundid.util.Base64;
import com.unboundid.util.ByteString;
import com.unboundid.util.ByteStringBuffer;
import com.unboundid.util.StaticUtils;
import com.unboundid.util.args.ArgumentException;
import com.unboundid.util.args.ArgumentParser;
import com.unboundid.util.args.StringArgument;
/**
* This class provides an example of an enhanced password storage scheme.
* Passwords will be encoded using a salted 256-bit SHA-2 digest, but the salt
* will be read from an attribute in the user's entry rather than being
* dynamically generated. As such, access to the full user entry will be
* required in order to generate the encoded password. Also note that the salt
* will not automatically be generated or written by this password storage
* scheme implementation so it must already be present in the entry, and if the
* salt is to be changed then that must be done in conjunction with changing the
* password.
* <BR><BR>
* This password storage scheme has one configuration argument:
* <UL>
* <LI>salt-attribute -- The name or OID of the attribute that will appear in
* user entries and will be used as the salt when generating an encoded
* password.</LI>
* </UL>
*/
public final class ExampleEnhancedPasswordStorageScheme
extends EnhancedPasswordStorageScheme
{
/**
* The name of the argument that will be used to specify which attribute holds
* the salt use when encoding the password.
*/
private static final String ARG_NAME_SALT_ATTRIBUTE = "salt-attribute";
/**
* The name of the digest algorithm that will be used to hash passwords.
*/
private static final String DIGEST_NAME_SHA2_256 = "SHA-256";
// The name of the attribute that should hold the salt.
private volatile String saltAttribute = null;
// The server context for the server in which this extension is running.
private DirectoryServerContext serverContext = null;
/**
* Creates a new instance of this password storage scheme. All password
* storage scheme implementations must include a default constructor, but any
* initialization should generally be done in the
* {@code initializePasswordStorageScheme} method.
*/
public ExampleEnhancedPasswordStorageScheme()
{
// No implementation required.
}
/**
* Retrieves a human-readable name for this extension.
*
* @return A human-readable name for this extension.
*/
@Override()
public String getExtensionName()
{
return "Example Enhanced Password Storage Scheme";
}
/**
* Retrieves a human-readable description for this extension. Each element
* of the array that is returned will be considered a separate paragraph in
* generated documentation.
*
* @return A human-readable description for this extension, or {@code null}
* or an empty array if no description should be available.
*/
@Override()
public String[] getExtensionDescription()
{
return new String[]
{
"This password storage scheme serves an example that may be used to " +
"demonstrate the process for creating a third-party enhanced " +
"password storage scheme. It will use a salted 256-bit SHA-2 " +
"encoding, but with the salt obtained from another attribute in " +
"the user entry rather than generated by the storage scheme."
};
}
/**
* Updates the provided argument parser to define any configuration arguments
* which may be used by this password generator. The argument parser may also
* be updated to define relationships between arguments (e.g., to specify
* required, exclusive, or dependent argument sets).
*
* @param parser The argument parser to be updated with the configuration
* arguments which may be used by this password generator.
*
* @throws ArgumentException If a problem is encountered while updating the
* provided argument parser.
*/
@Override()
public void defineConfigArguments(final ArgumentParser parser)
throws ArgumentException
{
// Add an argument that allows you to specify the attribute that holds the
// salt for encoding passwords.
final Character shortIdentifier = null;
final String longIdentifier = ARG_NAME_SALT_ATTRIBUTE;
final boolean required = true;
final int maxOccurrences = 1;
final String placeholder = "{attr}";
final String description = "The name of the attribute that holds " +
"the salt to use when encoding passwords for the user.";
parser.addArgument(new StringArgument(shortIdentifier, longIdentifier,
required, maxOccurrences, placeholder, description));
}
/**
* Initializes this password storage scheme.
*
* @param serverContext A handle to the server context for the server in
* which this extension is running.
* @param config The general configuration for this password storage
* scheme.
* @param parser The argument parser which has been initialized from
* the configuration for this password storage scheme.
*
* @throws LDAPException If a problem occurs while initializing this
* password storage scheme.
*/
@Override()
public void initializePasswordStorageScheme(
final DirectoryServerContext serverContext,
final PasswordStorageSchemeConfig config,
final ArgumentParser parser)
throws LDAPException
{
serverContext.debugInfo("Beginning password storage scheme initialization");
this.serverContext = serverContext;
final StringArgument saltAttrArg =
(StringArgument) parser.getNamedArgument(ARG_NAME_SALT_ATTRIBUTE);
saltAttribute = saltAttrArg.getValue();
}
/**
* Indicates whether the configuration contained in the provided argument
* parser represents a valid configuration for this extension.
*
* @param config The general configuration for this password
* storage scheme.
* @param parser The argument parser which has been initialized
* with the proposed configuration.
* @param unacceptableReasons A list that can be updated with reasons that
* the proposed configuration is not acceptable.
*
* @return {@code true} if the proposed configuration is acceptable, or
* {@code false} if not.
*/
@Override()
public boolean isConfigurationAcceptable(
final PasswordStorageSchemeConfig config,
final ArgumentParser parser,
final List<String> unacceptableReasons)
{
boolean acceptable = true;
// The salt attribute must be defined in the server schema.
final StringArgument saltAttrArg =
(StringArgument) parser.getNamedArgument(ARG_NAME_SALT_ATTRIBUTE);
final AttributeType saltAttrType =
config.getServerContext().getSchema().getAttributeType(
saltAttrArg.getValue(), false);
if (saltAttrType == null)
{
acceptable = false;
unacceptableReasons.add("The salt attribute is not defined in the " +
"server schema.");
}
return acceptable;
}
/**
* Attempts to apply the configuration contained in the provided argument
* parser.
*
* @param config The general configuration for this password
* storage scheme.
* @param parser The argument parser which has been
* initialized with the new configuration.
* @param adminActionsRequired A list that can be updated with information
* about any administrative actions that may be
* required before one or more of the
* configuration changes will be applied.
* @param messages A list that can be updated with information
* about the result of applying the new
* configuration.
*
* @return A result code that provides information about the result of
* attempting to apply the configuration change.
*/
@Override()
public ResultCode applyConfiguration(final PasswordStorageSchemeConfig config,
final ArgumentParser parser,
final List<String> adminActionsRequired,
final List<String> messages)
{
final StringArgument saltAttrArg =
(StringArgument) parser.getNamedArgument(ARG_NAME_SALT_ATTRIBUTE);
saltAttribute = saltAttrArg.getValue();
return ResultCode.SUCCESS;
}
/**
* Performs any cleanup which may be necessary when this password storage
* scheme is to be taken out of service.
*/
@Override()
public void finalizePasswordStorageScheme()
{
// No finalization is required.
}
/**
* Retrieves the name for this password storage scheme. This will be the
* identifier which appears in curly braces at the beginning of the encoded
* password. The name should not include curly braces.
*
* @return The name for this password storage scheme.
*/
@Override()
public String getStorageSchemeName()
{
// We'll call this algorithm "ESSHA256", for "externally-salted SHA-256".
return "ESSHA256";
}
/**
* Indicates whether this password storage scheme encodes passwords in a form
* that allows the original plaintext value to be obtained from the encoded
* representation.
*
* @return {@code true} if the original plaintext password may be obtained
* from the encoded password, or {@code false} if not.
*/
@Override()
public boolean isReversible()
{
// This algorithm is not reversible.
return false;
}
/**
* Indicates whether this password storage scheme encodes passwords in a form
* that may be considered secure. A storage scheme should only be considered
* secure if it is not possible to trivially determine a clear-text value
* which may be used to generate a given encoded representation.
*
* @return {@code true} if this password storage scheme may be considered
* secure, or {@code false} if not.
*/
@Override()
public boolean isSecure()
{
// This algorithm may be considered secure.
return true;
}
/**
* Indicates whether this password storage scheme requires access to the user
* entry in order to perform processing. If the storage scheme does require
* access to the user entry (e.g., in order to obtain key or salt information
* from another attribute, or to use information in the entry to access
* information in another data store), then some features (e.g., the ability
* to perform extensible matching with password values, or the ability to use
* the encode-password tool to encode and compare passwords) may not be
* available.
*
* @return {@code true} if this password storage scheme requires access to
* the user entry, or {@code false} if not.
*/
@Override()
public boolean requiresUserEntry()
{
// This password storage scheme does require access to the user entry.
return true;
}
/**
* Encodes the provided plaintext password for this storage scheme,
* without the name of the associated scheme. Note that the
* provided plaintext password should not be altered in any way.
*
* @param plaintext The plaintext password to be encoded. It must not
* be {@code null}. Note that there is no guarantee
* that password validators have yet been invoked for
* this password, so this password storage scheme
* implementation should not make any assumptions about
* the format of the plaintext password or whether it
* will actually be allowed for use in the entry.
* @param userEntry The complete entry for the user for whom the
* password is to be encoded. This will not be
* {@code null} for schemes in which
* {@link #requiresUserEntry} returns {@code true}.
* @param modifications The set of modifications to be applied to the user
* entry. This will generally be non-{@code null} only
* for operations that use a modify to change the user
* password.
* @param deterministic Indicates whether the password encoding should be
* deterministic. If this is {@code true}, then the
* scheme should attempt to generate a consistent
* encoding for the password (e.g., by determining the
* salt from a normalized representation of the user's
* DN). This may not be supported by all schemes.
* @param includeScheme Indicates whether to include the name of the scheme
* in curly braces before the encoded password.
*
* @return The password that has been encoded using this storage
* scheme.
*
* @throws LDAPException If a problem occurs while attempting to encode the
* password.
*/
@Override()
public ByteString encodePassword(final ByteString plaintext,
final Entry userEntry,
final List<Modification> modifications,
final boolean deterministic,
final boolean includeScheme)
throws LDAPException
{
final ByteStringBuffer buffer = new ByteStringBuffer();
if (includeScheme)
{
buffer.append('{');
buffer.append(getStorageSchemeName());
buffer.append('}');
}
final byte[] saltBytes = getSalt(userEntry, modifications);
encode(plaintext, saltBytes, buffer);
return buffer.toByteString();
}
/**
* Indicates whether the provided plaintext password could have been used to
* generate the given encoded password.
*
* @param plaintextPassword The plaintext password provided by the user as
* part of a simple bind attempt.
* @param storedPassword The stored password to compare against the
* provided plaintext password.
* @param userEntry The complete entry for the user for whom the
* password is to be validated. This will not be
* {@code null} for schemes in which
* {@link #requiresUserEntry} returns {@code true}.
*
* @return {@code true} if the provided clear-text password could have been
* used to generate the encoded password, or {@code false} if not.
*/
@Override()
public boolean passwordMatches(final ByteString plaintextPassword,
final ByteString storedPassword,
final Entry userEntry)
{
try
{
final byte[] saltBytes = getSalt(userEntry, null);
final ByteStringBuffer buffer = new ByteStringBuffer();
encode(plaintextPassword, saltBytes, buffer);
return Arrays.equals(buffer.toByteArray(), storedPassword.getValue());
}
catch (final Exception e)
{
serverContext.debugCaught(e);
return false;
}
}
/**
* Attempts to determine the plaintext password used to generate the provided
* encoded password. This method should only be called if the
* {@link #isReversible} method returns {@code true}.
*
* @param storedPassword The password for which to obtain the plaintext
* value. It should not include the scheme name in
* curly braces.
* @param userEntry The complete entry for the user for whom the
* password is to be validated. This will not be
* {@code null} for schemes in which
* {@link #requiresUserEntry} returns {@code true}.
*
* @return The plaintext password obtained from the given encoded password.
*
* @throws LDAPException If this password storage scheme is not reversible,
* or if the provided value could not be decoded to
* its plaintext representation.
*/
@Override()
public ByteString getPlaintextValue(final ByteString storedPassword,
final Entry userEntry)
throws LDAPException
{
throw new LDAPException(ResultCode.OTHER,
"Passwords encoded with the '" + getStorageSchemeName() +
"' scheme are not reversible.");
}
/**
* Indicates whether this password storage scheme provides the ability to
* encode passwords in the authentication password syntax as described in RFC
* 3112.
*
* @return {@code true} if this password storage scheme supports the
* authentication password syntax, or {@code false} if not.
*/
@Override()
public boolean supportsAuthPasswordSyntax()
{
// This password storage scheme does not support the authentication password
// syntax. As such, we don't need to implement any of the other methods
// that deal with it.
return false;
}
/**
* Retrieves the salt to use for password encoding. If modifications are
* available, then they will be checked first.
*
* @param userEntry The entry for the user for whom the salt is to be
* obtained.
* @param mods An optional set of modifications for the user.
*
* @return The salt to use for password encoding.
*
* @throws LDAPException If a problem is encountered while obtaining the
* salt.
*/
private byte[] getSalt(final Entry userEntry, final List<Modification> mods)
throws LDAPException
{
// The user entry must have been provided. Since requiresUserEntry returns
// true for this class, it should always be available, but we can guard
// against it being null just in case.
if (userEntry == null)
{
throw new LDAPException(ResultCode.OTHER,
"Unable to encode a new " + getStorageSchemeName() +
" password because no user entry was provided.");
}
// If any modifications were provided, then see if any of them affect the
// salt. If so, then apply just those modifications to the user entry.
final Attribute saltAttr;
if (mods != null)
{
final ArrayList<Modification> applyMods =
new ArrayList<Modification>(mods.size());
for (final Modification m : mods)
{
if (m.getAttributeName().equalsIgnoreCase(saltAttribute))
{
applyMods.add(m);
}
}
if (applyMods.isEmpty())
{
saltAttr = userEntry.getAttribute(saltAttribute,
Collections.<String>emptySet());
}
else
{
com.unboundid.ldap.sdk.Entry sdkEntry = userEntry.toLDAPSDKEntry();
sdkEntry = com.unboundid.ldap.sdk.Entry.applyModifications(sdkEntry,
true, applyMods);
saltAttr = sdkEntry.getAttribute(saltAttribute);
}
}
else
{
saltAttr = userEntry.getAttribute(saltAttribute,
Collections.<String>emptySet());
}
if (saltAttr == null)
{
throw new LDAPException(ResultCode.OTHER,
"No salt found in attribute '" + saltAttribute + "' in entry '" +
userEntry.getDN() + "'.");
}
if (saltAttr.size() != 1)
{
throw new LDAPException(ResultCode.OTHER,
"Entry '" + userEntry.getDN() + "' does not have exactly one " +
"value for salt attribute '" + saltAttribute + "'.");
}
return saltAttr.getValueByteArray();
}
/**
* Appends an encoded representation of the given password and salt to the
* provided buffer.
*
* @param password The clear-text password to be encoded.
* @param salt The bytes to use as the salt.
* @param buffer The buffer to which the encoded representation should be
* appended.
*
* @throws LDAPException If a problem is encountered while encoding the
* password.
*/
private void encode(final ByteString password, final byte[] salt,
final ByteStringBuffer buffer)
throws LDAPException
{
// Generate an array with the bytes of the password and the salt.
final byte[] pwBytes = password.getValue();
final byte[] pwPlusSalt = new byte[pwBytes.length + salt.length];
System.arraycopy(pwBytes, 0, pwPlusSalt, 0, pwBytes.length);
System.arraycopy(salt, 0, pwPlusSalt, pwBytes.length, salt.length);
// Generate a 256-bit SHA-2 digest of the password plus the salt.
final MessageDigest sha256Digest;
try
{
sha256Digest = MessageDigest.getInstance(DIGEST_NAME_SHA2_256);
}
catch (final Exception e)
{
serverContext.debugCaught(e);
throw new LDAPException(ResultCode.OTHER,
"Unable to obtain a " + DIGEST_NAME_SHA2_256 + " digest: " +
StaticUtils.getExceptionMessage(e),
e);
}
final byte[] digestBytes = sha256Digest.digest(pwPlusSalt);
// Append a base64-encoded representation of the digest bytes to the given
// buffer.
Base64.encode(digestBytes, buffer);
}
/**
* {@inheritDoc}
*/
@Override()
public Map<List<String>,String> getExamplesArgumentSets()
{
final LinkedHashMap<List<String>,String> examples =
new LinkedHashMap<List<String>,String>(1);
examples.put(
Arrays.asList(ARG_NAME_SALT_ATTRIBUTE + "=exampleAttr"),
"Encode passwords using the 256-bit SHA-2 digest, obtaining " +
"salt values from the 'exampleAttr' attribute of the user " +
"entry.");
return examples;
}
}
