RealmBase (Apache Tomcat 7.0.67 API Documentation)

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

All Implemented Interfaces:

javax.management.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.

Author:

Craig R. McClanahan

Nested Class Summary

Nested Classes
Modifier and Type Class and Description

protected static class RealmBase.AllRolesMode

Nested Classes
Modifier and Type	Class and Description
`protected static class`	`RealmBase.AllRolesMode`

Field Summary

Fields
Modifier and Type	Field and Description
`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 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 static java.lang.String`	`info` Descriptive information about this Realm implementation.
`protected java.security.MessageDigest`	`md` The MessageDigest object for digesting user credentials (passwords).
`protected static MD5Encoder`	`md5Encoder` Deprecated. Unused - will be removed in Tomcat 8.0.x
`protected static java.security.MessageDigest`	`md5Helper` MD5 message digest provider.
`protected java.lang.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 java.beans.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 java.lang.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

Constructors
Constructor and Description

RealmBase()

Constructors
Constructor and Description
`RealmBase()`

Method Summary

Methods
Modifier and Type	Method and Description
`void`	`addPropertyChangeListener(java.beans.PropertyChangeListener listener)` Add a property change listener to this component.
`java.security.Principal`	`authenticate(org.ietf.jgss.GSSContext gssContext, boolean storeCred)` Return the Principal associated with the specified `GSSContext`.
`java.security.Principal`	`authenticate(java.lang.String username)` Return the Principal associated with the specified username, 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.
`protected boolean`	`compareCredentials(java.lang.String userCredentials, java.lang.String serverCredentials)`
`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.
`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.
`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.
`protected java.nio.charset.Charset`	`getDigestCharset()`
`java.lang.String`	`getDigestEncoding()` Returns the digest encoding charset.
`java.lang.String`	`getDomainInternal()` Method implemented by sub-classes to identify the domain in which MBeans should be registered.
`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.
`java.lang.String`	`getObjectNameKeyProperties()` Allow sub-classes to specify the key properties component of the `ObjectName` that will be used to register this component.
`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.lang.String username, org.ietf.jgss.GSSCredential gssCredential)`
`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()`
`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.
`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(Wrapper wrapper, 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.
`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(java.lang.String[] args)` Digest password using the algorithm specified and convert the result to a corresponding hex string.
`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`	`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`	`setStripRealmForGss(boolean stripRealmForGss)`
`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.
`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()`.
`java.lang.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 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
  - md
```
protected volatile java.security.MessageDigest md
```
    The MessageDigest object for digesting user credentials (passwords).
  - md5Encoder
```
@Deprecated
protected static final MD5Encoder md5Encoder
```
    Deprecated. Unused - will be removed in Tomcat 8.0.x
    
    The MD5 helper object for this class.
  - md5Helper
```
protected static volatile java.security.MessageDigest md5Helper
```
    MD5 message digest provider.
  - sm
```
protected static final StringManager sm
```
    The string manager for this package.
  - 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.
  - 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 java.lang.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 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)
  - getDigestCharset
```
protected java.nio.charset.Charset getDigestCharset()
                                             throws java.io.UnsupportedEncodingException
```
    Throws:
    
    java.io.UnsupportedEncodingException
  - 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 (@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(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)
```
    Return the Principal associated with the specified username, if there is one; otherwise return null.
    
    Specified by:
    
    authenticate in interface Realm
    
    Parameters:
    username - Username of the Principal to look up
  - 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,
                                   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.
  - authenticate
```
public java.security.Principal authenticate(org.ietf.jgss.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?
  - compareCredentials
```
protected boolean compareCredentials(java.lang.String userCredentials,
                         java.lang.String serverCredentials)
```
  - 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(Wrapper wrapper,
              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
    wrapper - wrapper context for evaluating role
  - 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
  - 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 java.lang.String toString()
```
    Return a String representation of this component.
    
    Overrides:
    
    toString in class java.lang.Object
  - 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.
  - getPrincipal
```
protected java.security.Principal getPrincipal(java.lang.String username,
                                   org.ietf.jgss.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 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
  - getObjectNameKeyProperties
```
public java.lang.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 java.lang.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 java.lang.String getRealmPath()
```
  - setRealmPath
```
public void setRealmPath(java.lang.String theRealmPath)
```
  - getRealmSuffix
```
protected java.lang.String getRealmSuffix()
```

Class RealmBase

Nested Class Summary

Field Summary

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

Fields inherited from interface org.apache.catalina.Lifecycle

Constructor Summary

Method Summary

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

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

Methods inherited from class java.lang.Object

Field Detail

container

containerLog

digest

digestEncoding

info

md

md5Encoder

md5Helper

sm

support

validate

x509UsernameRetrieverClassName

x509UsernameRetriever

allRolesMode

stripRealmForGss

realmPath

Constructor Detail

RealmBase

Method Detail

getContainer

setContainer

getAllRolesMode

setAllRolesMode

getDigest

setDigest

getDigestEncoding

setDigestEncoding

getDigestCharset

getInfo

getValidate

setValidate

getX509UsernameRetrieverClassName

setX509UsernameRetrieverClassName

isStripRealmForGss

setStripRealmForGss

addPropertyChangeListener

authenticate

authenticate

authenticate

authenticate

authenticate

compareCredentials

backgroundProcess

findSecurityConstraints

hasResourcePermission

hasRole

hasUserDataPermission

removePropertyChangeListener

initInternal

startInternal

stopInternal

toString

digest

hasMessageDigest

getDigest

getName

getPassword

getPrincipal

getPrincipal

getPrincipal

getServer

Digest

main

getObjectNameKeyProperties

getDomainInternal

getRealmPath

setRealmPath

getRealmSuffix