"use strict"; // Enable strict mode (function() { var thisScript = document.currentScript; if (!thisScript) { // Workaround for IE <= 11 var scripts = document.getElementsByTagName("script"); thisScript = scripts[scripts.length - 1]; } document.addEventListener("DOMContentLoaded", (function() { var commentsDiv = document.getElementById("comments_thread"); var commentsShortname = "tomcat"; var commentsIdentifier = "https://tomcat.apache.org/" + thisScript.getAttribute("data-comments-identifier") + ".html"; (function(w, d) { if (w.location.hostname.toLowerCase() == "tomcat.apache.org") { var s = d.createElement("script"); s.type = "application/javascript"; s.async = true; s.src = "https://comments.apache.org/show_comments.lua?site=" + encodeURIComponent(commentsShortname) + "&page=" + encodeURIComponent(commentsIdentifier); d.head.appendChild(s); } else { commentsDiv.appendChild(d.createTextNode("Comments are disabled for this page at the moment.")); } })(window, document); }), false); })();
Version 9.0.12,

The CredentialHandler Component

Table of Contents

Introduction

The CredentialHandler element represents the component used by a Realm to compare a provided credential such as a password with the version of the credential stored by the Realm. The CredentialHandler 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 Realm or when changing a user's password.

A CredentialHandler element MUST be nested inside a Realm component. If it is not included, a default CredentialHandler will be created using the MessageDigestCredentialHandler.

Attributes

Common Attributes

All implementations of CredentialHandler support the following attributes:

Attribute Description
className

Java class name of the implementation to use. This class must implement the org.apache.catalina.CredentialHandler interface.

Unlike most Catalina components, there are several standard CredentialHandler implementations available. As a result, if a CredentialHandler element is present then the className attribute MUST be used to select the implementation you wish to use.

MessageDigestCredentialHandler

The MessageDigestCredentialHandler is used when stored passwords are protected by a message digest. This credential handler supports the following forms of stored passwords:

  • plainText - the plain text credentials if no algorithm is specified
  • encodedCredential - a hex encoded digest of the password digested using the configured digest
  • {MD5}encodedCredential - a Base64 encoded MD5 digest of the password
  • {SHA}encodedCredential - a Base64 encoded SHA1 digest of the password
  • {SSHA}encodedCredential - 20 character salt followed by the salted SHA1 digest Base64 encoded
  • salt$iterationCount$encodedCredential - a hex encoded salt, iteration code and a hex encoded credential, each separated by $
  • If the stored password form does not include an iteration count then an iteration count of 1 is used.

    If the stored password form does not include salt then no salt is used.

    Attribute Description
    algorithm

    The name of the java.security.MessageDigest algorithm used to encode user passwords stored in the database. If not specified, user passwords are assumed to be stored in clear-text.

    encoding

    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.

    iterations

    The number of iterations to use when creating a new stored credential from a clear text credential.

    saltLength

    The length of the randomly generated salt to use when creating a new stored credential from a clear text credential.

    NestedCredentialHandler

    The NestedCredentialHandler is an implementation of CredentialHandler that delegates to one or more sub-CredentialHandlers.

    Using the NestedCredentialHandler gives the developer the ability to combine multiple CredentialHandlers of the same or different types.

    Sub-CredentialHandlers are defined by nesting CredentialHandler elements inside the CredentialHandler element that defines the NestedCredentialHandler. Credentials will be matched against each CredentialHandler in the order they are listed. A match against any CredentialHandler will be sufficient for the credentials to be considered matched.

    SecretKeyCredentialHandler

    The SecretKeyCredentialHandler is used when stored passwords are built using javax.crypto.SecretKeyFactory. This credential handler supports the following forms of stored passwords:

  • salt$iterationCount$encodedCredential - a hex encoded salt, iteration code and a hex encoded credential, each separated by $
  • If the stored password form does not include an iteration count then an iteration count of 1 is used.

    If the stored password form does not include salt then no salt is used.

    Attribute Description
    algorithm

    The name of the secret key algorithm used to encode user passwords stored in the database. If not specified, a default of PBKDF2WithHmacSHA1 is used.

    keyLength

    The length of key to generate for the stored credential. If not specified, a default of 160 is used.

    iterations

    The number of iterations to use when creating a new stored credential from a clear text credential.

    saltLength

    The length of the randomly generated salt to use when creating a new stored credential from a clear text credential.

    Nested Components

    If you are using the NestedCredentialHandler Implementation or a CredentialHandler that extends the NestedCredentialHandler one or more <CredentialHandler> elements may be nested inside it.

    Special Features

    No special features are associated with a CredentialHandler element.

    Comments

    Notice: This comments section collects your suggestions on improving documentation for Apache Tomcat.

    If you have trouble and need help, read Find Help page and ask your question on the tomcat-users mailing list. Do not ask such questions here. This is not a Q&A section.

    The Apache Comments System is explained here. Comments may be removed by our moderators if they are either implemented or considered invalid/off-topic.