webapps/docs/config/credentialhandler.xml - tomcat80 - Git at Google

 <?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&apos;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>&lt;CredentialHandler&gt;</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>
	<?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>