## 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.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 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` `digestEncoding` The digest encoding charset.
`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` `getDigestEncoding()` Returns the digest encoding charset.
`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` `setDigestEncoding(java.lang.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.

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.

### digestEncoding

    protected java.lang.String digestEncoding

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

### 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

### getDigestEncoding

    public java.lang.String getDigestEncoding()

  Returns the digest encoding charset.

  Returns:
    The digest (null means platform default)

### setDigestEncoding

    public void setDigestEncoding(java.lang.String charset)

  Sets the digest encoding charset.

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

### 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()

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