# 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
Description
`static final int`
`DEFAULT_SALT_LENGTH`
Default salt length in bytes.
`protected static final StringManager`
`sm`
String manager for this class.

## Constructor Summary

Constructors
Constructor
Description
`DigestCredentialHandlerBase()`
Construct a new DigestCredentialHandlerBase.

## Method Summary

Modifier and Type
Method
Description
`static boolean`
`equals(byte[] b1, byte[] b2)`
Deprecated.
Use `ConstantTime.equals(byte[], byte[])`.
`static boolean`
`equals(String s1, String s2, boolean ignoreCase)`
Deprecated.
Use `ConstantTime.equals(String, String, boolean)`.
`abstract String`
`getAlgorithm()`
Get the algorithm used to convert input credentials to stored credentials.
`protected abstract int`
`getDefaultIterations()`
Get the default number of iterations used by the `CredentialHandler`.
`protected int`
`getDefaultSaltLength()`
Get the default salt length used by the `CredentialHandler`.
`int`
`getIterations()`
Get the number of iterations of the associated algorithm that will be used when creating a new stored credential for a given input credential.
`protected abstract Log`
`getLog()`
Get the logger for the CredentialHandler instance.
`boolean`
`getLogInvalidStoredCredentials()`
When checking input credentials against stored credentials will a warning message be logged if invalid stored credentials are discovered?
`int`
`getSaltLength()`
Get the salt length that will be used when creating a new stored credential for a given input credential.
`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 Object

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

### Methods inherited from interface CredentialHandler

`matches`

## Field Details

### sm

protected static final StringManager sm
String manager for this class.

### DEFAULT_SALT_LENGTH

public static final int DEFAULT_SALT_LENGTH
Default salt length in bytes.

See Also:
  - Constant Field Values

## Constructor Details

### DigestCredentialHandlerBase

public DigestCredentialHandlerBase()
Construct a new DigestCredentialHandlerBase.

## Method Details

### getIterations

public int getIterations()
Get the number of iterations of the associated algorithm that will be used when creating a new stored credential for a given input credential.

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()
Get the salt length that will be used when creating a new stored credential for a given input credential.

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()
Get the default salt length used by the `CredentialHandler`.

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)`. Subclasses 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()
Get the algorithm used to convert input credentials to stored credentials.

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

### getDefaultIterations

protected abstract int getDefaultIterations()
Get the default number of iterations used by the `CredentialHandler`.

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

### getLog

protected abstract Log getLog()
Get the logger for the CredentialHandler instance.

Returns:
  the logger for the CredentialHandler instance.

### equals

@Deprecated public static boolean equals(String s1, String s2, boolean ignoreCase)
Deprecated.
Use `ConstantTime.equals(String, String, boolean)`. This method will be removed in Tomcat 12.
Implements String equality which always compares all characters in the string, without stopping early if any characters do not match.

Note: This implementation was adapted from `MessageDigest.isEqual(byte[], byte[])` which we assume is as optimizer-defeating as possible.

Parameters:
  `s1` - The first string to compare.
  `s2` - The second string to compare.
  `ignoreCase` - `true` if the strings should be compared without regard to case. Note that "true" here is only guaranteed to work with plain ASCII characters.
Returns:
  `true` if the strings are equal to each other, `false` otherwise.

### equals

@Deprecated public static boolean equals(byte[] b1, byte[] b2)
Deprecated.
Use `ConstantTime.equals(byte[], byte[])`. This method will be removed in Tomcat 12.
Implements byte-array equality which always compares all bytes in the array, without stopping early if any bytes do not match.

Note: Implementation note: this method delegates to `MessageDigest.isEqual(byte[], byte[])` under the assumption that it provides a constant-time comparison of the bytes in the arrays. Java 7+ has such an implementation, but neither the Javadoc nor any specification requires it. Therefore, Tomcat should continue to use this method internally in case the JDK implementation changes so this method can be re-implemented properly.

Parameters:
  `b1` - The first array to compare.
  `b2` - The second array to compare.
Returns:
  `true` if the arrays are equal to each other, `false` otherwise.