Package com.unboundid.directory.sdk.ds.api

Class EnhancedPasswordStorageScheme

  • 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 EnhancedPasswordStorageScheme
extends java.lang.Object
implements UnboundIDExtension, Reconfigurable<PasswordStorageSchemeConfig>, ExampleUsageProvider
    This class defines an API that may be implemented by extensions which provide enhanced password storage scheme support. Although the older PasswordStorageScheme API is still supported, this enhanced version is both simpler and provides additional functionality, including providing access to the user entry (which may be useful, for example, if salt or encryption information is to be derived from other content in the entry, or from another repository that can be accessed based on content in the entry). However, this API is generally simpler than the PasswordStorageScheme API, so it may be desirable for all new implementations to implement this API instead.

    Encoded passwords may take 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 Enhanced 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-enhanced \
           --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:
    PasswordStorageScheme

    • Method Summary

      All Methods Instance Methods Abstract Methods Concrete Methods 
      Modifier and Type Method 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 plaintextPassword, java.lang.String authInfo, java.lang.String authValue, Entry userEntry)
      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, Entry userEntry, java.util.List<Modification> modifications, boolean deterministic)
      Encodes the provided plaintext password using the authentication password syntax as defined in RFC 3112.
      abstract ByteString encodePassword​(ByteString plaintext, Entry userEntry, java.util.List<Modification> modifications, boolean deterministic, boolean includeScheme)
      Encodes the provided plaintext password for this storage scheme, without the name of the associated scheme.
      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, Entry userEntry)
      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 storedPassword, Entry userEntry)
      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.
      java.lang.Boolean isAuthPasswordEncodedWithCurrentSettings​(java.lang.String authInfo, java.lang.String authValue, Entry userEntry, java.util.List<java.lang.String> explanations)
      Indicates whether the provided password is encoded with the current settings for this password storage scheme using the authentication password syntax.
      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.
      java.lang.Boolean isPasswordEncodedWithCurrentSettings​(ByteString encodedPassword, Entry userEntry, java.util.List<java.lang.String> explanations)
      Indicates whether the provided password is encoded with the current settings for this password storage scheme.
      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 plaintextPassword, ByteString storedPassword, Entry userEntry)
      Indicates whether the provided plaintext password could have been used to generate the given encoded password.
      boolean requiresUserEntry()
      Indicates whether this password storage scheme requires access to the user entry in order to perform processing.
      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

      • EnhancedPasswordStorageScheme

        public EnhancedPasswordStorageScheme()
        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

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

      • requiresUserEntry

        public boolean requiresUserEntry()
        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.

        Note that if this method returns true, then the server will never provide a null value for the userEntry parameter to methods that accept it. However, if this method returns false, then there may be some instances in which the server may invoke those methods with a null value for the userEntry parameter (e.g., when invoked by the encode-password tool or when targeting a password with an extensible match search filter).
        Returns:
        true if this password storage scheme requires access to the user entry, or false if not.

      • encodePassword

        public abstract ByteString encodePassword​(ByteString plaintext,
                                          Entry userEntry,
                                          java.util.List<Modification> modifications,
                                          boolean deterministic,
                                          boolean includeScheme)
                                   throws LDAPException
        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.
        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.
        userEntry - The complete entry for the user for whom the password is to be encoded. This will not be null for schemes in which requiresUserEntry() returns true.
        modifications - The set of modifications to be applied to the user entry. This will generally be non-null only for operations that use a modify to change the user password. If a modification list is provided, then it will contain the complete set of modifications for the operation, some of which may have no impact on password encoding.
        deterministic - Indicates whether the password encoding should be deterministic. If this is 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 will be used during LDIF import processing (and potentially at other times) to help ensure that if the LDIF file is imported into multiple servers, any clear-text password encountered in the LDIF file will have the same encoded representation on all servers. Some password storage schemes may choose to ignore this property if it does not apply or is not possible to achieve.
        includeScheme - Indicates whether to include the name of the scheme in curly braces before the encoded password.
        Returns:
        The password that has been encoded using this storage scheme.
        Throws:
        LDAPException - If a problem occurs while attempting to encode the password.

      • passwordMatches

        public abstract boolean passwordMatches​(ByteString plaintextPassword,
                                        ByteString storedPassword,
                                        Entry userEntry)
        Indicates whether the provided plaintext password could have been used to generate the given encoded password.
        Parameters:
        plaintextPassword - The plaintext password provided by the user as part of a simple bind attempt.
        storedPassword - The stored password to compare against the provided plaintext password. It will not include the scheme name in curly braces.
        userEntry - The complete entry for the user for whom the password is to be validated. This will not be null for schemes in which requiresUserEntry() returns true.
        Returns:
        true if the provided clear-text password could have been used to generate the encoded password, or false if not.

      • isPasswordEncodedWithCurrentSettings

        public java.lang.Boolean isPasswordEncodedWithCurrentSettings​(ByteString encodedPassword,
                                                              Entry userEntry,
                                                              java.util.List<java.lang.String> explanations)
        Indicates whether the provided password is encoded with the current settings for this password storage scheme.
        Parameters:
        encodedPassword - The encoded password for which to make the determination. This will not be null, and it will not include the scheme name in curly braces.
        userEntry - The complete entry for the user with whom the password is associated. This will not be null for schemes in which requiresUserEntry() returns true. The entry should not be altered in any way by this password storage scheme.
        explanations - A list that may be updated with messages that may help explain the result that this method returns. This may include messages that explain why the provided password is not encoded with the current settings or why the determination could not be made. This will not be null, and it will be updatable.
        Returns:
        true if the provided password is encoded wit the current settings for this password storage scheme, false if it is not encoded with the current settings for this password storage scheme, or null if the determination cannot be made (e.g., because this method is not implemented for this password storage scheme, or because an error occurred while attempting to make the determination).

      • getPlaintextValue

        public abstract ByteString getPlaintextValue​(ByteString storedPassword,
                                             Entry userEntry)
                                      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:
        storedPassword - The password for which to obtain the plaintext value. It should not include the scheme name in curly braces.
        userEntry - The complete entry for the user for whom the password is to be validated. This will not be null for schemes in which requiresUserEntry() returns true.
        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,
                                     Entry userEntry,
                                     java.util.List<Modification> modifications,
                                     boolean deterministic)
                              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.
        userEntry - The complete entry for the user for whom the password is to be encoded. This will not be null for schemes in which requiresUserEntry() returns true.
        modifications - The set of modifications to be applied to the user entry. This will generally be non-null only for operations that use a modify to change the user password. If a modification list is provided, then it will contain the complete set of modifications for the operation, some of which may have no impact on password encoding.
        deterministic - Indicates whether the password encoding should be deterministic. If this is 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 will be used during LDIF import processing (and potentially at other times) to help ensure that if the LDIF file is imported into multiple servers, any clear-text password encountered in the LDIF file will have the same encoded representation on all servers. Some password storage schemes may choose to ignore this property if it does not apply or is not possible to achieve.
        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 plaintextPassword,
                                   java.lang.String authInfo,
                                   java.lang.String authValue,
                                   Entry userEntry)
        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:
        plaintextPassword - The plaintext password provided by the user.
        authInfo - The authInfo component of the password encoded in the authentication password syntax.
        authValue - The authValue component of the password encoded in the authentication password syntax.
        userEntry - The complete entry for the user for whom the password is to be validated. This will not be null for schemes in which requiresUserEntry() returns true.
        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.

      • isAuthPasswordEncodedWithCurrentSettings

        public java.lang.Boolean isAuthPasswordEncodedWithCurrentSettings​(java.lang.String authInfo,
                                                                  java.lang.String authValue,
                                                                  Entry userEntry,
                                                                  java.util.List<java.lang.String> explanations)
        Indicates whether the provided password is encoded with the current settings for this password storage scheme using the authentication password syntax.
        Parameters:
        authInfo - The authInfo component of the password encoded in the authentication password syntax.
        authValue - The authValue component of the password encoded in the authentication password syntax.
        userEntry - The complete entry for the user with whom the password is associated. This will not be null for wchemes in which requiresUserEntry() returns true. The entry should not be altered in any way by this password storage scheme.
        explanations - A list that may be updated with messages that may help explain the result that this method returns. This may include messages that explain why the provided password is not encoded with the current settings or why the determination could not be made. This will not be null, and it will be updatable.
        Returns:
        true if the provided password is encoded wit the current settings for this password storage scheme, false if it is not encoded with the current settings for this password storage scheme, or null if the determination cannot be made (e.g., because this method is not implemented for this password storage scheme, or because an error occurred while attempting to make the determination).

      • getAuthPasswordPlaintextValue

        public ByteString getAuthPasswordPlaintextValue​(java.lang.String authInfo,
                                                java.lang.String authValue,
                                                Entry userEntry)
                                         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 component of the password encoded in the authentication password syntax.
        authValue - The authValue component of the password encoded in the authentication password syntax.
        userEntry - The complete entry for the user for whom the password is to be validated. This will not be null for schemes in which requiresUserEntry() returns true. The entry should not be altered in any way by this password storage scheme.
        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.