org.apache.catalina.realm

Class RealmBase

public abstract class RealmBase extends 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: 781465 $ $Date: 2009-06-03 18:38:25 +0200 (Wed, 03 Jun 2009) $

Author: Craig R. McClanahan

Nested Class Summary
protected static classRealmBase.AllRolesMode
Field Summary
protected RealmBase.AllRolesModeallRolesMode
The all role mode.
protected Containercontainer
The Container with which this Realm is associated.
protected LogcontainerLog
Container log
protected ObjectNamecontroller
protected Stringdigest
Digest algorithm used in storing passwords in a non-plaintext format.
protected StringdigestEncoding
The encoding charset for the digest.
protected Stringdomain
protected Stringhost
protected static Stringinfo
Descriptive information about this Realm implementation.
protected booleaninitialized
protected LifecycleSupportlifecycle
The lifecycle event support for this component.
protected MessageDigestmd
The MessageDigest object for digesting user credentials (passwords).
protected static MD5Encodermd5Encoder
The MD5 helper object for this class.
protected static MessageDigestmd5Helper
MD5 message digest provider.
protected MBeanServermserver
protected ObjectNameoname
protected Stringpath
protected StringrealmPath
protected static StringManagersm
The string manager for this package.
protected booleanstarted
Has this component been started?
protected PropertyChangeSupportsupport
The property change support for this component.
protected Stringtype
protected booleanvalidate
Should we validate client certificate chains when they are presented?
Method Summary
voidaddLifecycleListener(LifecycleListener listener)
Add a lifecycle event listener to this component.
voidaddPropertyChangeListener(PropertyChangeListener listener)
Add a property change listener to this component.
Principalauthenticate(String username, String credentials)
Return the Principal associated with the specified username and credentials, if there is one; otherwise return null.
Principalauthenticate(String username, byte[] credentials)
Return the Principal associated with the specified username and credentials, if there is one; otherwise return null.
Principalauthenticate(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.
Principalauthenticate(X509Certificate[] certs)
Return the Principal associated with the specified chain of X509 client certificates.
voidbackgroundProcess()
Execute a periodic task, such as reloading, etc.
voiddestroy()
protected Stringdigest(String credentials)
Digest the password using the specified algorithm and convert the result to a corresponding hexadecimal string.
static StringDigest(String credentials, String algorithm, 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.
StringgetAllRolesMode()
Return the all roles mode.
ContainergetContainer()
Return the Container with which this Realm has been associated.
ObjectNamegetController()
StringgetDigest()
Return the digest algorithm used for storing credentials.
protected StringgetDigest(String username, String realmName)
Return the digest associated with given principal's user name.
StringgetDigestEncoding()
Returns the digest encoding charset.
StringgetDomain()
StringgetInfo()
Return descriptive information about this Realm implementation and the corresponding version number, in the format <description>/<version>.
protected abstract StringgetName()
Return a short name for this Realm implementation, for use in log messages.
ObjectNamegetObjectName()
protected abstract StringgetPassword(String username)
Return the password associated with the given principal's user name.
protected PrincipalgetPrincipal(X509Certificate usercert)
Return the Principal associated with the given certificate.
protected abstract PrincipalgetPrincipal(String username)
Return the Principal associated with the given user name.
StringgetRealmPath()
protected StringgetRealmSuffix()
StringgetType()
booleangetValidate()
Return the "validate certificate chains" flag.
protected booleanhasMessageDigest()
booleanhasResourcePermission(Request request, Response response, SecurityConstraint[] constraints, Context context)
Perform access control based on the specified authorization constraint.
booleanhasRole(Principal principal, String role)
Return true if the specified Principal has the specified security role, within the context of this Realm; otherwise return false.
booleanhasUserDataPermission(Request request, Response response, SecurityConstraint[] constraints)
Enforce any user data constraint required by the security constraint guarding this request URI.
voidinit()
static voidmain(String[] args)
Digest password using the algorithm specified and convert the result to a corresponding hex string.
voidpostDeregister()
voidpostRegister(Boolean registrationDone)
voidpreDeregister()
ObjectNamepreRegister(MBeanServer server, ObjectName name)
voidremoveLifecycleListener(LifecycleListener listener)
Remove a lifecycle event listener from this component.
voidremovePropertyChangeListener(PropertyChangeListener listener)
Remove a property change listener from this component.
voidsetAllRolesMode(String allRolesMode)
Set the all roles mode.
voidsetContainer(Container container)
Set the Container with which this Realm has been associated.
voidsetController(ObjectName controller)
voidsetDigest(String digest)
Set the digest algorithm used for storing credentials.
voidsetDigestEncoding(String charset)
Sets the digest encoding charset.
voidsetRealmPath(String theRealmPath)
voidsetValidate(boolean validate)
Set the "validate certificate chains" flag.
voidstart()
Prepare for the beginning of active use of the public methods of this component.
voidstop()
Gracefully terminate the active use of the public methods of this component.

Field Detail

allRolesMode

protected RealmBase.AllRolesMode allRolesMode
The all role mode.

container

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

containerLog

protected Log containerLog
Container log

controller

protected ObjectName controller

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.

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

realmPath

protected String realmPath

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 Detail

addLifecycleListener

public void addLifecycleListener(LifecycleListener listener)
Add a lifecycle event listener to this component.

Parameters: listener The listener to add

addPropertyChangeListener

public void addPropertyChangeListener(PropertyChangeListener listener)
Add a property change listener to this component.

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.

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, byte[] credentials)
Return the Principal associated with the specified username and credentials, if there is one; otherwise return null.

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.

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.

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.

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.

Parameters: credentials Password or other credentials to use in authenticating this username

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

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.

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.

Parameters: request Request we are processing context Context the Request is mapped to

getAllRolesMode

public String getAllRolesMode()
Return the all roles mode.

getContainer

public Container getContainer()
Return the Container with which this Realm has been associated.

getController

public ObjectName getController()

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

getName

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

getObjectName

public ObjectName getObjectName()

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.

getRealmPath

public String getRealmPath()

getRealmSuffix

protected String getRealmSuffix()

getType

public String getType()

getValidate

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

hasMessageDigest

protected boolean hasMessageDigest()

hasResourcePermission

public boolean hasResourcePermission(Request request, Response response, SecurityConstraint[] constraints, Context context)
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.

Throws: IOException if an input/output error occurs

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.

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

Throws: IOException if an input/output error occurs

init

public void init()

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

postDeregister

public void postDeregister()

postRegister

public void postRegister(Boolean registrationDone)

preDeregister

public void preDeregister()

preRegister

public ObjectName preRegister(MBeanServer server, ObjectName name)

removeLifecycleListener

public void removeLifecycleListener(LifecycleListener listener)
Remove a lifecycle event listener from this component.

Parameters: listener The listener to remove

removePropertyChangeListener

public void removePropertyChangeListener(PropertyChangeListener listener)
Remove a property change listener from this component.

Parameters: listener The listener to remove

setAllRolesMode

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

setContainer

public void setContainer(Container container)
Set the Container with which this Realm has been associated.

Parameters: container The associated Container

setController

public void setController(ObjectName controller)

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 for platform default)

setRealmPath

public void setRealmPath(String theRealmPath)

setValidate

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

Parameters: validate The new validate certificate chains flag

start

public void start()
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.

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

stop

public void stop()
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.

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

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