Subversion Repositories Integrator Subversion

Rev

Details | Last modification | View Log | RSS feed

Rev Author Line No. Line
771 blopes 1 
<!DOCTYPE html SYSTEM "about:legacy-compat">
2 
<html lang="en"><head><META http-equiv="Content-Type" content="text/html; charset=UTF-8"><link href="../images/docs-stylesheet.css" rel="stylesheet" type="text/css"><title>Apache Tomcat 9 Configuration Reference (9.0.112) - The CredentialHandler Component</title></head><body><div id="wrapper"><header><div id="header"><div><div><div class="logo noPrint"><a href="https://tomcat.apache.org/"><img alt="Tomcat Home" src="../images/tomcat.png"></a></div><div style="height: 1px;"></div><div class="asfLogo noPrint"><a href="https://www.apache.org/" target="_blank"><img src="../images/asf-logo.svg" alt="The Apache Software Foundation" style="width: 266px; height: 83px;"></a></div><h1>Apache Tomcat 9 Configuration Reference</h1><div class="versionInfo">
3 
            Version 9.0.112,
4 
            <time datetime="2025-11-06">Nov 6 2025</time></div><div style="height: 1px;"></div><div style="clear: left;"></div></div></div></div></header><div id="middle"><div><div id="mainLeft" class="noprint"><div><nav><div><h2>Links</h2><ul><li><a href="../index.html">Docs Home</a></li><li><a href="index.html">Config Ref. Home</a></li><li><a href="https://cwiki.apache.org/confluence/display/TOMCAT/FAQ">FAQ</a></li><li><a href="#comments_section">User Comments</a></li></ul></div><div><h2>Top Level Elements</h2><ul><li><a href="server.html">Server</a></li><li><a href="service.html">Service</a></li></ul></div><div><h2>Executors</h2><ul><li><a href="executor.html">Executor</a></li></ul></div><div><h2>Connectors</h2><ul><li><a href="http.html">HTTP/1.1</a></li><li><a href="http2.html">HTTP/2</a></li><li><a href="ajp.html">AJP</a></li></ul></div><div><h2>Containers</h2><ul><li><a href="context.html">Context</a></li><li><a href="engine.html">Engine</a></li><li><a href="host.html">Host</a></li><li><a href="cluster.html">Cluster</a></li></ul></div><div><h2>Nested Components</h2><ul><li><a href="cookie-processor.html">CookieProcessor</a></li><li><a href="credentialhandler.html">CredentialHandler</a></li><li><a href="globalresources.html">Global Resources</a></li><li><a href="jar-scanner.html">JarScanner</a></li><li><a href="jar-scan-filter.html">JarScanFilter</a></li><li><a href="listeners.html">Listeners</a></li><li><a href="loader.html">Loader</a></li><li><a href="manager.html">Manager</a></li><li><a href="realm.html">Realm</a></li><li><a href="resources.html">Resources</a></li><li><a href="sessionidgenerator.html">SessionIdGenerator</a></li><li><a href="valve.html">Valve</a></li></ul></div><div><h2>Cluster Elements</h2><ul><li><a href="cluster.html">Cluster</a></li><li><a href="cluster-manager.html">Manager</a></li><li><a href="cluster-channel.html">Channel</a></li><li><a href="cluster-membership.html">Channel/Membership</a></li><li><a href="cluster-sender.html">Channel/Sender</a></li><li><a href="cluster-receiver.html">Channel/Receiver</a></li><li><a href="cluster-interceptor.html">Channel/Interceptor</a></li><li><a href="cluster-valve.html">Valve</a></li><li><a href="cluster-deployer.html">Deployer</a></li><li><a href="cluster-listener.html">ClusterListener</a></li></ul></div><div><h2>web.xml</h2><ul><li><a href="filter.html">Filter</a></li></ul></div><div><h2>Other</h2><ul><li><a href="runtime-attributes.html">Runtime attributes</a></li><li><a href="systemprops.html">System properties</a></li><li><a href="jaspic.html">JASPIC</a></li></ul></div></nav></div></div><div id="mainRight"><div id="content"><h2>The CredentialHandler Component</h2><h3 id="Table_of_Contents">Table of Contents</h3><div class="text">
5 
<ul><li><a href="#Introduction">Introduction</a></li><li><a href="#Attributes">Attributes</a><ol><li><a href="#Common_Attributes">Common Attributes</a></li><li><a href="#MessageDigestCredentialHandler">MessageDigestCredentialHandler</a></li><li><a href="#NestedCredentialHandler">NestedCredentialHandler</a></li><li><a href="#SecretKeyCredentialHandler">SecretKeyCredentialHandler</a></li></ol></li><li><a href="#Nested_Components">Nested Components</a></li><li><a href="#Special_Features">Special Features</a></li></ul>
6 
</div><h3 id="Introduction">Introduction</h3><div class="text">
7 
 
8 
  <p>The <strong>CredentialHandler</strong> element represents the component
9 
  used by a <a href="realm.html">Realm</a> to compare a provided credential such
10 
  as a password with the version of the credential stored by the
11 
  <a href="realm.html">Realm</a>. The <strong>CredentialHandler</strong> can
12 
  also be used to generate a new stored version of a given credential that would
13 
  be required, for example, when adding a new user to a
14 
  <a href="realm.html">Realm</a> or when changing a user's password.</p>
15 
 
16 
  <p>A <strong>CredentialHandler</strong> element MUST be nested inside a
17 
  <a href="realm.html">Realm</a> component.  If it is not included,
18 
  a default <strong>CredentialHandler</strong> will be created using the
19 
  <strong>MessageDigestCredentialHandler</strong>.</p>
20 
 
21 
</div><h3 id="Attributes">Attributes</h3><div class="text">
22 
 
23 
  <div class="subsection"><h4 id="Common_Attributes">Common Attributes</h4><div class="text">
24 
 
25 
    <p>All implementations of <strong>CredentialHandler</strong> support the
26 
    following attributes:</p>
27 
 
28 
    <table class="defaultTable"><tr><th style="width: 15%;">
29 
          Attribute
30 
        </th><th style="width: 85%;">
31 
          Description
32 
        </th></tr><tr id="Attributes_Common Attributes_className"><td><strong><code class="attributeName">className</code></strong></td><td>
33 
        <p>Java class name of the implementation to use. This class must
34 
        implement the <code>org.apache.catalina.CredentialHandler</code>
35 
        interface.</p>
36 
      </td></tr></table>
37 
 
38 
    <p>Unlike most Catalina components, there are several standard
39 
    <strong>CredentialHandler</strong> implementations available.  As a result,
40 
    if a <strong>CredentialHandler</strong> element is present then the
41 
    <code>className</code> attribute MUST be used to select the implementation
42 
    you wish to use.</p>
43 
 
44 
  </div></div>
45 
 
46 
 
47 
  <div class="subsection"><h4 id="MessageDigestCredentialHandler">MessageDigestCredentialHandler</h4><div class="text">
48 
 
49 
    <p>The <strong>MessageDigestCredentialHandler</strong> is used when stored
50 
    passwords are protected by a message digest. This credential handler
51 
    supports the following forms of stored passwords:</p>
52 
    <ul>
53 
      <li><strong>plainText</strong> - the plain text credentials if no
54 
      algorithm is specified</li>
55 
      <li><strong>encodedCredential</strong> - a hex encoded digest of the
56 
      password digested using the configured digest</li>
57 
      <li><strong>{MD5}encodedCredential</strong> - a Base64 encoded MD5
58 
      digest of the password</li>
59 
      <li><strong>{SHA}encodedCredential</strong> - a Base64 encoded SHA1 digest
60 
      of the password</li>
61 
      <li><strong>{SSHA}encodedCredential</strong> - 20 bytes of the salted SHA1
62 
      digest of the password, followed by the variable length salt bytes, all
63 
      Base64 encoded</li>
64 
      <li><strong>salt$iterationCount$encodedCredential</strong> - a hex encoded
65 
      salt, iteration code and a hex encoded credential, each separated by
66 
      $</li>
67 
    </ul>
68 
 
69 
    <p>If the stored password form does not include an iteration count then an
70 
    iteration count of 1 is used.</p>
71 
 
72 
    <p>If the stored password form does not include salt then no salt is
73 
    used.</p>
74 
 
75 
    <table class="defaultTable"><tr><th style="width: 15%;">
76 
          Attribute
77 
        </th><th style="width: 85%;">
78 
          Description
79 
        </th></tr><tr id="Attributes_MessageDigestCredentialHandler_algorithm"><td><code class="attributeName">algorithm</code></td><td>
80 
        <p>The name of the <code>java.security.MessageDigest</code> algorithm
81 
        used to encode user passwords stored in the database.  If not specified,
82 
        user passwords are assumed to be stored in clear-text.</p>
83 
      </td></tr><tr id="Attributes_MessageDigestCredentialHandler_encoding"><td><code class="attributeName">encoding</code></td><td>
84 
        <p>Digesting the password requires that it is converted to bytes. This
85 
        attribute determines the character encoding to use for conversions
86 
        between characters and bytes. If not specified, UTF-8 will be used.</p>
87 
      </td></tr><tr id="Attributes_MessageDigestCredentialHandler_iterations"><td><code class="attributeName">iterations</code></td><td>
88 
        <p>The number of iterations to use when creating a new stored credential
89 
        from a clear text credential.</p>
90 
      </td></tr><tr id="Attributes_MessageDigestCredentialHandler_digestInRfc3112Order"><td><code class="attributeName">digestInRfc3112Order</code></td><td>
91 
        <p>When generating the digest should the inputs be processed in the
92 
        order defined in RFC 3112 (credential then salt) or in the order used by
93 
        default in earlier versions of Tomcat (salt then credential). If not
94 
        specified, the default value of <code>false</code> is used. This default
95 
        will change in Tomcat 12.</p>
96 
      </td></tr><tr id="Attributes_MessageDigestCredentialHandler_saltLength"><td><code class="attributeName">saltLength</code></td><td>
97 
        <p>The length of the randomly generated salt to use when creating a
98 
        new stored credential from a clear text credential.</p>
99 
      </td></tr></table>
100 
 
101 
  </div></div>
102 
 
103 
  <div class="subsection"><h4 id="NestedCredentialHandler">NestedCredentialHandler</h4><div class="text">
104 
 
105 
    <p>The <strong>NestedCredentialHandler</strong> is an implementation of
106 
    <strong>CredentialHandler</strong> that delegates to one or more
107 
    sub-CredentialHandlers.</p>
108 
 
109 
    <p>Using the <strong>NestedCredentialHandler</strong> gives the developer
110 
    the ability to combine multiple <strong>CredentialHandler</strong>s of the
111 
    same or different types.</p>
112 
 
113 
    <p>Sub-CredentialHandlers are defined by nesting CredentialHandler elements
114 
    inside the <code>CredentialHandler</code> element that defines the
115 
    NestedCredentialHandler. Credentials will be matched against each
116 
    <code>CredentialHandler</code> in the order they are listed. A match against
117 
    any CredentialHandler will be sufficient for the credentials to be
118 
    considered matched.</p>
119 
 
120 
  </div></div>
121 
 
122 
  <div class="subsection"><h4 id="SecretKeyCredentialHandler">SecretKeyCredentialHandler</h4><div class="text">
123 
 
124 
    <p>The <strong>SecretKeyCredentialHandler</strong> is used when stored
125 
    passwords are built using <code>javax.crypto.SecretKeyFactory</code>. This
126 
    credential handler supports the following forms of stored passwords:</p>
127 
    <ul>
128 
      <li><strong>salt$iterationCount$encodedCredential</strong> - a hex encoded
129 
      salt, iteration code and a hex encoded credential, each separated by
130 
      $</li>
131 
    </ul>
132 
 
133 
    <p>If the stored password form does not include an iteration count then an
134 
    iteration count of 1 is used.</p>
135 
 
136 
    <p>If the stored password form does not include salt then no salt is
137 
    used.</p>
138 
 
139 
    <table class="defaultTable"><tr><th style="width: 15%;">
140 
          Attribute
141 
        </th><th style="width: 85%;">
142 
          Description
143 
        </th></tr><tr id="Attributes_SecretKeyCredentialHandler_algorithm"><td><code class="attributeName">algorithm</code></td><td>
144 
        <p>The name of the secret key algorithm used to encode user passwords
145 
        stored in the database.  If not specified, a default of
146 
        <code>PBKDF2WithHmacSHA1</code> is used.</p>
147 
      </td></tr><tr id="Attributes_SecretKeyCredentialHandler_keyLength"><td><code class="attributeName">keyLength</code></td><td>
148 
        <p>The length of key to generate for the stored credential. If not
149 
        specified, a default of <code>160</code> is used.</p>
150 
      </td></tr><tr id="Attributes_SecretKeyCredentialHandler_iterations"><td><code class="attributeName">iterations</code></td><td>
151 
        <p>The number of iterations to use when creating a new stored credential
152 
        from a clear text credential.</p>
153 
      </td></tr><tr id="Attributes_SecretKeyCredentialHandler_saltLength"><td><code class="attributeName">saltLength</code></td><td>
154 
        <p>The length of the randomly generated salt to use when creating a
155 
        new stored credential from a clear text credential.</p>
156 
      </td></tr></table>
157 
 
158 
  </div></div>
159 
 
160 
</div><h3 id="Nested_Components">Nested Components</h3><div class="text">
161 
 
162 
  <p>If you are using the <em>NestedCredentialHandler Implementation</em> or a
163 
  CredentialHandler that extends the NestedCredentialHandler one or more
164 
  <strong>&lt;CredentialHandler&gt;</strong> elements may be nested inside it.
165 
  </p>
166 
 
167 
</div><h3 id="Special_Features">Special Features</h3><div class="text">
168 
 
169 
  <p>No special features are associated with a
170 
  <strong>CredentialHandler</strong> element.</p>
171 
 
172 
</div></div></div></div></div><footer><div id="footer">
173 
    Copyright &copy; 1999-2025, The Apache Software Foundation
174 
    <br>
175 
    Apache Tomcat, Tomcat, Apache, the Apache Tomcat logo and the Apache logo
176 
    are either registered trademarks or trademarks of the Apache Software
177 
    Foundation.
178 
    </div></footer></div></body></html>