Author: markt
Date: Thu Sep 25 19:33:44 2014
New Revision: 1627614
URL: http://svn.apache.org/r1627614
Log:
Update docs
Added:
tomcat/trunk/webapps/docs/config/credentialhandler.xml (with props)
Added: tomcat/trunk/webapps/docs/config/credentialhandler.xml
URL:
http://svn.apache.org/viewvc/tomcat/trunk/webapps/docs/config/credentialhandler.xml?rev=1627614&view=auto
==============================================================================
--- tomcat/trunk/webapps/docs/config/credentialhandler.xml (added)
+++ tomcat/trunk/webapps/docs/config/credentialhandler.xml Thu Sep 25 19:33:44
2014
@@ -0,0 +1,217 @@
+<?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>CredentialHadler</strong> element MUST be nested inside a
+ <a href="realm.html">Realm</a> component. If it is not included,
+ a default <strong>CredentialHadler</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
+ passwwords are protected by a message digest. This credential handler
+ supports the following forms of stored passwords:</p>
+ <ul>
+ <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 included 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>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 crendtial
+ from a clear text credential.</p>
+ </attribute>
+
+ <attribute name="saltLength" required="false">
+ <p>The length of the randomly generated salt ot use use when creating a
+ new stored crendtial 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="PBECredentialHandler">
+
+ <p>The <strong>PBECredentialHandler</strong> is used when stored passwwords
+ are built using password based encrytpion. 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 included 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 password based encryption 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 crendtial
+ from a clear text credential.</p>
+ </attribute>
+
+ <attribute name="saltLength" required="false">
+ <p>The length of the randomly generated salt ot use use when creating a
+ new stored crendtial 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>
Propchange: tomcat/trunk/webapps/docs/config/credentialhandler.xml
------------------------------------------------------------------------------
svn:eol-style = native
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscr...@tomcat.apache.org
For additional commands, e-mail: dev-h...@tomcat.apache.org
