org.apache.catalina.realm
Class RealmBase

java.lang.Object
  org.apache.catalina.util.LifecycleBase
      org.apache.catalina.util.LifecycleMBeanBase
          org.apache.catalina.realm.RealmBase

All Implemented Interfaces:

MBeanRegistration, Lifecycle, Realm

Direct Known Subclasses:

CombinedRealm, DataSourceRealm, JAASRealm, JDBCRealm, JNDIRealm, MemoryRealm, NullRealm, UserDatabaseRealm

public abstract class RealmBase
extends LifecycleMBeanBase
implements 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:

$Id: RealmBase.java 1303339 2012-03-21 10:03:18Z markt $

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 String	digest Digest algorithm used in storing passwords in a non-plaintext format.
protected String	digestEncoding The encoding charset for the digest.
protected static String	info Descriptive information about this Realm implementation.
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 String	realmPath
protected static StringManager	sm The string manager for this package.
protected boolean	stripRealmForGss When processing users authenticated via the GSS-API, should any "@...
protected PropertyChangeSupport	support The property change support for this component.
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 String	x509UsernameRetrieverClassName The name of the class to use for retrieving user names from X509 certificates.

Fields inherited from class org.apache.catalina.util.LifecycleMBeanBase

mserver

Fields inherited from interface org.apache.catalina.Lifecycle

AFTER_DESTROY_EVENT, AFTER_INIT_EVENT, AFTER_START_EVENT, AFTER_STOP_EVENT, BEFORE_DESTROY_EVENT, BEFORE_INIT_EVENT, BEFORE_START_EVENT, BEFORE_STOP_EVENT, CONFIGURE_START_EVENT, CONFIGURE_STOP_EVENT, PERIODIC_EVENT, START_EVENT, STOP_EVENT

Constructor Summary

RealmBase()

Method Summary

void	addPropertyChangeListener(PropertyChangeListener listener) Add a property change listener to this component.
Principal	authenticate(GSSContext gssContext, boolean storeCred) Return the Principal associated with the specified GSSContext.
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(X509Certificate[] certs) Return the Principal associated with the specified chain of X509 client certificates.
void	backgroundProcess() Execute a periodic task, such as reloading, etc.
protected String	digest(String credentials) Digest the password using the specified algorithm and convert the result to a corresponding hexadecimal string.
static String	Digest(String credentials, String algorithm, String encoding) Digest password using the algorithm specified and convert the result to a corresponding hex string.
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.
String	getAllRolesMode() Return the all roles mode.
Container	getContainer() Return the Container with which this Realm has been associated.
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.
protected Charset	getDigestCharset()
String	getDigestEncoding() Returns the digest encoding charset.
String	getDomainInternal() Method implemented by sub-classes to identify the domain in which MBeans should be registered.
String	getInfo() Return descriptive information about this Realm implementation and the corresponding version number, in the format <description>/<version>.
protected abstract String	getName() Return a short name for this Realm implementation, for use in log messages.
String	getObjectNameKeyProperties() Allow sub-classes to specify the key properties component of the ObjectName that will be used to register this component.
protected abstract String	getPassword(String username) Return the password associated with the given principal's user name.
protected abstract Principal	getPrincipal(String username) Return the Principal associated with the given user name.
protected Principal	getPrincipal(String username, GSSCredential gssCredential)
protected Principal	getPrincipal(X509Certificate usercert) Return the Principal associated with the given certificate.
String	getRealmPath()
protected String	getRealmSuffix()
protected Server	getServer() Return the Server object that is the ultimate parent for the container with which this Realm is associated.
boolean	getValidate() Return the "validate certificate chains" flag.
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(Wrapper wrapper, 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(Request request, Response response, SecurityConstraint[] constraints) Enforce any user data constraint required by the security constraint guarding this request URI.
protected void	initInternal() Sub-classes wishing to perform additional initialization should override this method, ensuring that super.initInternal() is the first call in the overriding method.
boolean	isStripRealmForGss()
static void	main(String[] args) Digest password using the algorithm specified and convert the result to a corresponding hex string.
void	removePropertyChangeListener(PropertyChangeListener listener) Remove a property change listener from this component.
void	setAllRolesMode(String allRolesMode) Set the all roles mode.
void	setContainer(Container container) Set the Container with which this Realm has been associated.
void	setDigest(String digest) Set the digest algorithm used for storing credentials.
void	setDigestEncoding(String charset) Sets the digest encoding charset.
void	setRealmPath(String theRealmPath)
void	setStripRealmForGss(boolean stripRealmForGss)
void	setValidate(boolean validate) Set the "validate certificate chains" flag.
void	setX509UsernameRetrieverClassName(String className) Sets the name of the class that will be used to extract user names from X509 client certificates.
protected void	startInternal() Prepare for the beginning of active use of the public methods of this component and implement the requirements of LifecycleBase.startInternal().
protected void	stopInternal() Gracefully terminate the active use of the public methods of this component and implement the requirements of LifecycleBase.stopInternal().
String	toString() Return a String representation of this component.

Methods inherited from class org.apache.catalina.util.LifecycleMBeanBase

destroyInternal, getDomain, getObjectName, postDeregister, postRegister, preDeregister, preRegister, register, setDomain, unregister

Methods inherited from class org.apache.catalina.util.LifecycleBase

addLifecycleListener, destroy, findLifecycleListeners, fireLifecycleEvent, getState, getStateName, init, removeLifecycleListener, setState, setState, start, stop

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, 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 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 encoding charset for the digest.

info

protected static final String info

Descriptive information about this Realm implementation.

See Also:

Constant Field Values

md

protected volatile 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 volatile MessageDigest md5Helper

MD5 message digest provider.

sm

protected static final StringManager sm

The string manager for this package.

support

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

stripRealmForGss

protected boolean stripRealmForGss

When processing users authenticated via the GSS-API, should any "@..." be stripped from the end of the user name?

realmPath

protected String realmPath

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

Return the all roles mode.

setAllRolesMode

public void setAllRolesMode(String allRolesMode)

Set the all roles mode.

getDigest

public String getDigest()

Return the digest algorithm used for storing credentials.

setDigest

public void setDigest(String digest)

Set the digest algorithm used for storing credentials.

Parameters:

digest - The new digest algorithm

getDigestEncoding

public String getDigestEncoding()

Returns the digest encoding charset.

Returns:

The charset (may be null) for platform default

setDigestEncoding

public void setDigestEncoding(String charset)

Sets the digest encoding charset.

Parameters:

charset - The charset (null for platform default)

getDigestCharset

protected Charset getDigestCharset()
                            throws UnsupportedEncodingException

Throws:

UnsupportedEncodingException

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

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

Sets the name of the class that will be used to extract user names from X509 client certificates. The class must implement (@link X509UsernameRetriever}.

Parameters:

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

isStripRealmForGss

public boolean isStripRealmForGss()

setStripRealmForGss

public void setStripRealmForGss(boolean stripRealmForGss)

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

authenticate

public Principal authenticate(GSSContext gssContext,
                              boolean storeCred)

Return the Principal associated with the specified GSSContext. If there is none, return null.

Specified by:

authenticate in interface Realm

Parameters:

gssContext - The gssContext processed by the Authenticator.

storeCred - Should the realm attempt to store the delegated credentials in the returned Principal?

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

IOException - if an input/output error occurs

hasRole

public boolean hasRole(Wrapper wrapper,
                       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

wrapper - wrapper context for evaluating role

hasUserDataPermission

public boolean hasUserDataPermission(Request request,
                                     Response 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.

Specified by:

hasUserDataPermission in interface Realm

Parameters:

request - Request we are processing

response - Response we are creating

constraints - Security constraint being checked

Throws:

IOException - if an input/output error occurs

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

initInternal

protected void initInternal()
                     throws LifecycleException

Description copied from class: LifecycleMBeanBase

Sub-classes wishing to perform additional initialization should override this method, ensuring that super.initInternal() is the first call in the overriding method.

Overrides:

initInternal in class LifecycleMBeanBase

Throws:

LifecycleException

startInternal

protected void startInternal()
                      throws LifecycleException

Prepare for the beginning of active use of the public methods of this component and implement the requirements of LifecycleBase.startInternal().

Specified by:

startInternal in class LifecycleBase

Throws:

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

stopInternal

protected void stopInternal()
                     throws LifecycleException

Gracefully terminate the active use of the public methods of this component and implement the requirements of LifecycleBase.stopInternal().

Specified by:

stopInternal in class LifecycleBase

Throws:

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

toString

public String toString()

Return a String representation of this component.

Overrides:

toString in class Object

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.

Parameters:

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

hasMessageDigest

protected boolean hasMessageDigest()

getDigest

protected String getDigest(String username,
                           String realmName)

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

getName

protected abstract String getName()

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

getPassword

protected abstract String getPassword(String username)

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

getPrincipal

protected Principal getPrincipal(X509Certificate usercert)

Return the Principal associated with the given certificate.

getPrincipal

protected abstract Principal getPrincipal(String username)

Return the Principal associated with the given user name.

getPrincipal

protected Principal getPrincipal(String username,
                                 GSSCredential gssCredential)

getServer

protected Server getServer()

Return the Server object that is the ultimate parent for the container with which this Realm is associated. If the server cannot be found (eg because the container hierarchy is not complete), null is returned.

Digest

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

getObjectNameKeyProperties

public String getObjectNameKeyProperties()

Description copied from class: LifecycleMBeanBase

Allow sub-classes to specify the key properties component of the ObjectName that will be used to register this component.

Specified by:

getObjectNameKeyProperties in class LifecycleMBeanBase

Returns:

The string representation of the key properties component of the desired ObjectName

getDomainInternal

public String getDomainInternal()

Description copied from class: LifecycleMBeanBase

Method implemented by sub-classes to identify the domain in which MBeans should be registered.

Specified by:

getDomainInternal in class LifecycleMBeanBase

Returns:

The name of the domain to use to register MBeans.

getRealmPath

public String getRealmPath()

setRealmPath

public void setRealmPath(String theRealmPath)

getRealmSuffix

protected String getRealmSuffix()