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

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: