org.apache.catalina.realm

## Class DigestCredentialHandlerBase

- java.lang.Object
- - org.apache.catalina.realm.DigestCredentialHandlerBase

- All Implemented Interfaces:
    CredentialHandler
  Direct Known Subclasses:
    MessageDigestCredentialHandler, SecretKeyCredentialHandler

      public abstract class DigestCredentialHandlerBase
      extends Object
      implements CredentialHandler

  Base implementation for the Tomcat provided `CredentialHandler`s.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static int` | `DEFAULT_SALT_LENGTH`
    `protected static StringManager` | `sm`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `DigestCredentialHandlerBase()`

  - ### Method Summary

    All Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `abstract String` | `getAlgorithm()`
    `protected abstract int` | `getDefaultIterations()`
    `protected int` | `getDefaultSaltLength()`
    `int` | `getIterations()`
    `protected abstract Log` | `getLog()`
    `boolean` | `getLogInvalidStoredCredentials()` When checking input credentials against stored credentials will a warning message be logged if invalid stored credentials are discovered?
    `int` | `getSaltLength()`
    `protected boolean` | `matchesSaltIterationsEncoded(String inputCredentials, String storedCredentials)` Checks whether the provided credential matches the stored credential when the stored credential is in the form salt$iteration-count$credential
    `String` | `mutate(String userCredential)` Generates the equivalent stored credentials for the given input credentials.
    `protected abstract String` | `mutate(String inputCredentials, byte[] salt, int iterations)` Generates the equivalent stored credentials for the given input credentials, salt and iterations.
    `protected String` | `mutate(String inputCredentials, byte[] salt, int iterations, int keyLength)` Generates the equivalent stored credentials for the given input credentials, salt, iterations and key length.
    `abstract void` | `setAlgorithm(String algorithm)` Set the algorithm used to convert input credentials to stored credentials.
    `void` | `setIterations(int iterations)` Set the number of iterations of the associated algorithm that will be used when creating a new stored credential for a given input credential.
    `void` | `setLogInvalidStoredCredentials(boolean logInvalidStoredCredentials)` Set whether a warning message will be logged if invalid stored credentials are discovered while checking input credentials against stored credentials?
    `void` | `setSaltLength(int saltLength)` Set the salt length that will be used when creating a new stored credential for a given input credential.

    - ### Methods inherited from class java.lang.Object

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

    - ### Methods inherited from interface org.apache.catalina.CredentialHandler

      `matches`

- - ### Field Detail

    - #### sm

          protected static final StringManager sm

    - #### DEFAULT_SALT_LENGTH

          public static final int DEFAULT_SALT_LENGTH

      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### DigestCredentialHandlerBase

          public DigestCredentialHandlerBase()

  - ### Method Detail

    - #### getIterations

          public int getIterations()

      Returns:
        the number of iterations of the associated algorithm that will be used when creating a new stored credential for a given input credential.

    - #### setIterations

          public void setIterations(int iterations)

      Set the number of iterations of the associated algorithm that will be used when creating a new stored credential for a given input credential.
      Parameters:
        `iterations` - the iterations count

    - #### getSaltLength

          public int getSaltLength()

      Returns:
        the salt length that will be used when creating a new stored credential for a given input credential.

    - #### setSaltLength

          public void setSaltLength(int saltLength)

      Set the salt length that will be used when creating a new stored credential for a given input credential.
      Parameters:
        `saltLength` - the salt length

    - #### getLogInvalidStoredCredentials

          public boolean getLogInvalidStoredCredentials()

      When checking input credentials against stored credentials will a warning message be logged if invalid stored credentials are discovered?
      Returns:
        `true` if logging will occur

    - #### setLogInvalidStoredCredentials

          public void setLogInvalidStoredCredentials(boolean logInvalidStoredCredentials)

      Set whether a warning message will be logged if invalid stored credentials are discovered while checking input credentials against stored credentials?
      Parameters:
        `logInvalidStoredCredentials` - `true` to log, the default value is `false`

    - #### mutate

          public String mutate(String userCredential)

      Description copied from interface: `CredentialHandler`
      Generates the equivalent stored credentials for the given input credentials.
      Specified by:
        `mutate` in interface `CredentialHandler`
      Parameters:
        `userCredential` - User provided credentials
      Returns:
        The equivalent stored credentials for the given input credentials

    - #### matchesSaltIterationsEncoded

          protected boolean matchesSaltIterationsEncoded(String inputCredentials,
                                                         String storedCredentials)

      Checks whether the provided credential matches the stored credential when the stored credential is in the form salt$iteration-count$credential
      Parameters:
        `inputCredentials` - The input credential
        `storedCredentials` - The stored credential
      Returns:
        `true` if they match, otherwise `false`

    - #### getDefaultSaltLength

          protected int getDefaultSaltLength()

      Returns:
        the default salt length used by the `CredentialHandler`.

    - #### mutate

          protected abstract String mutate(String inputCredentials,
                                           byte[] salt,
                                           int iterations)

      Generates the equivalent stored credentials for the given input credentials, salt and iterations. If the algorithm requires a key length, the default will be used.
      Parameters:
        `inputCredentials` - User provided credentials
        `salt` - Salt, if any
        `iterations` - Number of iterations of the algorithm associated with this CredentialHandler applied to the inputCredentials to generate the equivalent stored credentials
      Returns:
        The equivalent stored credentials for the given input credentials or `null` if the generation fails

    - #### mutate

          protected String mutate(String inputCredentials,
                                  byte[] salt,
                                  int iterations,
                                  int keyLength)

      Generates the equivalent stored credentials for the given input credentials, salt, iterations and key length. The default implementation calls ignores the key length and calls `mutate(String, byte[], int)`. Sub-classes that use the key length should override this method.
      Parameters:
        `inputCredentials` - User provided credentials
        `salt` - Salt, if any
        `iterations` - Number of iterations of the algorithm associated with this CredentialHandler applied to the inputCredentials to generate the equivalent stored credentials
        `keyLength` - Length of the produced digest in bits for implementations where it's applicable
      Returns:
        The equivalent stored credentials for the given input credentials or `null` if the generation fails

    - #### setAlgorithm

          public abstract void setAlgorithm(String algorithm)
                                     throws NoSuchAlgorithmException

      Set the algorithm used to convert input credentials to stored credentials.
      Parameters:
        `algorithm` - the algorithm
      Throws:
        `NoSuchAlgorithmException` - if the specified algorithm is not supported

    - #### getAlgorithm

          public abstract String getAlgorithm()

      Returns:
        the algorithm used to convert input credentials to stored credentials.

    - #### getDefaultIterations

          protected abstract int getDefaultIterations()

      Returns:
        the default number of iterations used by the `CredentialHandler`.

    - #### getLog

          protected abstract Log getLog()

      Returns:
        the logger for the CredentialHandler instance.

Copyright © 2000-2022 Apache Software Foundation. All Rights Reserved.