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.

Author:
  Craig R. McClanahan

### Nested Class Summary

Nested Classes
`protected static class` `RealmBase.AllRolesMode`

### Field Summary

Fields
`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` Deprecated. Unused - will be removed in Tomcat 8.0.x
`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

Constructors
Constructor and Description
`RealmBase()`

### Method Summary

Methods
`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 boolean` `compareCredentials(String userCredentials, String serverCredentials)`
`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

    @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 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?

#### compareCredentials

    protected boolean compareCredentials(String userCredentials,
                             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 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()