org.jaffa.tomcat.realm
Class JDBCEncryptionRealm

java.lang.Object
  org.apache.catalina.realm.RealmBase
      org.jaffa.tomcat.realm.JDBCEncryptionRealm

All Implemented Interfaces:

Lifecycle, Realm

public class JDBCEncryptionRealm

extends RealmBase

This Realm included the functionality of both the standard tomcat JDBCRealm and the DataSourceRealm, in one class. It also included the ability to perform custom password encryption using 3rd party classes (if your encryption scheme is not supported by the default MessageDigest class in the JCE libraries).

This new version works with Tomcat 4.1 and higher, the previous version that doesn't have the DataSource code in it, works with ther earlier Tomcat 4.0 release

The code based for this classes was taken from the Tomcat 4.1.26 release

The two properties used for encryption are : encryptionClass and encryptionMethod.

With these set, the realm introspects for the named class for the names method. It is expected that the method has one of the following signatures

      public static String methodName(String password)
 

or

      public static String methodName(String password, String username)
 

The method should return a string, that should match the value retrieved from the database. This allow one-way encryption algorithms to be used. No decryption facility needs to be provided.

In addition to the original JDBCRealm/DataSource this realm

1. does not throw a NullPointerException if the database password is null
2. considers a user validated if the database and entered password are both null
3. provided one-way password encryption prior to comparing them
4. allows extention to the query to get the user's credentials
5. allows a custom query to be suppplied for getting the user's roles
6. Message levels for 'debug' parameter are 0 ->None, 2+ ->Errors, 5+ ->Warnings, 10+ ->Debug

New in Version 1.3

• Adds support for DataSources. If the 'dataSourceName' is passed it overrides the use of a regular connection, therefore it ignores the values for connectionName, connectionPassword, connectionURL and driverName
• Uses its own LocalStrings for messages, incase you want to implement a diffenent language

For more documentation see the Jaffa Web Site

Version:

1.3

Author:

Paul Extance

Field Summary

protected String	connectionName The connection username to use when trying to connect to the database.
protected String	connectionPassword The connection URL to use when trying to connect to the database.
protected String	connectionURL The connection URL to use when trying to connect to the database.
protected String	dataSourceName The name of the JNDI JDBC DataSource
protected Connection	dbConnection The connection to the database.
protected Driver	driver Instance of the JDBC Driver class we use as a connection factory.
protected String	driverName The JDBC driver to use.
protected static String	info Descriptive information about this Realm implementation.
protected static String	name Descriptive information about this Realm implementation.
protected PreparedStatement	preparedCredentials The PreparedStatement to use for authenticating users.
protected PreparedStatement	preparedRoles The PreparedStatement to use for identifying the roles for a specified user.
protected String	roleNameCol The column in the user role table that names a role
protected static StringManager	sm The string manager for this package.
protected String	userCredCol The column in the user table that holds the user's credintials
protected String	userNameCol The column in the user table that holds the user's name
protected String	userRoleTable The table that holds the relation between user's and roles
protected String	userTable The table that holds user data.

Fields inherited from class org.apache.catalina.realm.RealmBase

container, debug, digest, lifecycle, md, md5Encoder, md5Helper, started, support, validate

Fields inherited from interface org.apache.catalina.Lifecycle

AFTER_START_EVENT, AFTER_STOP_EVENT, BEFORE_START_EVENT, BEFORE_STOP_EVENT, START_EVENT, STOP_EVENT

Constructor Summary

JDBCEncryptionRealm()

Method Summary

Principal	authenticate(String username, String credentials) Return the Principal associated with the specified username and credentials, if there is one; otherwise return null.
protected void	close(Connection dbConnection) Close the specified database connection.
protected PreparedStatement	credentials(Connection dbConnection, String username) Return a PreparedStatement configured to perform the SELECT required to retrieve user credentials for the specified username.
String	getConnectionName() Return the username to use to connect to the database.
String	getConnectionPassword() Return the password to use to connect to the database.
String	getConnectionURL() Return the URL to use to connect to the database.
String	getDataSourceName() Return the name of the JNDI JDBC DataSource.
String	getDriverName() Return the JDBC driver that will be used.
String	getEncryptionClass() Return the class used for encryption
String	getEncryptionMethod() Return the method used for encryption
protected String	getName() Return a short name for this Realm implementation.
protected String	getPassword(String username) Not Implemented - Return the password associated with the given principal's user name.
protected Principal	getPrincipal(String username) Not Implemented - Return the Principal associated with the given user name.
String	getRoleNameCol() Return the column in the user role table that names a role.
String	getRoleSelect() Return the alternative select statement for reading the roles
String	getUserClause() Getter for property userClause.
String	getUserCredCol() Return the column in the user table that holds the user's credentials.
String	getUserNameCol() Return the column in the user table that holds the user's name.
String	getUserRoleTable() Return the table that holds the relation between user's and roles.
String	getUserTable() Return the table that holds user data.
protected Connection	open() Open (if necessary) and return a database connection for use by this Realm.
protected void	release(Connection dbConnection) Release our use of this connection so that it can be recycled.
protected PreparedStatement	roles(Connection dbConnection, String username) Return a PreparedStatement configured to perform the SELECT required to retrieve user roles for the specified username.
void	setConnectionName(String connectionName) Set the username to use to connect to the database.
void	setConnectionPassword(String connectionPassword) Set the password to use to connect to the database.
void	setConnectionURL(String connectionURL) Set the URL to use to connect to the database.
void	setDataSourceName(String dataSourceName) Set the name of the JNDI JDBC DataSource.
void	setDriverName(String driverName) Set the JDBC driver that will be used.
void	setEncryptionClass(String encryptionClass) Setter for property encryptionClass.
void	setEncryptionMethod(String encryptionMethod) Setter for property encryptionMethod.
void	setRoleNameCol(String roleNameCol) Set the column in the user role table that names a role.
void	setRoleSelect(String roleSelect) Setter for property roleSelect.
void	setUserClause(String userClause) Setter for property userClause.
void	setUserCredCol(String userCredCol) Set the column in the user table that holds the user's credentials.
void	setUserNameCol(String userNameCol) Set the column in the user table that holds the user's name.
void	setUserRoleTable(String userRoleTable) Set the table that holds the relation between user's and roles.
void	setUserTable(String userTable) Set the table that holds user data.
void	start() Prepare for active use of the public methods of this Component.
void	stop() Gracefully shut down active use of the public methods of this Component.

Methods inherited from class org.apache.catalina.realm.RealmBase

addLifecycleListener, addPropertyChangeListener, authenticate, authenticate, authenticate, digest, Digest, findLifecycleListeners, getContainer, getDebug, getDigest, getDigest, getInfo, getValidate, hasMessageDigest, hasRole, log, log, main, removeLifecycleListener, removePropertyChangeListener, setContainer, setDebug, setDigest, setValidate

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

dataSourceName

protected String dataSourceName

The name of the JNDI JDBC DataSource

connectionName

protected String connectionName

The connection username to use when trying to connect to the database.

connectionPassword

protected String connectionPassword

The connection URL to use when trying to connect to the database.

connectionURL

protected String connectionURL

The connection URL to use when trying to connect to the database.

dbConnection

protected Connection dbConnection

The connection to the database.

driver

protected Driver driver

Instance of the JDBC Driver class we use as a connection factory.

driverName

protected String driverName

The JDBC driver to use.

info

protected static final String info

Descriptive information about this Realm implementation.

See Also:

Constant Field Values

name

protected static final String name

Descriptive information about this Realm implementation.

See Also:

Constant Field Values

preparedCredentials

protected PreparedStatement preparedCredentials

The PreparedStatement to use for authenticating users.

preparedRoles

protected PreparedStatement preparedRoles

The PreparedStatement to use for identifying the roles for a specified user.

roleNameCol

protected String roleNameCol

The column in the user role table that names a role

sm

protected static final StringManager sm

The string manager for this package.

userCredCol

protected String userCredCol

The column in the user table that holds the user's credintials

userNameCol

protected String userNameCol

The column in the user table that holds the user's name

userRoleTable

protected String userRoleTable

The table that holds the relation between user's and roles

userTable

protected String userTable

The table that holds user data.

Constructor Detail

JDBCEncryptionRealm

public JDBCEncryptionRealm()

Method Detail

getDataSourceName

public String getDataSourceName()

Return the name of the JNDI JDBC DataSource.

Returns:

Name of the JNDI JDBC DataSource

Since:

1.3

setDataSourceName

public void setDataSourceName(String dataSourceName)

Set the name of the JNDI JDBC DataSource.

Parameters:

dataSourceName - the name of the JNDI JDBC DataSource

Since:

1.3

getConnectionName

public String getConnectionName()

Return the username to use to connect to the database.

Returns:

Username to use to connect to the database

setConnectionName

public void setConnectionName(String connectionName)

Set the username to use to connect to the database.

Parameters:

connectionName - Username

getConnectionPassword

public String getConnectionPassword()

Return the password to use to connect to the database.

Returns:

Password to use to connect to the database

setConnectionPassword

public void setConnectionPassword(String connectionPassword)

Set the password to use to connect to the database.

Parameters:

connectionPassword - User password

getConnectionURL

public String getConnectionURL()

Return the URL to use to connect to the database.

Returns:

URL to use to connect to the database

setConnectionURL

public void setConnectionURL(String connectionURL)

Set the URL to use to connect to the database.

Parameters:

connectionURL - The new connection URL

getDriverName

public String getDriverName()

Return the JDBC driver that will be used.

Returns:

JDBC driver that will be used

setDriverName

public void setDriverName(String driverName)

Set the JDBC driver that will be used.

Parameters:

driverName - The driver name

getRoleNameCol

public String getRoleNameCol()

Return the column in the user role table that names a role.

Returns:

Column in the user role table that names a role

setRoleNameCol

public void setRoleNameCol(String roleNameCol)

Set the column in the user role table that names a role.

Parameters:

roleNameCol - The column name

getUserCredCol

public String getUserCredCol()

Return the column in the user table that holds the user's credentials.

Returns:

Column in the user table that holds the user's credentials

setUserCredCol

public void setUserCredCol(String userCredCol)

Set the column in the user table that holds the user's credentials.

Parameters:

userCredCol - The column name

getUserNameCol

public String getUserNameCol()

Return the column in the user table that holds the user's name.

Returns:

Column in the user table that holds the user's name

setUserNameCol

public void setUserNameCol(String userNameCol)

Set the column in the user table that holds the user's name.

Parameters:

userNameCol - The column name

getUserRoleTable

public String getUserRoleTable()

Return the table that holds the relation between user's and roles.

Returns:

Table that holds the relation between user's and roles

setUserRoleTable

public void setUserRoleTable(String userRoleTable)

Set the table that holds the relation between user's and roles.

Parameters:

userRoleTable - The table name

getUserTable

public String getUserTable()

Return the table that holds user data.

Returns:

Table that holds user data

setUserTable

public void setUserTable(String userTable)

Set the table that holds user data.

Parameters:

userTable - The table name

setEncryptionClass

public void setEncryptionClass(String encryptionClass)

Setter for property encryptionClass.

Parameters:

encryptionClass - New value of property encryptionClass.

getEncryptionClass

public String getEncryptionClass()

Return the class used for encryption

Returns:

Class used for encryption

setEncryptionMethod

public void setEncryptionMethod(String encryptionMethod)

Setter for property encryptionMethod.

Parameters:

encryptionMethod - New value of property encryptionMethod.

getEncryptionMethod

public String getEncryptionMethod()

Return the method used for encryption

Returns:

Method used for encryption

setRoleSelect

public void setRoleSelect(String roleSelect)

Setter for property roleSelect. This, if set is used as an override for creating the complete prepared statement for retriving the list of roles from the database.

Parameters:

roleSelect - New value of property roleSelect.

getRoleSelect

public String getRoleSelect()

Return the alternative select statement for reading the roles

Returns:

Alternative select statement for reading the roles

getUserClause

public String getUserClause()

Getter for property userClause.

Returns:

Value of property userClause.

setUserClause

public void setUserClause(String userClause)

Setter for property userClause.

Parameters:

userClause - New value of property userClause.

authenticate

public Principal authenticate(String username,
                              String credentials)

Return the Principal associated with the specified username and credentials, if there is one; otherwise return null. If there are any errors with the JDBC connection, executing the query or anything we return null (don't authenticate). This event is also logged, and the connection will be closed so that a subsequent request will automatically re-open it.

Parameters:

username - Username of the Principal to look up

credentials - Password or other credentials to use in authenticating this username

Returns:

Authenticated principle object, with role access defined

close

protected void close(Connection dbConnection)

Close the specified database connection.

Parameters:

dbConnection - The connection to be closed

credentials

protected PreparedStatement credentials(Connection dbConnection,
                                        String username)
                                 throws SQLException

Return a PreparedStatement configured to perform the SELECT required to retrieve user credentials for the specified username.

Parameters:

dbConnection - The database connection to be used

username - Username for which credentials should be retrieved

Returns:

PreparedStatement to read user's password

Throws:

SQLException - if a database error occurs

getName

protected String getName()

Return a short name for this Realm implementation.

Returns:

Short name for this Realm implementation

getPassword

protected String getPassword(String username)

Not Implemented - Return the password associated with the given principal's user name.

Parameters:

username - User's Name

Returns:

Returns null in all cases

getPrincipal

protected Principal getPrincipal(String username)

Not Implemented - Return the Principal associated with the given user name.

Parameters:

username - User's Name

Returns:

Returns null in all cases

open

protected Connection open()
                   throws SQLException

Open (if necessary) and return a database connection for use by this Realm. Tries to use a data source if defined, otherwise open a direct connection using the specified database driver

Returns:

Connection to the database

Throws:

SQLException - if a database error occurs

release

protected void release(Connection dbConnection)
                throws SQLException

Release our use of this connection so that it can be recycled. Only puts the connection back in the pool if using a DataSource, otherwise the connection is held open.

Parameters:

dbConnection - Connection to release

Throws:

SQLException - If there is an error with the database

roles

protected PreparedStatement roles(Connection dbConnection,
                                  String username)
                           throws SQLException

Return a PreparedStatement configured to perform the SELECT required to retrieve user roles for the specified username.

Parameters:

dbConnection - The database connection to be used

username - Username for which roles should be retrieved

Returns:

PreparedStatement to read user's roles

Throws:

SQLException - if a database error occurs

start

public void start()
           throws LifecycleException

Prepare for active use of the public methods of this Component.

Throws:

LifecycleException - if this component detects a fatal error that prevents it from being started

stop

public void stop()
          throws LifecycleException

Gracefully shut down active use of the public methods of this Component.

Throws:

LifecycleException - if this component detects a fatal error that needs to be reported