com.unboundid.directory.sdk.ds.api

Class PasswordStorageScheme

java.lang.Object

com.unboundid.directory.sdk.ds.api.PasswordStorageScheme

All Implemented Interfaces:

Configurable, ExampleUsageProvider, Reconfigurable<PasswordStorageSchemeConfig>, UnboundIDExtension

@Extensible
 @DirectoryServerExtension
 @DirectoryProxyServerExtension(appliesToLocalContent=true,
                               appliesToRemoteContent=false)
 @SynchronizationServerExtension(appliesToLocalContent=true,
                                appliesToSynchronizedContent=false)
 @ThreadSafety(level=INTERFACE_THREADSAFE)
public abstract class PasswordStorageScheme
extends java.lang.Object
implements UnboundIDExtension, Reconfigurable<PasswordStorageSchemeConfig>, ExampleUsageProvider

NOTE: The EnhancedPasswordStorageScheme class provides both a simpler and more functional API for interacting with passwords. It may be desirable for new storage scheme implementations to implement that API rather than this older version.

This class defines an API that must be implemented by extensions which may be used to encode passwords for storage in the server. Ideally, encoded passwords should be stored in a secure manner so that anyone with access to the encoded password will not be able to determine the clear-text password with which it is associated (e.g., using a one-way message digest, or using reversible encryption with a securely-obtained key). Passwords are not required to be stored in a reversible form that allows the server to determine the clear-text password used to generate an encoded representation as long as it is possible to determine whether a given clear-text password may be used to generate a provided encoded representation.

Encoded passwords may taken one of two forms. The first is the "user password" syntax, in which the encoded password is represented by the name of the storage scheme in curly braces followed by the transformed password (e.g., "{scheme}encoded"). This format isn't based on any defined standard, but is commonly used by a number of directory server implementations. The second format is the authentication password syntax as described in RFC 3112, in which the encoded representation is broken into scheme, authInfo, and authValue segments separated by dollar signs (e.g., "scheme$authInfo$authValue"). All password storage schemes are required to support the "user password" syntax and may optionally also support the authentication password syntax.

Configuring Password Storage Schemes

In order to configure a password storage scheme created using this API, use a command like:

      dsconfig create-password-storage-scheme \
           --scheme-name "{scheme-name}" \
           --type third-party \
           --set enabled:true \
           --set "extension-class:{class-name}" \
           --set "extension-argument:{name=value}"
 

where "{scheme-name}" is the name to use for the password storage scheme instance, "{class-name}" is the fully-qualified name of the Java class that extends com.unboundid.directory.sdk.ds.api.PasswordStorageScheme, and "{name=value}" represents name-value pairs for any arguments to provide to the password storage scheme. If multiple arguments should be provided to the password storage scheme, then the "--set extension-argument:{name=value}" option should be provided multiple times.

See Also:

EnhancedPasswordStorageScheme

Constructor Summary

Constructors

Constructor and Description
PasswordStorageScheme() Creates a new instance of this password storage scheme.

Method Summary

Modifier and Type	Method and Description
ResultCode	applyConfiguration(PasswordStorageSchemeConfig config, ArgumentParser parser, java.util.List<java.lang.String> adminActionsRequired, java.util.List<java.lang.String> messages) Attempts to apply the configuration from the provided argument parser to this extension.
boolean	authPasswordMatches(ByteString plaintext, java.lang.String authInfo, java.lang.String authValue) Indicates whether the provided plaintext password may be used to generate an encoded password with the given authInfo and authValue elements when using the authentication password syntax as defined in RFC 3112.
void	defineConfigArguments(ArgumentParser parser) Updates the provided argument parser to define any configuration arguments which may be used by this extension.
ByteString	encodeAuthPassword(ByteString plaintext) Encodes the provided plaintext password using the authentication password syntax as defined in RFC 3112.
abstract ByteString	encodePassword(ByteString plaintext) Encodes the provided plaintext password.
ByteString	encodePasswordWithScheme(ByteString plaintext) Encodes the provided plaintext password, prefixing the encoded representation with the name of the storage scheme in curly braces.
ByteString	encodePasswordWithScheme(ByteString plaintext, DN entryDN) Encodes the provided plaintext password, prefixing the encoded representation with the name of the storage scheme in curly braces.
void	finalizePasswordStorageScheme() Performs any cleanup which may be necessary when this password storage scheme is to be taken out of service.
ByteString	getAuthPasswordPlaintextValue(java.lang.String authInfo, java.lang.String authValue) Obtains the plaintext password that was used to generate an encoded password with the given authInfo and authValue elements when using the authentication password syntax as described in RFC 3112.
java.lang.String	getAuthPasswordSchemeName() Retrieves the name that should be used to identify this password storage scheme when encoding passwords using the authentication password syntax as described in RFC 3112.
java.util.Map<java.util.List<java.lang.String>,java.lang.String>	getExamplesArgumentSets() Retrieves a map containing examples of configurations that may be used for this extension.
abstract java.lang.String[]	getExtensionDescription() Retrieves a human-readable description for this extension.
abstract java.lang.String	getExtensionName() Retrieves a human-readable name for this extension.
abstract ByteString	getPlaintextValue(ByteString encoded) Attempts to determine the plaintext password used to generate the provided encoded password.
abstract java.lang.String	getStorageSchemeName() Retrieves the name for this password storage scheme.
void	initializePasswordStorageScheme(DirectoryServerContext serverContext, PasswordStorageSchemeConfig config, ArgumentParser parser) Initializes this password storage scheme.
boolean	isConfigurationAcceptable(PasswordStorageSchemeConfig config, ArgumentParser parser, java.util.List<java.lang.String> unacceptableReasons) Indicates whether the configuration represented by the provided argument parser is acceptable for use by this extension.
abstract boolean	isReversible() Indicates whether this password storage scheme encodes passwords in a form that allows the original plaintext value to be obtained from the encoded representation.
abstract boolean	isSecure() Indicates whether this password storage scheme encodes passwords in a form that may be considered secure.
abstract boolean	passwordMatches(ByteString plaintext, ByteString encoded) Indicates whether the provided plaintext password could have been used to generate the given encoded password.
boolean	supportsAuthPasswordSyntax() Indicates whether this password storage scheme provides the ability to encode passwords in the authentication password syntax as described in RFC 3112.

Methods inherited from class java.lang.Object

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

Constructor Detail

PasswordStorageScheme

public PasswordStorageScheme()

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

Method Detail

getExtensionName

public abstract java.lang.String getExtensionName()

Retrieves a human-readable name for this extension.

Specified by:

getExtensionName in interface UnboundIDExtension

Returns:

A human-readable name for this extension.

getExtensionDescription

public abstract java.lang.String[] getExtensionDescription()

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.

Specified by:

getExtensionDescription in interface UnboundIDExtension

Returns:

A human-readable description for this extension, or null or an empty array if no description should be available.

defineConfigArguments

public void defineConfigArguments(ArgumentParser parser)
                           throws ArgumentException

Updates the provided argument parser to define any configuration arguments which may be used by this extension. The argument parser may also be updated to define relationships between arguments (e.g., to specify required, exclusive, or dependent argument sets).

Specified by:

defineConfigArguments in interface Configurable

Parameters:

parser - The argument parser to be updated with the configuration arguments which may be used by this extension.

Throws:

ArgumentException - If a problem is encountered while updating the provided argument parser.

initializePasswordStorageScheme

public void initializePasswordStorageScheme(DirectoryServerContext serverContext,
                                            PasswordStorageSchemeConfig config,
                                            ArgumentParser parser)
                                     throws LDAPException

Initializes this password storage scheme.

Parameters:

serverContext - A handle to the server context for the server in which this extension is running.

config - The general configuration for this password storage scheme.

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.

isConfigurationAcceptable

public boolean isConfigurationAcceptable(PasswordStorageSchemeConfig config,
                                         ArgumentParser parser,
                                         java.util.List<java.lang.String> unacceptableReasons)

Indicates whether the configuration represented by the provided argument parser is acceptable for use by this extension. The parser will have been used to parse any configuration available for this extension, and any automatic validation will have been performed. This method may be used to perform any more complex validation which cannot be performed automatically by the argument parser.

Specified by:

isConfigurationAcceptable in interface Reconfigurable<PasswordStorageSchemeConfig>

Parameters:

config - The general configuration for this extension.

parser - The argument parser that has been used to parse the proposed configuration for this extension.

unacceptableReasons - A list to which messages may be added to provide additional information about why the provided configuration is not acceptable.

Returns:

true if the configuration in the provided argument parser appears to be acceptable, or false if not.

applyConfiguration

public ResultCode applyConfiguration(PasswordStorageSchemeConfig config,
                                     ArgumentParser parser,
                                     java.util.List<java.lang.String> adminActionsRequired,
                                     java.util.List<java.lang.String> messages)

Attempts to apply the configuration from the provided argument parser to this extension.

Specified by:

applyConfiguration in interface Reconfigurable<PasswordStorageSchemeConfig>

Parameters:

config - The general configuration for this extension.

parser - The argument parser that has been used to parse the new configuration for this extension.

adminActionsRequired - A list to which messages may be added to provide additional information about any additional administrative actions that may be required to apply some of the configuration changes.

messages - A list to which messages may be added to provide additional information about the processing performed by this method.

Returns:

A result code providing information about the result of applying the configuration change. A result of SUCCESS should be used to indicate that all processing completed successfully. Any other result will indicate that a problem occurred during processing.

finalizePasswordStorageScheme

public void finalizePasswordStorageScheme()

Performs any cleanup which may be necessary when this password storage scheme is to be taken out of service.

getStorageSchemeName

public abstract java.lang.String getStorageSchemeName()

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.

Returns:

The name for this password storage scheme.

isReversible

public abstract boolean isReversible()

Indicates whether this password storage scheme encodes passwords in a form that allows the original plaintext value to be obtained from the encoded representation.

Returns:

true if the original plaintext password may be obtained from the encoded password, or false if not.

isSecure

public abstract boolean isSecure()

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.

Returns:

true if this password storage scheme may be considered secure, or false if not.

encodePassword

public abstract ByteString encodePassword(ByteString plaintext)
                                   throws LDAPException

Encodes the provided plaintext password. The encoded password should not include the scheme name in curly braces.

Parameters:

plaintext - The plaintext password to be encoded. It must not be 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.

Returns:

The encoded representation of the provided password.

Throws:

LDAPException - If a problem occurs while attempting to encode the password.

encodePasswordWithScheme

public ByteString encodePasswordWithScheme(ByteString plaintext)
                                    throws LDAPException

Encodes the provided plaintext password, prefixing the encoded representation with the name of the storage scheme in curly braces.

Parameters:

plaintext - The plaintext password to be encoded. It must not be 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.

Returns:

The encoded representation of the provided password, prefixed with the storage scheme name.

Throws:

LDAPException - If a problem occurs while attempting to encode the password.

encodePasswordWithScheme

public ByteString encodePasswordWithScheme(ByteString plaintext,
                                           DN entryDN)
                                    throws LDAPException

Encodes the provided plaintext password, prefixing the encoded representation with the name of the storage scheme in curly braces. If an entry DN is provided, then a deterministic encoding should be used (e.g., a salt generated from the provided DN) so that the same encoding will always be used for same plaintext in the same entry. This will primarily be used when importing an LDIF file containing plaintext passwords so that the same LDIF file can be imported into multiple servers and the same encoded passwords will be generated in each server.

Parameters:

plaintext - The plaintext password to be encoded. It must not be 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.

entryDN - The DN of the entry in which the encoded password will appear. This may be null if it is not known.

Returns:

The encoded representation of the provided password, prefixed with the storage scheme name.

Throws:

LDAPException - If a problem occurs while attempting to encode the password.

passwordMatches

public abstract boolean passwordMatches(ByteString plaintext,
                                        ByteString encoded)

Indicates whether the provided plaintext password could have been used to generate the given encoded password.

Parameters:

plaintext - The plaintext password for which to make the determination.

encoded - The encoded password for which to make the determination. It will not include the scheme name.

Returns:

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

getPlaintextValue

public abstract ByteString getPlaintextValue(ByteString encoded)
                                      throws LDAPException

Attempts to determine the plaintext password used to generate the provided encoded password. This method should only be called if the isReversible() method returns true.

Parameters:

encoded - The encoded password for which to obtain the original plaintext password. It must not be null and will not be prefixed with the scheme name.

Returns:

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.

supportsAuthPasswordSyntax

public boolean supportsAuthPasswordSyntax()

Indicates whether this password storage scheme provides the ability to encode passwords in the authentication password syntax as described in RFC 3112.

Returns:

true if this password storage scheme supports the authentication password syntax, or false if not.

getAuthPasswordSchemeName

public java.lang.String getAuthPasswordSchemeName()

Retrieves the name that should be used to identify this password storage scheme when encoding passwords using the authentication password syntax as described in RFC 3112. This should only be used if the supportsAuthPasswordSyntax() method returns true.

Returns:

The name that should be used to identify this password storage scheme when encoding passwords using the authentication password syntax.

encodeAuthPassword

public ByteString encodeAuthPassword(ByteString plaintext)
                              throws LDAPException

Encodes the provided plaintext password using the authentication password syntax as defined in RFC 3112. This should only be used if the supportsAuthPasswordSyntax() method returns true.

Parameters:

plaintext - The plaintext password to be encoded. It must not be 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.

Returns:

The encoded representation of the provided password.

Throws:

LDAPException - If a problem occurs while encoding the provided password, or if this password storage scheme does not support the authentication password syntax.

authPasswordMatches

public boolean authPasswordMatches(ByteString plaintext,
                                   java.lang.String authInfo,
                                   java.lang.String authValue)

Indicates whether the provided plaintext password may be used to generate an encoded password with the given authInfo and authValue elements when using the authentication password syntax as defined in RFC 3112. This should only be used if the supportsAuthPasswordSyntax() method returns true.

Parameters:

plaintext - The plaintext password for which to make the determination.

authInfo - The authInfo portion of the encoded password for which to make the determination.

authValue - The authValue portion of the encoded password for which to make the determination.

Returns:

true if the provided plaintext password could be used to generate an encoded password with the given authInfo and authValue portions, or false if not.

getAuthPasswordPlaintextValue

public ByteString getAuthPasswordPlaintextValue(java.lang.String authInfo,
                                                java.lang.String authValue)
                                         throws LDAPException

Obtains the plaintext password that was used to generate an encoded password with the given authInfo and authValue elements when using the authentication password syntax as described in RFC 3112. This should only be used if both the supportsAuthPasswordSyntax() and isReversible() methods return true.

Parameters:

authInfo - The authInfo portion of the encoded password for which to retrieve the corresponding plaintext value.

authValue - The authValue portion of the encoded password for which to retrieve the corresponding plaintext value.

Returns:

The plaintext password that was used to generate the encoded password.

Throws:

LDAPException - If this password storage scheme is not reversible, if this password storage scheme does not support the authentication password syntax, or if some other problem is encountered while attempting to determine the plaintext password.

getExamplesArgumentSets

public java.util.Map<java.util.List<java.lang.String>,java.lang.String> getExamplesArgumentSets()

Retrieves a map containing examples of configurations that may be used for this extension. The map key should be a list of sample arguments, and the corresponding value should be a description of the behavior that will be exhibited by the extension when used with that configuration.

Specified by:

getExamplesArgumentSets in interface ExampleUsageProvider

Returns:

A map containing examples of configurations that may be used for this extension. It may be null or empty if there should not be any example argument sets.