RealmBase (Apache Tomcat 10.1.48 API Documentation)
Description: declaration: package: org.apache.catalina.realm, class: RealmBase

# Class RealmBase

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

All Implemented Interfaces:
  `MBeanRegistration, Contained, JmxEnabled, Lifecycle, Realm`

Direct Known Subclasses:
  `AuthenticatedUserRealm, CombinedRealm, DataSourceRealm, JAASRealm, 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.

- ## Nested Class Summary

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

  ### Nested classes/interfaces inherited from interface Lifecycle

  `Lifecycle.SingleUse`

- ## Field Summary

  Fields
  Modifier and Type
  Field
  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 String`
  `realmPath`
  `protected static final StringManager`
  `sm`
  The string manager for this package.
  `protected boolean`
  `stripRealmForGss`
  When processing users authenticated via the GSS-API, should any "@..." be stripped from the end of the username?
  `protected final PropertyChangeSupport`
  `support`
  The property change support for this component.
  `protected static final String`
  `USER_ATTRIBUTES_DELIMITER`
  The character used for delimiting user attribute names.
  `protected static final String`
  `USER_ATTRIBUTES_WILDCARD`
  The character used as wildcard in user attribute lists.
  `protected String`
  `userAttributes`
  The comma separated names of user attributes to additionally query from the realm.
  `protected List<String>`
  `userAttributesList`
  The list of user attributes to additionally query from the realm.
  `protected boolean`
  `validate`
  Should we validate client certificate chains when they are presented?
  `protected X509UsernameRetriever`
  `x509UsernameRetriever`
  The object that will extract usernames from X509 client certificates.
  `protected String`
  `x509UsernameRetrieverClassName`
  The name of the class to use for retrieving usernames from X509 certificates.

  ### Fields inherited from interface 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
  Description
  `RealmBase()`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `addPropertyChangeListener(PropertyChangeListener listener)`
  Add a property change listener to this component.
  `Principal`
  `authenticate(String username)`
  Try to authenticate with the specified username.
  `Principal`
  `authenticate(String username, String credentials)`
  Try to authenticate using the specified username and credentials.
  `Principal`
  `authenticate(String username, String clientDigest, String nonce, String nc, String cnonce, String qop, String realm, String digestA2)`
  Deprecated.
  `Principal`
  `authenticate(String username, String clientDigest, String nonce, String nc, String cnonce, String qop, String realm, String digestA2, String algorithm)`
  Try to authenticate with the specified username, which matches the digest calculated using the given parameters using the method described in RFC 7616.
  `Principal`
  `authenticate(X509Certificate[] certs)`
  Try to authenticate using a chain of `X509Certificate`s.
  `Principal`
  `authenticate(GSSContext gssContext, boolean storeCred)`
  Try to authenticate using a `GSSContext`.
  `Principal`
  `authenticate(GSSName gssName, GSSCredential gssCredential)`
  Try to authenticate using a `GSSName`.
  `void`
  `backgroundProcess()`
  Execute a periodic task, such as reloading, etc.
  `SecurityConstraint[]`
  `findSecurityConstraints(Request request, Context context)`
  Find the SecurityConstraints configured to guard the request URI for this request.
  `String`
  `getAllRolesMode()`
  Return the all roles mode.
  `Container`
  `getContainer()`
  Get the `Container` with which this instance is associated.
  `CredentialHandler`
  `getCredentialHandler()`
  `protected String`
  `getDigest(String username, String realmName)`
  Deprecated.
  Unused.
  `protected String`
  `getDigest(String username, String realmName, String algorithm)`
  Return the digest associated with given principal's user name.
  `String`
  `getDomainInternal()`
  Method implemented by subclasses to identify the domain in which MBeans should be registered.
  `String`
  `getObjectNameKeyProperties()`
  Allow subclasses to specify the key properties component of the `ObjectName` that will be used to register this component.
  `protected abstract String`
  `getPassword(String username)`
  Get the password for the specified user.
  `protected abstract Principal`
  `getPrincipal(String username)`
  Get the principal associated with the specified user.
  `protected Principal`
  `getPrincipal(X509Certificate usercert)`
  Get the principal associated with the specified certificate.
  `protected Principal`
  `getPrincipal(GSSName gssName, GSSCredential gssCredential)`
  Get the principal associated with the specified `GSSName`.
  `protected Principal`
  `getPrincipal(GSSName gssName, GSSCredential gssCredential, GSSContext gssContext)`
  Get the principal associated with the specified `GSSName`.
  `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.
  `int`
  `getTransportGuaranteeRedirectStatus()`
  `String`
  `getUserAttributes()`
  `boolean`
  `getValidate()`
  Return the "validate certificate chains" flag.
  `String`
  `getX509UsernameRetrieverClassName()`
  Gets the name of the class that will be used to extract usernames from X509 client certificates.
  `protected boolean`
  `hasMessageDigest(String algorithm)`
  `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)`
  Check if the specified Principal has the specified security role, within the context of this Realm.
  `protected boolean`
  `hasRoleInternal(Principal principal, String role)`
  Check if the specified Principal has the specified security role, within the context of this Realm.
  `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()`
  Subclasses implement this method to perform any instance initialisation required.
  `boolean`
  `isStripRealmForGss()`
  `static void`
  `main(String[] args)`
  Generate a stored credential string for the given password and associated parameters.
  `protected List<String>`
  `parseUserAttributes(String userAttributes)`
  Parse the specified delimiter separated attribute names and return a list of that names or `null`, if no attributes have been specified.
  `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 instance is associated.
  `void`
  `setCredentialHandler(CredentialHandler credentialHandler)`
  Set the CredentialHandler to be used by this Realm.
  `void`
  `setRealmPath(String theRealmPath)`
  `void`
  `setStripRealmForGss(boolean stripRealmForGss)`
  `void`
  `setTransportGuaranteeRedirectStatus(int transportGuaranteeRedirectStatus)`
  Set the HTTP status code used when the container needs to issue an HTTP redirect to meet the requirements of a configured transport guarantee.
  `void`
  `setUserAttributes(String userAttributes)`
  Set the comma separated names of user attributes to additionally query from the realm.
  `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 usernames 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()`

  ### Methods inherited from class LifecycleMBeanBase

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

  ### Methods inherited from class LifecycleBase

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

  ### Methods inherited from class Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

  ### Methods inherited from interface Realm

  `isAvailable`

- ## Field Details

  - ### USER_ATTRIBUTES_DELIMITER

    protected static final String USER_ATTRIBUTES_DELIMITER
    The character used for delimiting user attribute names.

    Applies to some of the Realm implementations only.

    See Also:
      - Constant Field Values

  - ### USER_ATTRIBUTES_WILDCARD

    protected static final String USER_ATTRIBUTES_WILDCARD
    The character used as wildcard in user attribute lists. Using it means query all available user attributes.

    Applies to some of the Realm implementations only.

    See Also:
      - Constant Field Values

  - ### container

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

  - ### containerLog

    protected Log containerLog
    Container log

  - ### sm

    protected static final StringManager sm
    The string manager for this package.

  - ### support

    protected final 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 usernames from X509 certificates.

  - ### x509UsernameRetriever

    protected X509UsernameRetriever x509UsernameRetriever
    The object that will extract usernames 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 username?

  - ### userAttributes

    protected String userAttributes
    The comma separated names of user attributes to additionally query from the realm. These will be provided to the user through the created Principal's attributes map. Support for this feature is optional.

  - ### userAttributesList

    protected List<String> userAttributesList
    The list of user attributes to additionally query from the realm. These will be provided to the user through the created Principal's attributes map. Support for this feature is optional.

  - ### realmPath

    protected String realmPath

- ## Constructor Details

  - ### RealmBase

    public RealmBase()

- ## Method Details

  - ### getTransportGuaranteeRedirectStatus

    public int getTransportGuaranteeRedirectStatus()
    Returns:
      The HTTP status code used when the container needs to issue an HTTP redirect to meet the requirements of a configured transport guarantee.

  - ### setTransportGuaranteeRedirectStatus

    public void setTransportGuaranteeRedirectStatus(int transportGuaranteeRedirectStatus)
    Set the HTTP status code used when the container needs to issue an HTTP redirect to meet the requirements of a configured transport guarantee.
    Parameters:
      `transportGuaranteeRedirectStatus` - The status to use. This value is not validated

  - ### getCredentialHandler

    public CredentialHandler getCredentialHandler()
    Specified by:
      `getCredentialHandler` in interface `Realm`
    Returns:
      the CredentialHandler configured for this Realm.

  - ### setCredentialHandler

    public void setCredentialHandler(CredentialHandler credentialHandler)
    Description copied from interface: `Realm`
    Set the CredentialHandler to be used by this Realm.
    Specified by:
      `setCredentialHandler` in interface `Realm`
    Parameters:
      `credentialHandler` - the `CredentialHandler` to use

  - ### getContainer

    public Container getContainer()
    Description copied from interface: `Contained`
    Get the `Container` with which this instance is associated.
    Specified by:
      `getContainer` in interface `Contained`
    Returns:
      The Container with which this instance is associated or `null` if not associated with a Container

  - ### setContainer

    public void setContainer(Container container)
    Description copied from interface: `Contained`
    Set the `Container` with which this instance is associated.
    Specified by:
      `setContainer` in interface `Contained`
    Parameters:
      `container` - The Container instance with which this instance is to be associated, or `null` to disassociate this instance from any Container

  - ### getAllRolesMode

    public String getAllRolesMode()
    Return the all roles mode.
    Returns:
      A string representation of the current all roles mode

  - ### setAllRolesMode

    public void setAllRolesMode(String allRolesMode)
    Set the all roles mode.
    Parameters:
      `allRolesMode` - A string representation of the new all roles mode

  - ### getValidate

    public boolean getValidate()
    Return the "validate certificate chains" flag.
    Returns:
      The value of 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 usernames from X509 client certificates.
    Returns:
      The name of the class that will be used to extract usernames from X509 client certificates.

  - ### setX509UsernameRetrieverClassName

    public void setX509UsernameRetrieverClassName(String className)
    Sets the name of the class that will be used to extract usernames from X509 client certificates. The class must implement X509UsernameRetriever.
    Parameters:
      `className` - The name of the class that will be used to extract usernames from X509 client certificates.
    See Also:
      - `X509UsernameRetriever`

  - ### isStripRealmForGss

    public boolean isStripRealmForGss()

  - ### setStripRealmForGss

    public void setStripRealmForGss(boolean stripRealmForGss)

  - ### getUserAttributes

    public String getUserAttributes()
    Returns:
      the comma separated names of user attributes to additionally query from realm

  - ### setUserAttributes

    public void setUserAttributes(String userAttributes)
    Set the comma separated names of user attributes to additionally query from the realm. These will be provided to the user through the created Principal's attributes map. In this map, each field value is bound to the field's name, that is, the name of the field serves as the key of the mapping.

    If set to the wildcard character, or, if the wildcard character is part of the comma separated list, all available attributes - except the password attribute (as specified by `userCredCol`) - are queried. The wildcard character is defined by constant `USER_ATTRIBUTES_WILDCARD`. It defaults to the asterisk (*) character.

    Parameters:
      `userAttributes` - the comma separated names of user attributes

  - ### addPropertyChangeListener

    public void addPropertyChangeListener(PropertyChangeListener listener)
    Description copied from interface: `Realm`
    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)
    Description copied from interface: `Realm`
    Try to authenticate with the specified username.
    Specified by:
      `authenticate` in interface `Realm`
    Parameters:
      `username` - Username of the Principal to look up
    Returns:
      the associated principal, or `null` if none is associated.

  - ### authenticate

    public Principal authenticate(String username, String credentials)
    Description copied from interface: `Realm`
    Try to authenticate using the specified username and credentials.
    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
    Returns:
      the associated principal, or `null` if there is none

  - ### authenticate

    @Deprecated public Principal authenticate(String username, String clientDigest, String nonce, String nc, String cnonce, String qop, String realm, String digestA2)
    Deprecated.
    Description copied from interface: `Realm`
    Try to authenticate with the specified username, which matches the digest calculated using the given parameters using the method described in RFC 2617 (which is a superset of RFC 2069).
    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
      `nc` - the nonce counter
      `cnonce` - the client chosen nonce
      `qop` - the "quality of protection" (`nc` and `cnonce` will only be used, if `qop` is not `null`).
      `realm` - Realm name
      `digestA2` - Second digest calculated as digest(Method + ":" + uri)
    Returns:
      the associated principal, or `null` if there is none.

  - ### authenticate

    public Principal authenticate(String username, String clientDigest, String nonce, String nc, String cnonce, String qop, String realm, String digestA2, String algorithm)
    Description copied from interface: `Realm`
    Try to authenticate with the specified username, which matches the digest calculated using the given parameters using the method described in RFC 7616.

    The default implementation calls `Realm.authenticate(String, String, String, String, String, String, String, String)` for backwards compatibility which effectively forces the use of MD5 regardless of the algorithm specified in the call to this method.

    Implementations are expected to override the default implementation and take account of the algorithm parameter.

    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
      `nc` - the nonce counter
      `cnonce` - the client chosen nonce
      `qop` - the "quality of protection" (`nc` and `cnonce` will only be used, if `qop` is not `null`).
      `realm` - Realm name
      `digestA2` - Second digest calculated as digest(Method + ":" + uri)
      `algorithm` - The message digest algorithm to use
    Returns:
      the associated principal, or `null` if there is none.

  - ### authenticate

    public Principal authenticate(X509Certificate[] certs)
    Description copied from interface: `Realm`
    Try to authenticate using a chain of `X509Certificate`s.
    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.
    Returns:
      the associated principal, or `null` if there is none

  - ### authenticate

    public Principal authenticate(GSSContext gssContext, boolean storeCred)
    Description copied from interface: `Realm`
    Try to authenticate using a `GSSContext`.
    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?
    Returns:
      the associated principal, or `null` if there is none

  - ### authenticate

    public Principal authenticate(GSSName gssName, GSSCredential gssCredential)
    Description copied from interface: `Realm`
    Try to authenticate using a `GSSName`.
    Specified by:
      `authenticate` in interface `Realm`
    Parameters:
      `gssName` - The `GSSName` of the principal to look up
      `gssCredential` - The `GSSCredential` of the principal, may be `null`
    Returns:
      the associated principal, or `null` if there is none

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

    The default implementation is NO-OP.

    Specified by:
      `backgroundProcess` in interface `Realm`

  - ### findSecurityConstraints

    public SecurityConstraint[] findSecurityConstraints(Request request, Context context)
    Description copied from interface: `Realm`
    Find the SecurityConstraints configured to guard the request URI for this request.
    Specified by:
      `findSecurityConstraints` in interface `Realm`
    Parameters:
      `request` - Request we are processing
      `context` - Context the Request is mapped to
    Returns:
      the configured `SecurityConstraint`, or `null` if there is none

  - ### hasResourcePermission

    public boolean hasResourcePermission(Request request, Response response, SecurityConstraint[] constraints, Context context) throws IOException
    Description copied from interface: `Realm`
    Perform access control based on the specified authorization constraint.
    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.
    Returns:
      `true` if this constraint is satisfied and processing should continue, or `false` otherwise
    Throws:
      `IOException` - if an input/output error occurs

  - ### hasRole

    public boolean hasRole(Wrapper wrapper, Principal principal, String role)
    Check if the specified Principal has the specified security role, within the context of this Realm.

    This method or `hasRoleInternal(Principal, String)` 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:
      `wrapper` - wrapper context for evaluating role
      `principal` - Principal for whom the role is to be checked
      `role` - Security role to be checked
    Returns:
      `true` if the specified Principal has the specified security role, within the context of this Realm; otherwise return `false`.

  - ### parseUserAttributes

    protected List<String> parseUserAttributes(String userAttributes)
    Parse the specified delimiter separated attribute names and return a list of that names or `null`, if no attributes have been specified.

    If a wildcard character is found, return a list consisting of a single wildcard character only.

    Parameters:
      `userAttributes` - comma separated names of attributes to parse
    Returns:
      a list containing the parsed attribute names or `null`, if no attributes have been specified

  - ### hasRoleInternal

    protected boolean hasRoleInternal(Principal principal, String role)
    Check if the specified Principal has the specified security role, within the context of this Realm. This method or `hasRoleInternal(Principal, String)` 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
    Returns:
      `true` if the specified Principal has the specified security role, within the context of this Realm; otherwise return `false`.

  - ### hasUserDataPermission

    public boolean hasUserDataPermission(Request request, Response response, SecurityConstraint[] constraints) throws IOException
    Description copied from interface: `Realm`
    Enforce any user data constraint required by the security constraint guarding this request URI.
    Specified by:
      `hasUserDataPermission` in interface `Realm`
    Parameters:
      `request` - Request we are processing
      `response` - Response we are creating
      `constraints` - Security constraint being checked
    Returns:
      `true` if this constraint was not violated and processing should continue, or `false` if we have created a response already.
    Throws:
      `IOException` - if an input/output error occurs

  - ### removePropertyChangeListener

    public void removePropertyChangeListener(PropertyChangeListener listener)
    Description copied from interface: `Realm`
    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: `LifecycleBase`
    Subclasses implement this method to perform any instance initialisation required.
    Overrides:
      `initInternal` in class `LifecycleMBeanBase`
    Throws:
      `LifecycleException` - If the initialisation fails

  - ### 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()
    Overrides:
      `toString` in class `Object`

  - ### hasMessageDigest

    protected boolean hasMessageDigest(String algorithm)

  - ### getDigest

    @Deprecated protected String getDigest(String username, String realmName)
    Deprecated.
    Unused. Use `getDigest(String, String, String)`. Will be removed in Tomcat 11.
    Return the digest associated with given principal's username.
    Parameters:
      `username` - The username
      `realmName` - The realm name
    Returns:
      the digest for the specified user

  - ### getDigest

    protected String getDigest(String username, String realmName, String algorithm)
    Return the digest associated with given principal's user name.
    Parameters:
      `username` - The user name
      `realmName` - The realm name
      `algorithm` - The name of the message digest algorithm to use
    Returns:
      the digest for the specified user

  - ### getPassword

    protected abstract String getPassword(String username)
    Get the password for the specified user.
    Parameters:
      `username` - The username
    Returns:
      the password associated with the given principal's username.

  - ### getPrincipal

    protected Principal getPrincipal(X509Certificate usercert)
    Get the principal associated with the specified certificate.
    Parameters:
      `usercert` - The user certificate
    Returns:
      the Principal associated with the given certificate.

  - ### getPrincipal

    protected abstract Principal getPrincipal(String username)
    Get the principal associated with the specified user.
    Parameters:
      `username` - The username
    Returns:
      the Principal associated with the given username.

  - ### getPrincipal

    protected Principal getPrincipal(GSSName gssName, GSSCredential gssCredential, GSSContext gssContext)
    Get the principal associated with the specified `GSSName`.
    Parameters:
      `gssName` - The GSS name
      `gssCredential` - the GSS credential of the principal
      `gssContext` - the established GSS context
    Returns:
      the principal associated with the given username.

  - ### getPrincipal

    protected Principal getPrincipal(GSSName gssName, GSSCredential gssCredential)
    Get the principal associated with the specified `GSSName`.
    Parameters:
      `gssName` - The GSS name
      `gssCredential` - the GSS credential of the principal
    Returns:
      the principal associated with the given username.

  - ### 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 (e.g. because the container hierarchy is not complete), `null` is returned.
    Returns:
      the Server associated with the realm

  - ### main

    public static void main(String[] args) throws IOException
    Generate a stored credential string for the given password and associated parameters.

    The following parameters are supported:

    - -a - The algorithm to use to generate the stored credential. If not specified a default of SHA-512 will be used.
    - -e - The encoding to use for any byte to/from character conversion that may be necessary. If not specified, the system encoding (`Charset.defaultCharset()`) will be used.
    - -i - The number of iterations to use when generating the stored credential. If not specified, the default for the CredentialHandler will be used.
    - -s - The length (in bytes) of salt to generate and store as part of the credential. If not specified, the default for the CredentialHandler will be used.
    - -k - The length (in bits) of the key(s), if any, created while generating the credential. If not specified, the default for the CredentialHandler will be used.
    - -h - The fully qualified class name of the CredentialHandler to use. If not specified, the built-in handlers will be tested in turn and the first one to accept the specified algorithm will be used.
    - -f - The name of the file that contains passwords to encode. Each line in the file should contain only one password. Using this option ignores other password input.

    This generation process currently supports the following CredentialHandlers, the correct one being selected based on the algorithm specified:

    - `MessageDigestCredentialHandler`
    - `SecretKeyCredentialHandler`
    Parameters:
      `args` - The parameters passed on the command line
    Throws:
      `IOException` - If an error occurs reading the password file

  - ### getObjectNameKeyProperties

    public String getObjectNameKeyProperties()
    Description copied from class: `LifecycleMBeanBase`
    Allow subclasses 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 subclasses 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()