Apache Tomcat 6.0.43

org.apache.catalina.realm
Class RealmBase

java.lang.Object
  extended by org.apache.catalina.realm.RealmBase
All Implemented Interfaces:
javax.management.MBeanRegistration, Lifecycle, Realm
Direct Known Subclasses:
CombinedRealm, 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.

Author:
Craig R. McClanahan

Nested Class Summary
protected static class RealmBase.AllRolesMode
           
 
Field Summary
protected  RealmBase.AllRolesMode allRolesMode
          The all role mode.
protected  Container container
          The Container with which this Realm is associated.
protected  Log containerLog
          Container log
protected  javax.management.ObjectName controller
           
protected  java.lang.String digest
          Digest algorithm used in storing passwords in a non-plaintext format.
protected  java.lang.String digestEncoding
          The encoding charset for the digest.
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  java.lang.String realmPath
           
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?
protected  X509UsernameRetriever x509UsernameRetriever
          The object that will extract user names from X509 client certificates.
protected  java.lang.String x509UsernameRetrieverClassName
          The name of the class to use for retrieving user names from X509 certificates.
 
Fields inherited from interface org.apache.catalina.Lifecycle
AFTER_START_EVENT, AFTER_STOP_EVENT, BEFORE_START_EVENT, BEFORE_STOP_EVENT, DESTROY_EVENT, INIT_EVENT, PERIODIC_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 backgroundProcess()
          Execute a periodic task, such as reloading, etc.
 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, java.lang.String encoding)
          Digest password using the algorithm specified and convert the result to a corresponding hex string.
 LifecycleListener[] findLifecycleListeners()
          Get the lifecycle listeners associated with this lifecycle.
 SecurityConstraint[] findSecurityConstraints(Request request, Context context)
          Return the SecurityConstraints configured to guard the request URI for this request, or null if there is no such constraint.
 java.lang.String getAllRolesMode()
          Return the all roles mode.
 Container getContainer()
          Return the Container with which this Realm has been associated.
 javax.management.ObjectName getController()
           
 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.
protected  java.security.Principal getPrincipal(java.security.cert.X509Certificate usercert)
          Return the Principal associated with the given certificate.
 java.lang.String getRealmPath()
           
protected  java.lang.String getRealmSuffix()
           
 java.lang.String getType()
           
 boolean getValidate()
          Return the "validate certificate chains" flag.
 java.lang.String getX509UsernameRetrieverClassName()
          Gets the name of the class that will be used to extract user names from X509 client certificates.
protected  boolean hasMessageDigest()
           
 boolean hasResourcePermission(Request request, Response 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(Request request, Response response, SecurityConstraint[] constraints)
          Enforce any user data constraint required by the security constraint guarding this request URI.
 void init()
           
static void main(java.lang.String[] args)
          Digest password using the algorithm specified 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 setAllRolesMode(java.lang.String allRolesMode)
          Set the all roles mode.
 void setContainer(Container container)
          Set the Container with which this Realm has been associated.
 void setController(javax.management.ObjectName controller)
           
 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 setRealmPath(java.lang.String theRealmPath)
           
 void setValidate(boolean validate)
          Set the "validate certificate chains" flag.
 void setX509UsernameRetrieverClassName(java.lang.String className)
          Sets the name of the class that will be used to extract user names from X509 client certificates.
 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.


containerLog

protected Log containerLog
Container log


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 encoding charset for the digest.


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?


x509UsernameRetrieverClassName

protected java.lang.String x509UsernameRetrieverClassName
The name of the class to use for retrieving user names from X509 certificates.


x509UsernameRetriever

protected X509UsernameRetriever x509UsernameRetriever
The object that will extract user names from X509 client certificates.


allRolesMode

protected RealmBase.AllRolesMode allRolesMode
The all role mode.


type

protected java.lang.String type

domain

protected java.lang.String domain

host

protected java.lang.String host

path

protected java.lang.String path

realmPath

protected java.lang.String realmPath

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

getAllRolesMode

public java.lang.String getAllRolesMode()
Return the all roles mode.


setAllRolesMode

public void setAllRolesMode(java.lang.String allRolesMode)
Set the all roles mode.


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 charset (may be null) for platform default

setDigestEncoding

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

Parameters:
charset - The charset (null for 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

getX509UsernameRetrieverClassName

public java.lang.String getX509UsernameRetrieverClassName()
Gets the name of the class that will be used to extract user names from X509 client certificates.

Returns:
The name of the class that will be used to extract user names from X509 client certificates.

setX509UsernameRetrieverClassName

public void setX509UsernameRetrieverClassName(java.lang.String className)
Sets the name of the class that will be used to extract user names from X509 client certificates. The class must implement X509UsernameRetriever.

Parameters:
className - The name of the class that will be used to extract user names from X509 client certificates.
See Also:
X509UsernameRetriever

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.

backgroundProcess

public void backgroundProcess()
Execute a periodic task, such as reloading, etc. This method will be invoked inside the classloading context of this container. Unexpected throwables will be caught and logged.

Specified by:
backgroundProcess in interface Realm

findSecurityConstraints

public SecurityConstraint[] findSecurityConstraints(Request 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(Request request,
                                     Response 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(Request request,
                                     Response 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.

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 java.security.Principal getPrincipal(java.security.cert.X509Certificate usercert)
Return the Principal associated with the given certificate.


getPrincipal

protected abstract java.security.Principal getPrincipal(java.lang.String username)
Return the Principal associated with the given user name.


Digest

public static final java.lang.String Digest(java.lang.String credentials,
                                            java.lang.String algorithm,
                                            java.lang.String encoding)
Digest password using the algorithm specified 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 the digest
encoding - Character encoding of the string to digest

main

public static void main(java.lang.String[] args)
Digest password using the algorithm specified 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()

getRealmPath

public java.lang.String getRealmPath()

setRealmPath

public void setRealmPath(java.lang.String theRealmPath)

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

getRealmSuffix

protected java.lang.String getRealmSuffix()

Apache Tomcat 6.0.43

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