init
This commit is contained in:
219
webapps/docs/config/credentialhandler.xml
Normal file
219
webapps/docs/config/credentialhandler.xml
Normal file
@@ -0,0 +1,219 @@
|
||||
<?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>
|
||||
Reference in New Issue
Block a user