Though the tomcat-docs gives most information, there are some pitfalls when using tomcats facilities for HTTP Auth in Digest mode including hashed passwords. Following is a list to avoid them (tested on tomcat 6.0.x).

JDBC Driver to classpath

Tomcat realm handling is container internal, therefore it is not enough to have jdbc-driver (e.g. mysql-connector-java-5.1.6.jar) in your application classpath. You have to explicit add it to the container classpath (e.g. TOMCAT_HOME/lib).

Configuration Snippets

Tomcat container config, which can appear as nested element inside <Engine>, <Host> or <Context> (e.g. TOMCAT_HOME/conf/context.xml):

...
<!-- database connection settings + enabling hashed passwords (MD5 sum style) -->
<Realm
 className="org.apache.catalina.realm.JDBCRealm"
 digest="MD5"
 driverName="com.mysql.jdbc.Driver"
 connectionURL="jdbcURL"
 connectionName="dbUser"
 connectionPassword="dbPwd"
 userRoleTable="role_table"
 userTable="user_table"
 userNameCol="dbuser_column"
 userCredCol="dbpwd_column"
 roleNameCol="role_column"/>
...

Webapplication web.xml:

<web-app>
...
 <security-constraint>
   <web-resource-collection>
     <web-resource-name>Secure area</web-resource-name>
     <url-pattern>/*</url-pattern>
   </web-resource-collection>
   <auth-constraint>
     <role-name>admin</role-name>
   </auth-constraint>
 </security-constraint>

 <login-config>
   <!-- enabling HTTP Auth digest mode -->
   <auth-method>DIGEST</auth-method>
   <realm-name>your-realm</realm-name>
 </login-config>

 <!-- roles must be defined to be used in security-constraint -->
 <security-role>
   <description>Role sample</description>
   <role-name>admin</role-name>
 </security-role>
...
</web-app>

Password patterns

For HTTP Auth Digest tomcat expects a special cleartext pattern for the hashed password entry inside the database. Unfortunately the cleartext snippet is different from the one from Http Auth Basic (this took me some time to find out…).

Bash CLI samples for HTTP Auth password hashing (md5sum):

# Basic style (only the password without user or realm info is hashed)
echo -n password | md5sum
# Digest style ('your-realm' is entry from web.xml->login-config->realm-name)
echo -n username:your-realm:password | md5sum

Migration HTTP Auth Basic to Digest

As you saw above tomcats Auth Basic and Digest cleartext password patterns are different. Therefore just switching the entry of web.xml->login-config->auth-method from ‘BASIC’ to ‘DIGEST’ wouldn’t suffice. I recommend to completely create a new database column (e.g. passwords_digest) so the separation and transition-path between Basic and Digest style is more clear. In case you hashed the Basic passwords already further more you have to reset the user passwords (the nature of good hashes are that you practically cannot map back to cleartext).