Package org.apache.catalina.realm

Class RealmBase

  • All Implemented Interfaces:
    Lifecycle, Realm
    Direct Known Subclasses:
    JAASRealm, RealmAdapter
    public abstract class RealmBase
extends Object
implements Lifecycle, Realm
    Simple implementation of Realm that reads an XML file to configure the valid users, passwords, and roles. The file format (and default file location) are identical to those currently supported by Tomcat 3.X.
    Version:
    $Revision: 1.14 $ $Date: 2007/04/18 17:27:23 $
    Author:
    Craig R. McClanahan

    • Field Detail

      • log

        protected static final Logger log

      • debug

        protected int debug
        The debugging detail level for this component.

      • container

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

      • checkIfRequestIsSecure

        protected boolean checkIfRequestIsSecure
        Flag indicating whether a check to see if the request is secure is required before adding Pragma and Cache-Control headers when proxy caching has been disabled

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

      • lifecycle

        protected LifecycleSupport lifecycle
        The lifecycle event support for this component.

      • md

        protected volatile MessageDigest md
        The MessageDigest object for digesting user credentials (passwords).

      • md5Encoder

        protected static final MD5Encoder md5Encoder
        The MD5 helper object for this class.

      • md5Helper

        protected static volatile MessageDigest md5Helper
        MD5 message digest provider.

      • started

        protected boolean started
        Has this component been started?

      • validate

        protected boolean validate
        Should we validate client certificate chains when they are presented?

    • 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

      • getDebug

        public int getDebug()
        Return the debugging detail level for this component.

      • setDebug

        public void setDebug​(int debug)
        Set the debugging detail level for this component.
        Parameters:
        debug - The new debugging detail level

      • 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

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

      • 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

      • authenticate

        public Principal authenticate​(String username,
                              char[] 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,
                              char[] clientDigest,
                              String nOnce,
                              String nc,
                              String cnonce,
                              String qop,
                              String realm,
                              char[] 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[] certificates)
        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:
        certificates - 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.

      • findSecurityConstraints

        public SecurityConstraint[] findSecurityConstraints​(HttpRequest 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

      • findSecurityConstraints

        public SecurityConstraint[] findSecurityConstraints​(String uri,
                                                    String method,
                                                    Context context)
        Gets the security constraints configured by the given context for the given request URI and method.
        Specified by:
        findSecurityConstraints in interface Realm
        Parameters:
        uri - the request URI (minus the context Path)
        method - the request method
        context - the context
        Returns:
        the security constraints configured by the given context for the given request URI and method, or null

      • hasResourcePermission

        public boolean hasResourcePermission​(HttpRequest request,
                                     HttpResponse 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​(HttpRequest request,
                       HttpResponse response,
                       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. The default implementation is to forward to hasRole(Principal principal, String role).
        Specified by:
        hasRole in interface Realm
        Parameters:
        request - Request we are processing
        response - Response we are creating
        principal - Principal for whom the role is to be checked
        role - Security role to be checked

      • preAuthenticateCheck

        public int preAuthenticateCheck​(HttpRequest request,
                                HttpResponse response,
                                SecurityConstraint[] constraints,
                                boolean disableProxyCaching,
                                boolean securePagesWithPragma,
                                boolean ssoEnabled)
                         throws IOException
        Checks whether or not authentication is needed. Returns an int, one of AUTHENTICATE_NOT_NEEDED, AUTHENTICATE_NEEDED, or AUTHENTICATED_NOT_AUTHORIZED.
        Specified by:
        preAuthenticateCheck in interface Realm
        Parameters:
        request - Request we are processing
        response - Response we are creating
        constraints - Security constraint we are enforcing
        disableProxyCaching - whether or not to disable proxy caching for protected resources.
        securePagesWithPragma - true if we add headers which are incompatible with downloading office documents in IE under SSL but which fix a caching problem in Mozilla.
        ssoEnabled - true if sso is enabled
        Throws:
        IOException - if an input/output error occurs

      • invokeAuthenticateDelegate

        public boolean invokeAuthenticateDelegate​(HttpRequest request,
                                          HttpResponse response,
                                          Context context,
                                          Authenticator authenticator,
                                          boolean calledFromAuthenticate)
                                   throws IOException
        Authenticates the user making this request, based on the specified login configuration. Return true if any specified requirements have been satisfied, or false if we have created a response challenge already.
        Specified by:
        invokeAuthenticateDelegate in interface Realm
        Parameters:
        request - Request we are processing
        response - Response we are creating
        context - The Context to which client of this class is attached.
        authenticator - the current authenticator.
        calledFromAuthenticate - true if the call originates from HttpServletRequest.authenticate
        Throws:
        IOException - if an input/output error occurs

      • invokePostAuthenticateDelegate

        public boolean invokePostAuthenticateDelegate​(HttpRequest request,
                                              HttpResponse response,
                                              Context context)
                                       throws IOException
        Post authentication for given request and response.
        Specified by:
        invokePostAuthenticateDelegate in interface Realm
        Parameters:
        request - Request we are processing
        response - Response we are creating
        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.
        Specified by:
        hasRole in interface Realm
        Parameters:
        principal - Principal for whom the role is to be checked
        role - Security role to be checked

      • hasUserDataPermission

        public boolean hasUserDataPermission​(HttpRequest request,
                                     HttpResponse response,
                                     SecurityConstraint[] constraints)
                              throws IOException
        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

      • hasUserDataPermission

        public boolean hasUserDataPermission​(HttpRequest request,
                                     HttpResponse response,
                                     SecurityConstraint[] constraints,
                                     String uri,
                                     String method)
                              throws IOException
        Checks if the given request URI and method are the target of any user-data-constraint with a transport-guarantee of CONFIDENTIAL, and whether any such constraint is already satisfied. If uri and method are null, then the URI and method of the given request are checked. If a user-data-constraint exists that is not satisfied, then the given request will be redirected to HTTPS.
        Specified by:
        hasUserDataPermission in interface Realm
        Parameters:
        request - the request that may be redirected
        response - the response that may be redirected
        constraints - the security constraints to check against
        uri - the request URI (minus the context path) to check
        method - the request method to check
        Returns:
        true if the request URI and method are not the target of any unsatisfied user-data-constraint with a transport-guarantee of CONFIDENTIAL, and false if they are (in which case the given request will have been redirected to HTTPS)
        Throws:
        IOException

      • 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

      • addLifecycleListener

        public void addLifecycleListener​(LifecycleListener listener)
        Add a lifecycle event listener to this component.
        Specified by:
        addLifecycleListener in interface Lifecycle
        Parameters:
        listener - The listener to add

      • removeLifecycleListener

        public void removeLifecycleListener​(LifecycleListener listener)
        Remove a lifecycle event listener from this component.
        Specified by:
        removeLifecycleListener in interface Lifecycle
        Parameters:
        listener - The listener to remove

      • start

        public void start()
           throws LifecycleException
        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.
        Specified by:
        start in interface Lifecycle
        Throws:
        LifecycleException - if this component detects a fatal error that prevents this component from being used

      • stop

        public void stop()
          throws LifecycleException
        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.
        Specified by:
        stop in interface Lifecycle
        Throws:
        LifecycleException - if this component detects a fatal error that needs to be reported

      • destroy

        public void destroy()

      • logout

        public void logout​(HttpRequest hreq)
        Description copied from interface: Realm
        Logs out.
        Specified by:
        logout in interface Realm
        Parameters:
        hreq - the HttpRequest

      • isSecurityExtensionEnabled

        public boolean isSecurityExtensionEnabled​(jakarta.servlet.ServletContext servletContext)
        Description copied from interface: Realm
        Returns whether the specified ServletContext indicates that security extension is enabled.
        Specified by:
        isSecurityExtensionEnabled in interface Realm
        Parameters:
        servletContext - the ServletContext
        Returns:
        true if security extension is enabled; false otherwise

      • digest

        protected char[] digest​(char[] 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 char[] 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 char[] getPassword​(String username)
        Return the password associated with the given principal's user name.

      • getPrincipal

        protected abstract Principal getPrincipal​(String username)
        Return the Principal associated with the given user name.

      • log

        protected void log​(String message)
        Log a message on the Logger associated with our Container (if any)
        Parameters:
        message - Message to be logged

      • log

        protected void log​(String message,
                   Throwable t)
        Log a message on the Logger associated with our Container (if any)
        Parameters:
        message - Message to be logged
        t - Associated exception

      • disableProxyCaching

        protected void disableProxyCaching​(HttpRequest request,
                                   HttpResponse response,
                                   boolean disableProxyCaching,
                                   boolean securePagesWithPragma)

      • getController

        public ObjectName getController()

      • setController

        public void setController​(ObjectName controller)

      • getAlternatePrincipal

        public Principal getAlternatePrincipal​(HttpRequest req)
        Return an alternate principal from the request if available. Tomcat realms do not implement this so always return null as default.
        Specified by:
        getAlternatePrincipal in interface Realm
        Parameters:
        req - The request object.
        Returns:
        Alternate principal or null.

      • getAlternateAuthType

        public String getAlternateAuthType​(HttpRequest req)
        Return an alternate auth type from the request if available. Tomcat realms do not implement this so always return null as default.
        Specified by:
        getAlternateAuthType in interface Realm
        Parameters:
        req - The request object.
        Returns:
        Alternate auth type or null.

      • setRealmName

        public void setRealmName​(String name,
                         String authMethod)
        Set the name of the associated realm.
        Specified by:
        setRealmName in interface Realm
        Parameters:
        name - the name of the realm.

      • getRealmName

        public String getRealmName()
        Returns the name of the associated realm.
        Specified by:
        getRealmName in interface Realm
        Returns:
        realm name or null if not set.

      • authenticate

        public Principal authenticate​(jakarta.servlet.http.HttpServletRequest hreq)
        Description copied from interface: Realm
        Does digest authentication and returns the Principal associated with the username in the HTTP header.
        Specified by:
        authenticate in interface Realm
        Parameters:
        hreq - HTTP servlet request.