RealmBase (Catalina Internal API Documentation)

org.apache.catalina.realm
Class RealmBase


java.lang.Object

  |

  +--org.apache.catalina.realm.RealmBase

All Implemented Interfaces:
Lifecycle, Realm
Direct Known Subclasses:
JDBCRealm, JNDIRealm, MemoryRealm

public abstract class RealmBase
extends java.lang.Object
implements Lifecycle, Realm

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.7.2.1 $ $Date: 2002/02/26 00:50:08 $
Author:
Craig R. McClanahan

Field Summary
protected  Container container
          The Container with which this Realm is associated.
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 static java.lang.String info
          Descriptive information about this Realm implementation.
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 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  boolean validate
          Should we validate client certificate chains when they are presented?
 
Fields inherited from interface org.apache.catalina.Lifecycle
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.
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.
 Container getContainer()
          Return the Container with which this Realm has been associated.
 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 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.
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.
 boolean getValidate()
          Return the "validate certificate chains" flag.
protected  boolean hasMessageDigest()
           
 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.
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 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 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?

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.

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

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

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:
java.lang.IllegalStateException - if this component has already been started
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:
java.lang.IllegalStateException - if this component has not been started
LifecycleException - if this component detects a fatal error that needs to be reported

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



Copyright © 2000-2001 Apache Software Foundation. All Rights Reserved.