Quelle  credentialhandler.xml   Sprache: XML

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