220 lines
7.8 KiB
XML
220 lines
7.8 KiB
XML
<?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 character salt followed
|
|
by the salted SHA1 digest 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="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>
|