## The CredentialHandler Component

### Table of Contents

- Introduction
- Attributes
  1. Common Attributes
  2. MessageDigestCredentialHandler
  3. NestedCredentialHandler
  4. SecretKeyCredentialHandler
- Nested Components
- Special Features

### Introduction

The CredentialHandler element represents the component used by a Realm to compare a provided credential such as a password with the version of the credential stored by the Realm. The CredentialHandler can also be used to generate a new stored version of a given credential that would be required, for example, when adding a new user to a Realm or when changing a user's password.

A CredentialHandler element MUST be nested inside a Realm component. If it is not included, a default CredentialHandler will be created using the MessageDigestCredentialHandler.

### Attributes

#### Common Attributes

All implementations of CredentialHandler support the following attributes:

Attribute | Description
--- | ---
`className` | Java class name of the implementation to use. This class must implement the `org.apache.catalina.CredentialHandler` interface.

Unlike most Catalina components, there are several standard CredentialHandler implementations available. As a result, if a CredentialHandler element is present then the `className` attribute MUST be used to select the implementation you wish to use.

#### MessageDigestCredentialHandler

The MessageDigestCredentialHandler is used when stored passwords are protected by a message digest. This credential handler supports the following forms of stored passwords:

- plainText - the plain text credentials if no algorithm is specified
- encodedCredential - a hex encoded digest of the password digested using the configured digest
- {MD5}encodedCredential - a Base64 encoded MD5 digest of the password
- {SHA}encodedCredential - a Base64 encoded SHA1 digest of the password
- {SSHA}encodedCredential - 20 bytes of the salted SHA1 digest of the password, followed by the variable length salt bytes, all Base64 encoded
- salt$iterationCount$encodedCredential - a hex encoded salt, iteration code and a hex encoded credential, each separated by $

If the stored password form does not include an iteration count then an iteration count of 1 is used.

If the stored password form does not include salt then no salt is used.

Attribute | Description
--- | ---
`algorithm` | The name of the `java.security.MessageDigest` algorithm used to encode user passwords stored in the database. If not specified, user passwords are assumed to be stored in clear-text.
`encoding` | Digesting the password requires that it is converted to bytes. This attribute determines the character encoding to use for conversions between characters and bytes. If not specified, UTF-8 will be used.
`iterations` | The number of iterations to use when creating a new stored credential from a clear text credential.
`digestInRfc3112Order` | When generating the digest should the inputs be processed in the order defined in RFC 3112 (credential then salt) or in the order used by default in earlier versions of Tomcat (salt then credential). If not specified, the default value of `false` is used. This default will change in Tomcat 12.
`saltLength` | The length of the randomly generated salt to use when creating a new stored credential from a clear text credential.

#### NestedCredentialHandler

The NestedCredentialHandler is an implementation of CredentialHandler that delegates to one or more sub-CredentialHandlers.

Using the NestedCredentialHandler gives the developer the ability to combine multiple CredentialHandlers of the same or different types.

Sub-CredentialHandlers are defined by nesting CredentialHandler elements inside the `CredentialHandler` element that defines the NestedCredentialHandler. Credentials will be matched against each `CredentialHandler` in the order they are listed. A match against any CredentialHandler will be sufficient for the credentials to be considered matched.

#### SecretKeyCredentialHandler

The SecretKeyCredentialHandler is used when stored passwords are built using `javax.crypto.SecretKeyFactory`. This credential handler supports the following forms of stored passwords:

- salt$iterationCount$encodedCredential - a hex encoded salt, iteration code and a hex encoded credential, each separated by $

If the stored password form does not include an iteration count then an iteration count of 1 is used.

If the stored password form does not include salt then no salt is used.

Attribute | Description
--- | ---
`algorithm` | The name of the secret key algorithm used to encode user passwords stored in the database. If not specified, a default of `PBKDF2WithHmacSHA1` is used.
`keyLength` | The length of key to generate for the stored credential. If not specified, a default of `160` is used.
`iterations` | The number of iterations to use when creating a new stored credential from a clear text credential.
`saltLength` | The length of the randomly generated salt to use when creating a new stored credential from a clear text credential.

### Nested Components

If you are using the NestedCredentialHandler Implementation or a CredentialHandler that extends the NestedCredentialHandler one or more <CredentialHandler> elements may be nested inside it.

### Special Features

No special features are associated with a CredentialHandler element.