org.apache.catalina.realm

Class RealmBase

Implemented Interfaces:
Lifecycle, MBeanRegistration, Realm
Known Direct Subclasses:
DataSourceRealm, JAASRealm, JDBCRealm, JNDIRealm, MemoryRealm, UserDatabaseRealm

public abstract class RealmBase
extends java.lang.Object
implements Lifecycle, Realm, 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.2.2 $ $Date: 2004/10/27 16:26:18 $

Author:
Craig R. McClanahan

Field Summary

protected Container
container
The Container with which this Realm is associated.
protected ObjectName
controller
protected int
debug
The debugging detail level for this component.
protected String
digest
Digest algorithm used in storing passwords in a non-plaintext format.
protected String
digestEncoding
The digest encoding charset.
protected String
domain
protected String
host
protected static String
info
Descriptive information about this Realm implementation.
protected boolean
initialized
protected LifecycleSupport
lifecycle
The lifecycle event support for this component.
protected MessageDigest
md
The MessageDigest object for digesting user credentials (passwords).
protected static MD5Encoder
md5Encoder
The MD5 helper object for this class.
protected static MessageDigest
md5Helper
MD5 message digest provider.
protected MBeanServer
mserver
protected ObjectName
oname
protected String
path
protected static StringManager
sm
The string manager for this package.
protected boolean
started
Has this component been started?
protected PropertyChangeSupport
support
The property change support for this component.
protected 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

Method Summary

static String
Digest(String credentials, String algorithm)
Digest password using the algorithm especificied and convert the result to a corresponding hex string.
void
addLifecycleListener(LifecycleListener listener)
Add a lifecycle event listener to this component.
void
addPropertyChangeListener(PropertyChangeListener listener)
Add a property change listener to this component.
Principal
authenticate(String username, String credentials)
Return the Principal associated with the specified username and credentials, if there is one; otherwise return null.
Principal
authenticate(String username, String clientDigest, String nOnce, String nc, String cnonce, String qop, String realm, 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.
Principal
authenticate(String username, byte[] credentials)
Return the Principal associated with the specified username and credentials, if there is one; otherwise return null.
Principal
authenticate(certs[] )
Return the Principal associated with the specified chain of X509 client certificates.
void
destroy()
protected String
digest(String credentials)
Digest the password using the specified algorithm and convert the result to a corresponding hexadecimal 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.
ObjectName
getController()
int
getDebug()
Return the debugging detail level for this component.
String
getDigest()
Return the digest algorithm used for storing credentials.
protected String
getDigest(String username, String realmName)
Return the digest associated with given principal's user name.
String
getDigestEncoding()
Returns the digest encoding charset.
String
getDomain()
String
getInfo()
Return descriptive information about this Realm implementation and the corresponding version number, in the format <description>/<version>.
protected String
getName()
Return a short name for this Realm implementation, for use in log messages.
ObjectName
getObjectName()
protected String
getPassword(String username)
Return the password associated with the given principal's user name.
protected Principal
getPrincipal(String username)
Return the Principal associated with the given user name.
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(Principal principal, 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(String message)
Log a message on the Logger associated with our Container (if any)
protected void
log(String message, Throwable throwable)
Log a message on the Logger associated with our Container (if any)
static void
main(args[] )
Digest password using the algorithm especificied and convert the result to a corresponding hex string.
void
postDeregister()
void
postRegister(Boolean registrationDone)
void
preDeregister()
ObjectName
preRegister(MBeanServer server, ObjectName name)
void
removeLifecycleListener(LifecycleListener listener)
Remove a lifecycle event listener from this component.
void
removePropertyChangeListener(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(ObjectName controller)
void
setDebug(int debug)
Set the debugging detail level for this component.
void
setDigest(String digest)
Set the digest algorithm used for storing credentials.
void
setDigestEncoding(String charset)
Sets the digest encoding charset.
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.

Field Details

container

protected Container container
The Container with which this Realm is associated.


controller

protected ObjectName controller


debug

protected int debug
The debugging detail level for this component.


digest

protected 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.


digestEncoding

protected String digestEncoding
The digest encoding charset. Null (the default) means use the platform default encoding.


domain

protected String domain


host

protected String host


info

protected static final String info
Descriptive information about this Realm implementation.


initialized

protected boolean initialized


lifecycle

protected LifecycleSupport lifecycle
The lifecycle event support for this component.


md

protected 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 MessageDigest md5Helper
MD5 message digest provider.


mserver

protected MBeanServer mserver


oname

protected ObjectName oname


path

protected String path


sm

protected static StringManager sm
The string manager for this package.


started

protected boolean started
Has this component been started?


support

protected PropertyChangeSupport support
The property change support for this component.


type

protected String type


validate

protected boolean validate
Should we validate client certificate chains when they are presented?

Method Details

Digest

public static final String Digest(String credentials,
                                  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


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


addPropertyChangeListener

public void addPropertyChangeListener(PropertyChangeListener listener)
Add a property change listener to this component.
Specified by:
addPropertyChangeListener in interface Realm

Parameters:
listener - The listener to add


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.
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 Principal authenticate(String username,
                              String clientDigest,
                              String nOnce,
                              String nc,
                              String cnonce,
                              String qop,
                              String realm,
                              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 Principal authenticate(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 Principal authenticate(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:


destroy

public void destroy()


digest

protected String digest(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


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


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


getContainer

public Container getContainer()
Return the Container with which this Realm has been associated.
Specified by:
getContainer in interface Realm


getController

public ObjectName getController()


getDebug

public int getDebug()
Return the debugging detail level for this component.


getDigest

public String getDigest()
Return the digest algorithm used for storing credentials.


getDigest

protected String getDigest(String username,
                           String realmName)
Return the digest associated with given principal's user name.


getDigestEncoding

public String getDigestEncoding()
Returns the digest encoding charset.

Returns:
The digest (null means platform default)


getDomain

public String getDomain()


getInfo

public 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


getName

protected String getName()
Return a short name for this Realm implementation, for use in log messages.


getObjectName

public ObjectName getObjectName()


getPassword

protected String getPassword(String username)
Return the password associated with the given principal's user name.


getPrincipal

protected Principal getPrincipal(String username)
Return the Principal associated with the given user name.


getType

public String getType()


getValidate

public boolean getValidate()
Return the "validate certificate chains" flag.


hasMessageDigest

protected boolean hasMessageDigest()


hasResourcePermission

public boolean hasResourcePermission(HttpRequest request,
                                     HttpResponse response,
                                     SecurityConstraint[] constraints,
                                     Context context)
            throws IOException
Perform access control based on the specified authorization constraint. Return true if this constraint is satisfied and processing should continue, or false otherwise.

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.


hasRole

public boolean hasRole(Principal principal,
                       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 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.

Parameters:
request - Request we are processing
response - Response we are creating
constraints - Security constraint being checked


init

public void init()


log

protected void log(String message)
Log a message on the Logger associated with our Container (if any)

Parameters:
message - Message to be logged


log

protected void log(String message,
                   Throwable throwable)
Log a message on the Logger associated with our Container (if any)

Parameters:
message - Message to be logged
throwable - Associated exception


main

public static void main(args[] )
Digest password using the algorithm especificied and convert the result to a corresponding hex string. If exception, the plain credentials string is returned


postDeregister

public void postDeregister()


postRegister

public void postRegister(Boolean registrationDone)


preDeregister

public void preDeregister()
            throws Exception


preRegister

public ObjectName preRegister(MBeanServer server,
                              ObjectName name)
            throws Exception


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


removePropertyChangeListener

public void removePropertyChangeListener(PropertyChangeListener listener)
Remove a property change listener from this component.
Specified by:
removePropertyChangeListener in interface Realm

Parameters:
listener - The listener to remove


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


setController

public void setController(ObjectName controller)


setDebug

public void setDebug(int debug)
Set the debugging detail level for this component.

Parameters:
debug - The new debugging detail level


setDigest

public void setDigest(String digest)
Set the digest algorithm used for storing credentials.

Parameters:
digest - The new digest algorithm


setDigestEncoding

public void setDigestEncoding(String charset)
Sets the digest encoding charset.

Parameters:
charset - The charset (null means platform default)


setValidate

public void setValidate(boolean validate)
Set the "validate certificate chains" flag.

Parameters:
validate - The new validate certificate chains flag


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


Copyright B) 2000-2003 Apache Software Foundation. All Rights Reserved.