<?xml version="1.0" encoding="UTF-8"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<!DOCTYPE document [
<!ENTITY project SYSTEM "project.xml">
]>
<document url="credentialhandler.html">
&project;
<properties>
<title>The CredentialHandler Component</title>
</properties>
<body>
<section name="Table of Contents">
<toc />
</section>
<section name="Introduction">
<p>The <strong>CredentialHandler</strong> element represents the component
used by a <a href="realm.html">Realm</a> to compare a provided credential such
as a password with the version of the credential stored by the
<a href="realm.html">Realm</a>. The <strong>CredentialHandler</strong> 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
<a href="realm.html">Realm</a> or when changing a user's password.</p>
<p>A <strong>CredentialHandler</strong> element MUST be nested inside a
<a href="realm.html">Realm</a> component. If it is not included,
a default <strong>CredentialHandler</strong> will be created using the
<strong>MessageDigestCredentialHandler</strong>.</p>
</section>
<section name="Attributes">
<subsection name="Common Attributes">
<p>All implementations of <strong>CredentialHandler</strong> support the
following attributes:</p>
<attributes>
<attribute name="className" required="true">
<p>Java class name of the implementation to use. This class must
implement the <code>org.apache.catalina.CredentialHandler</code>
interface.</p>
</attribute>
</attributes>
<p>Unlike most Catalina components, there are several standard
<strong>CredentialHandler</strong> implementations available. As a result,
if a <strong>CredentialHandler</strong> element is present then the
<code>className</code> attribute MUST be used to select the implementation
you wish to use.</p>
</subsection>
<subsection name="MessageDigestCredentialHandler">
<p>The <strong>MessageDigestCredentialHandler</strong> is used when stored
passwords are protected by a message digest. This credential handler
supports the following forms of stored passwords:</p>
<ul>
<li><strong>plainText</strong> - the plain text credentials if no
algorithm is specified</li>
<li><strong>encodedCredential</strong> - a hex encoded digest of the
password digested using the configured digest</li>
<li><strong>{MD5}encodedCredential</strong> - a Base64 encoded MD5
digest of the password</li>
<li><strong>{SHA}encodedCredential</strong> - a Base64 encoded SHA1 digest
of the password</li>
<li><strong>{SSHA}encodedCredential</strong> - 20 bytes of the salted SHA1
digest of the password, followed by the variable length salt bytes, all
Base64 encoded</li>
<li><strong>salt$iterationCount$encodedCredential</strong> - a hex encoded
salt, iteration code and a hex encoded credential, each separated by
$</li>
</ul>
<p>If the stored password form does not include an iteration count then an
iteration count of 1 is used.</p>
<p>If the stored password form does not include salt then no salt is
used.</p>
<attributes>
<attribute name="algorithm" required="false">
<p>The name of the <code>java.security.MessageDigest</code> algorithm
used to encode user passwords stored in the database. If not specified,
user passwords are assumed to be stored in clear-text.</p>
</attribute>
<attribute name="encoding" required="false">
<p>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.</p>
</attribute>
<attribute name="iterations" required="false">
<p>The number of iterations to use when creating a new stored credential
from a clear text credential.</p>
</attribute>
<attribute name="digestInRfc3112Order" required="false">
<p>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 <code>false</code> is used. This default
will change in Tomcat 12.</p>
</attribute>
<attribute name="saltLength" required="false">
<p>The length of the randomly generated salt to use when creating a
new stored credential from a clear text credential.</p>
</attribute>
</attributes>
</subsection>
<subsection name="NestedCredentialHandler">
<p>The <strong>NestedCredentialHandler</strong> is an implementation of
<strong>CredentialHandler</strong> that delegates to one or more
sub-CredentialHandlers.</p>
<p>Using the <strong>NestedCredentialHandler</strong> gives the developer
the ability to combine multiple <strong>CredentialHandler</strong>s of the
same or different types.</p>
<p>Sub-CredentialHandlers are defined by nesting CredentialHandler elements
inside the <code>CredentialHandler</code> element that defines the
NestedCredentialHandler. Credentials will be matched against each
<code>CredentialHandler</code> in the order they are listed. A match against
any CredentialHandler will be sufficient for the credentials to be
considered matched.</p>
</subsection>
<subsection name="SecretKeyCredentialHandler">
<p>The <strong>SecretKeyCredentialHandler</strong> is used when stored
passwords are built using <code>javax.crypto.SecretKeyFactory</code>. This
credential handler supports the following forms of stored passwords:</p>
<ul>
<li><strong>salt$iterationCount$encodedCredential</strong> - a hex encoded
salt, iteration code and a hex encoded credential, each separated by
$</li>
</ul>
<p>If the stored password form does not include an iteration count then an
iteration count of 1 is used.</p>
<p>If the stored password form does not include salt then no salt is
used.</p>
<attributes>
<attribute name="algorithm" required="false">
<p>The name of the secret key algorithm used to encode user passwords
stored in the database. If not specified, a default of
<code>PBKDF2WithHmacSHA1</code> is used.</p>
</attribute>
<attribute name="keyLength" required="false">
<p>The length of key to generate for the stored credential. If not
specified, a default of <code>160</code> is used.</p>
</attribute>
<attribute name="iterations" required="false">
<p>The number of iterations to use when creating a new stored credential
from a clear text credential.</p>
</attribute>
<attribute name="saltLength" required="false">
<p>The length of the randomly generated salt to use when creating a
new stored credential from a clear text credential.</p>
</attribute>
</attributes>
</subsection>
</section>
<section name="Nested Components">
<p>If you are using the <em>NestedCredentialHandler Implementation</em> or a
CredentialHandler that extends the NestedCredentialHandler one or more
<strong><CredentialHandler></strong> elements may be nested inside it.
</p>
</section>
<section name="Special Features">
<p>No special features are associated with a
<strong>CredentialHandler</strong> element.</p>
</section>
</body>
</document>