Digest passwords enable an application to avoid storing and even transmitting the password in a form that someone can read.

A digest of a cleartext password is calculated when it is passed through a one-way function that consistently produces another series of characters, digestPassword = digester(username + ":" + realm + ":" cleartextPassword). The function is "one-way" because the digestPassword cannot be used to reverse-engineer the original password.

Digest passwords can be used in two places: storage and transmission. Digest passwords in storage means that the password is stored in a digested form, for example in a database or in a file. Digest passwords in transmission means that the client (usually a web browser) creates the digest and submits the digest password to the web server.

Digest protects passwords

Storing digest passwords is so important for security purposes that the Resin authenticators default to assuming that the passwords are stored in digest form.

The important advantage is that a user's cleartext password is not as easily compromised. Since the password they use (the "cleartext" password) is not stored a malicious user cannot determine the password by gaining access to the database or other backend storage for the passwords.

MD5 digest

Resin's authenticators use "MD5-base64" and a realm "resin" to digest passwords by default. MD5 indicates that the MD5 algorithm is used. base64 is an encoding format to apply to the binary result of MD5.

Some examples are:

In the above example the digest of "harry/quidditch" is different than the digest of "hpotter/quidditch" because even though the password is the same, the username has changed. The digest is calculated with digest(username + ":" + realm + ":" + password), so if the username changes the resulting digest is different.

Calculating a digest

Of course, storing the digest password is a bit more work. When the user registers, the application needs to compute the digest to store it.

Unix users can quickly calculate a digest:

echo -n "user:resin:password" | openssl dgst -md5 -binary | uuencode -m -

The class com.caucho.http.security.PasswordDigest can be used to calculate a digest.

  import com.caucho.server.security.PasswordDigest;

  ...

  String username = ...;
  String password = ...;
  String realm = "resin";

  PasswordDigest passwordDigest = PasswordDigest();

  String digest = passwordDigest.getPasswordDigest(username, password, realm);

  $username = ...;
  $password = ...;
  $realm = "resin";

  $passwordDigest = new Java("com.caucho.server.security.PasswordDigest");

  $digest = $passwordDigest->getPasswordDigest($username, $password, $realm);

The realm for JdbcAuthenticator and XmlAuthenticator defaults to "resin"; the realm can be specified during configuration:

<authenticator type='com.caucho.server.security.JdbcAuthenticator'>
  <init>
    <password-digest-realm>hogwarts</password-digest-realm>

    ...

Using Digest with basic authentication or a form login

When using the form login method or the HTTP basic authentication login method, the password submitted is in cleartext. The Resin authenticator will digest the password before comparing it to the value retrieved from storage. The message is transmitted in cleartext but is stored as a digest. This method provides only half of the protection - the password is not protected in transmission (although if the form submit is being done over an SSL connection it will be secure).

Using HTTP digest authentication

The HTTP protocol includes a method to indicate to the client that it should make a digest using the password. The client submits a digest to Resin instead of submitting a cleartext password. HTTP digest authentication protects the password in transmission.

When using HTTP digest, Resin will respond to the browser and ask it to calculcate a digest. The steps involved are:

• Resin provides the client a realm and some other information
• The client obtains a username and password (usually a dialog box with a web browser)
• The client calculates a digest using the username, realm, pasword, and other information supplied by Resin
• The client submits the digest to Resin
• Resin does the same digest calculation as the client did
• Resin compares the submitted digest and the digest it calculated. If they match, the user has been authenticated

The advantage of this method is that the cleartext password is protected in transmission, it cannot be determined from the digest that is submitted by the client to the server.

HTTP digest authentication is enabled with the auth-method child of the login-config configuration tag.

<login-config>
  <auth-method>DIGEST</auth-method>
</login-config>

Disabling the use of password-digest

Although it is not advised, Resin's authenticators can be configured to use passwords that are not in digest form.

<authenticator>
  <type>com.caucho.server.security.XmlAuthenticator</type>
  <init>
     <password-digest>none</password-digest>
     <user>harry:quidditch:user</user>
  </init>
</authenticator>

Compatibility

Authenticators are not defined by the Servlet Specification, so the ability to use passwords stored as a digest depends upon the implementation of the Authenticator that the application server provides. MD5-base64 is the most common form of digest, because it is the default in HTTP digest authentication.

The use of <auth-method>DIGEST<auth-method> is defined in the Servlet Specification and implemented in most application servers.