org.apache.catalina.realm
Class RealmBase

java.lang.Object
  org.apache.catalina.realm.RealmBase

All Implemented Interfaces:

Lifecycle, javax.management.MBeanRegistration, Realm

Direct Known Subclasses:

DataSourceRealm, JAASRealm, JDBCRealm, JNDIRealm, MemoryRealm, UserDatabaseRealm

public abstract class RealmBase

extends java.lang.Object

implements Lifecycle, Realm, javax.management.MBeanRegistration

Simple implementation of Realm that reads an XML file to configure the valid users, passwords, and roles. The file format (and default file location) are identical to those currently supported by Tomcat 3.X.

Version:

$Revision: 1.33 $ $Date: 2004/05/26 15:51:25 $

Author:

Craig R. McClanahan

Field Summary

protected Container	container The Container with which this Realm is associated.
protected javax.management.ObjectName	controller
protected int	debug The debugging detail level for this component.
protected java.lang.String	digest Digest algorithm used in storing passwords in a non-plaintext format.
protected java.lang.String	domain
protected java.lang.String	host
protected static java.lang.String	info Descriptive information about this Realm implementation.
protected boolean	initialized
protected LifecycleSupport	lifecycle The lifecycle event support for this component.
protected java.security.MessageDigest	md The MessageDigest object for digesting user credentials (passwords).
protected static MD5Encoder	md5Encoder The MD5 helper object for this class.
protected static java.security.MessageDigest	md5Helper MD5 message digest provider.
protected javax.management.MBeanServer	mserver
protected javax.management.ObjectName	oname
protected java.lang.String	path
protected static StringManager	sm The string manager for this package.
protected boolean	started Has this component been started?
protected java.beans.PropertyChangeSupport	support The property change support for this component.
protected java.lang.String	type
protected boolean	validate Should we validate client certificate chains when they are presented?

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

RealmBase()

Method Summary

void	addLifecycleListener(LifecycleListener listener) Add a lifecycle event listener to this component.
void	addPropertyChangeListener(java.beans.PropertyChangeListener listener) Add a property change listener to this component.
java.security.Principal	authenticate(java.lang.String username, byte[] credentials) Return the Principal associated with the specified username and credentials, if there is one; otherwise return null.
java.security.Principal	authenticate(java.lang.String username, java.lang.String credentials) Return the Principal associated with the specified username and credentials, if there is one; otherwise return null.
java.security.Principal	authenticate(java.lang.String username, java.lang.String clientDigest, java.lang.String nOnce, java.lang.String nc, java.lang.String cnonce, java.lang.String qop, java.lang.String realm, java.lang.String md5a2) Return the Principal associated with the specified username, which matches the digest calculated using the given parameters using the method described in RFC 2069; otherwise return null.
java.security.Principal	authenticate(java.security.cert.X509Certificate[] certs) Return the Principal associated with the specified chain of X509 client certificates.
void	destroy()
protected java.lang.String	digest(java.lang.String credentials) Digest the password using the specified algorithm and convert the result to a corresponding hexadecimal string.
static java.lang.String	Digest(java.lang.String credentials, java.lang.String algorithm) Digest password using the algorithm especificied and convert the result to a corresponding hex string.
LifecycleListener[]	findLifecycleListeners() Get the lifecycle listeners associated with this lifecycle.
SecurityConstraint[]	findSecurityConstraints(HttpRequest request, Context context) Return the SecurityConstraints configured to guard the request URI for this request, or null if there is no such constraint.
Container	getContainer() Return the Container with which this Realm has been associated.
javax.management.ObjectName	getController()
int	getDebug() Return the debugging detail level for this component.
java.lang.String	getDigest() Return the digest algorithm used for storing credentials.
protected java.lang.String	getDigest(java.lang.String username, java.lang.String realmName) Return the digest associated with given principal's user name.
java.lang.String	getDomain()
java.lang.String	getInfo() Return descriptive information about this Realm implementation and the corresponding version number, in the format <description>/<version>.
protected abstract java.lang.String	getName() Return a short name for this Realm implementation, for use in log messages.
javax.management.ObjectName	getObjectName()
protected abstract java.lang.String	getPassword(java.lang.String username) Return the password associated with the given principal's user name.
protected abstract java.security.Principal	getPrincipal(java.lang.String username) Return the Principal associated with the given user name.
java.lang.String	getType()
boolean	getValidate() Return the "validate certificate chains" flag.
protected boolean	hasMessageDigest()
boolean	hasResourcePermission(HttpRequest request, HttpResponse response, SecurityConstraint[] constraints, Context context) Perform access control based on the specified authorization constraint.
boolean	hasRole(java.security.Principal principal, java.lang.String role) Return true if the specified Principal has the specified security role, within the context of this Realm; otherwise return false.
boolean	hasUserDataPermission(HttpRequest request, HttpResponse response, SecurityConstraint[] constraints) Enforce any user data constraint required by the security constraint guarding this request URI.
void	init()
protected void	log(java.lang.String message) Log a message on the Logger associated with our Container (if any)
protected void	log(java.lang.String message, java.lang.Throwable throwable) Log a message on the Logger associated with our Container (if any)
static void	main(java.lang.String[] args) Digest password using the algorithm especificied and convert the result to a corresponding hex string.
void	postDeregister()
void	postRegister(java.lang.Boolean registrationDone)
void	preDeregister()
javax.management.ObjectName	preRegister(javax.management.MBeanServer server, javax.management.ObjectName name)
void	removeLifecycleListener(LifecycleListener listener) Remove a lifecycle event listener from this component.
void	removePropertyChangeListener(java.beans.PropertyChangeListener listener) Remove a property change listener from this component.
void	setContainer(Container container) Set the Container with which this Realm has been associated.
void	setController(javax.management.ObjectName controller)
void	setDebug(int debug) Set the debugging detail level for this component.
void	setDigest(java.lang.String digest) Set the digest algorithm used for storing credentials.
void	setValidate(boolean validate) Set the "validate certificate chains" flag.
void	start() Prepare for the beginning of active use of the public methods of this component.
void	stop() Gracefully terminate the active use of the public methods of this component.

Methods inherited from class java.lang.Object

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

Field Detail

container

protected Container container

The Container with which this Realm is associated.

debug

protected int debug

The debugging detail level for this component.

digest

protected java.lang.String digest

Digest algorithm used in storing passwords in a non-plaintext format. Valid values are those accepted for the algorithm name by the MessageDigest class, or null if no digesting should be performed.

info

protected static final java.lang.String info

Descriptive information about this Realm implementation.

See Also:

Constant Field Values

lifecycle

protected LifecycleSupport lifecycle

The lifecycle event support for this component.

md

protected java.security.MessageDigest md

The MessageDigest object for digesting user credentials (passwords).

md5Encoder

protected static final MD5Encoder md5Encoder

The MD5 helper object for this class.

md5Helper

protected static java.security.MessageDigest md5Helper

MD5 message digest provider.

sm

protected static StringManager sm

The string manager for this package.

started

protected boolean started

Has this component been started?

support

protected java.beans.PropertyChangeSupport support

The property change support for this component.

validate

protected boolean validate

Should we validate client certificate chains when they are presented?

type

protected java.lang.String type

domain

protected java.lang.String domain

host

protected java.lang.String host

path

protected java.lang.String path

oname

protected javax.management.ObjectName oname

controller

protected javax.management.ObjectName controller

mserver

protected javax.management.MBeanServer mserver

initialized

protected boolean initialized

Constructor Detail

RealmBase

public RealmBase()

Method Detail

getContainer

public Container getContainer()

Return the Container with which this Realm has been associated.

Specified by:

getContainer in interface Realm

setContainer

public void setContainer(Container container)

Set the Container with which this Realm has been associated.

Specified by:

setContainer in interface Realm

Parameters:

container - The associated Container

getDebug

public int getDebug()

Return the debugging detail level for this component.

setDebug

public void setDebug(int debug)

Set the debugging detail level for this component.

Parameters:

debug - The new debugging detail level

getDigest

public java.lang.String getDigest()

Return the digest algorithm used for storing credentials.

setDigest

public void setDigest(java.lang.String digest)

Set the digest algorithm used for storing credentials.

Parameters:

digest - The new digest algorithm

getInfo

public java.lang.String getInfo()

Return descriptive information about this Realm implementation and the corresponding version number, in the format <description>/<version>.

Specified by:

getInfo in interface Realm

getValidate

public boolean getValidate()

Return the "validate certificate chains" flag.

setValidate

public void setValidate(boolean validate)

Set the "validate certificate chains" flag.

Parameters:

validate - The new validate certificate chains flag

addPropertyChangeListener

public void addPropertyChangeListener(java.beans.PropertyChangeListener listener)

Add a property change listener to this component.

Specified by:

addPropertyChangeListener in interface Realm

Parameters:

listener - The listener to add

authenticate

public java.security.Principal authenticate(java.lang.String username,
                                            java.lang.String credentials)

Return the Principal associated with the specified username and credentials, if there is one; otherwise return null.

Specified by:

authenticate in interface Realm

Parameters:

username - Username of the Principal to look up

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

authenticate

public java.security.Principal authenticate(java.lang.String username,
                                            byte[] credentials)

Return the Principal associated with the specified username and credentials, if there is one; otherwise return null.

Specified by:

authenticate in interface Realm

Parameters:

username - Username of the Principal to look up

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

authenticate

public java.security.Principal authenticate(java.lang.String username,
                                            java.lang.String clientDigest,
                                            java.lang.String nOnce,
                                            java.lang.String nc,
                                            java.lang.String cnonce,
                                            java.lang.String qop,
                                            java.lang.String realm,
                                            java.lang.String md5a2)

Return the Principal associated with the specified username, which matches the digest calculated using the given parameters using the method described in RFC 2069; otherwise return null.

Specified by:

authenticate in interface Realm

Parameters:

username - Username of the Principal to look up

clientDigest - Digest which has been submitted by the client

nOnce - Unique (or supposedly unique) token which has been used for this request

realm - Realm name

md5a2 - Second MD5 digest used to calculate the digest : MD5(Method + ":" + uri)

authenticate

public java.security.Principal authenticate(java.security.cert.X509Certificate[] certs)

Return the Principal associated with the specified chain of X509 client certificates. If there is none, return null.

Specified by:

authenticate in interface Realm

Parameters:

certs - Array of client certificates, with the first one in the array being the certificate of the client itself.

findSecurityConstraints

public SecurityConstraint[] findSecurityConstraints(HttpRequest request,
                                                    Context context)

Return the SecurityConstraints configured to guard the request URI for this request, or null if there is no such constraint.

Specified by:

findSecurityConstraints in interface Realm

Parameters:

request - Request we are processing

context - Context the Request is mapped to

hasResourcePermission

public boolean hasResourcePermission(HttpRequest request,
                                     HttpResponse response,
                                     SecurityConstraint[] constraints,
                                     Context context)
                              throws java.io.IOException

Perform access control based on the specified authorization constraint. Return true if this constraint is satisfied and processing should continue, or false otherwise.

Specified by:

hasResourcePermission in interface Realm

Parameters:

request - Request we are processing

response - Response we are creating

constraints - Security constraint we are enforcing

context - The Context to which client of this class is attached.

Throws:

java.io.IOException - if an input/output error occurs

hasRole

public boolean hasRole(java.security.Principal principal,
                       java.lang.String role)

Return true if the specified Principal has the specified security role, within the context of this Realm; otherwise return false. This method can be overridden by Realm implementations, but the default is adequate when an instance of GenericPrincipal is used to represent authenticated Principals from this Realm.

Specified by:

hasRole in interface Realm

Parameters:

principal - Principal for whom the role is to be checked

role - Security role to be checked

hasUserDataPermission

public boolean hasUserDataPermission(HttpRequest request,
                                     HttpResponse response,
                                     SecurityConstraint[] constraints)
                              throws java.io.IOException

Enforce any user data constraint required by the security constraint guarding this request URI. Return true if this constraint was not violated and processing should continue, or false if we have created a response already.

Specified by:

hasUserDataPermission in interface Realm

Parameters:

request - Request we are processing

response - Response we are creating

constraints - Security constraint being checked

Throws:

java.io.IOException - if an input/output error occurs

removePropertyChangeListener

public void removePropertyChangeListener(java.beans.PropertyChangeListener listener)

Remove a property change listener from this component.

Specified by:

removePropertyChangeListener in interface Realm

Parameters:

listener - The listener to remove

addLifecycleListener

public void addLifecycleListener(LifecycleListener listener)

Add a lifecycle event listener to this component.

Specified by:

addLifecycleListener in interface Lifecycle

Parameters:

listener - The listener to add

findLifecycleListeners

public LifecycleListener[] findLifecycleListeners()

Get the lifecycle listeners associated with this lifecycle. If this Lifecycle has no listeners registered, a zero-length array is returned.

Specified by:

findLifecycleListeners in interface Lifecycle

removeLifecycleListener

public void removeLifecycleListener(LifecycleListener listener)

Remove a lifecycle event listener from this component.

Specified by:

removeLifecycleListener in interface Lifecycle

Parameters:

listener - The listener to remove

start

public void start()
           throws LifecycleException

Prepare for the beginning of active use of the public methods of this component. This method should be called before any of the public methods of this component are utilized. It should also send a LifecycleEvent of type START_EVENT to any registered listeners.

Specified by:

start in interface Lifecycle

Throws:

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

stop

public void stop()
          throws LifecycleException

Gracefully terminate the active use of the public methods of this component. This method should be the last one called on a given instance of this component. It should also send a LifecycleEvent of type STOP_EVENT to any registered listeners.

Specified by:

stop in interface Lifecycle

Throws:

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

destroy

public void destroy()

digest

protected java.lang.String digest(java.lang.String credentials)

Digest the password using the specified algorithm and convert the result to a corresponding hexadecimal string. If exception, the plain credentials string is returned. IMPLEMENTATION NOTE - This implementation is synchronized because it reuses the MessageDigest instance. This should be faster than cloning the instance on every request.

Parameters:

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

hasMessageDigest

protected boolean hasMessageDigest()

getDigest

protected java.lang.String getDigest(java.lang.String username,
                                     java.lang.String realmName)

Return the digest associated with given principal's user name.

getName

protected abstract java.lang.String getName()

Return a short name for this Realm implementation, for use in log messages.

getPassword

protected abstract java.lang.String getPassword(java.lang.String username)

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

getPrincipal

protected abstract java.security.Principal getPrincipal(java.lang.String username)

Return the Principal associated with the given user name.

log

protected void log(java.lang.String message)

Log a message on the Logger associated with our Container (if any)

Parameters:

message - Message to be logged

log

protected void log(java.lang.String message,
                   java.lang.Throwable throwable)

Log a message on the Logger associated with our Container (if any)

Parameters:

message - Message to be logged

throwable - Associated exception

Digest

public static final java.lang.String Digest(java.lang.String credentials,
                                            java.lang.String algorithm)

Digest password using the algorithm especificied and convert the result to a corresponding hex string. If exception, the plain credentials string is returned

Parameters:

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

algorithm - Algorithm used to do th digest

main

public static void main(java.lang.String[] args)

Digest password using the algorithm especificied and convert the result to a corresponding hex string. If exception, the plain credentials string is returned

getController

public javax.management.ObjectName getController()

setController

public void setController(javax.management.ObjectName controller)

getObjectName

public javax.management.ObjectName getObjectName()

getDomain

public java.lang.String getDomain()

getType

public java.lang.String getType()

preRegister

public javax.management.ObjectName preRegister(javax.management.MBeanServer server,
                                               javax.management.ObjectName name)
                                        throws java.lang.Exception

Specified by:

preRegister in interface javax.management.MBeanRegistration

Throws:

java.lang.Exception

postRegister

public void postRegister(java.lang.Boolean registrationDone)

Specified by:

postRegister in interface javax.management.MBeanRegistration

preDeregister

public void preDeregister()
                   throws java.lang.Exception

Specified by:

preDeregister in interface javax.management.MBeanRegistration

Throws:

java.lang.Exception

postDeregister

public void postDeregister()

Specified by:

postDeregister in interface javax.management.MBeanRegistration

init

public void init()