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 |
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 |
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
|
keyLength |
The length of key to generate for the stored credential. If not
specified, a default of |
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.