The CredentialHandler Component

Table of Contents

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.