## 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 character salt followed by the salted SHA1 digest 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.
`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.