| <?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> |