DigestAuthenticator (Apache Tomcat 9.0.102 API Documentation)
Description: declaration: package: org.apache.catalina.authenticator, class: DigestAuthenticator

Package org.apache.catalina.authenticator

# Class DigestAuthenticator

java.lang.Object
org.apache.catalina.util.LifecycleBase
org.apache.catalina.util.LifecycleMBeanBase
org.apache.catalina.valves.ValveBase
org.apache.catalina.authenticator.AuthenticatorBase
org.apache.catalina.authenticator.DigestAuthenticator

All Implemented Interfaces:
  `MBeanRegistration`, `RegistrationListener`, `Authenticator`, `Contained`, `JmxEnabled`, `Lifecycle`, `Valve`

public class DigestAuthenticator extends AuthenticatorBase
An Authenticator and Valve implementation of HTTP DIGEST Authentication, as outlined in RFC 7616: "HTTP Digest Authentication"

Author:
  Craig R. McClanahan, Remy Maucherat

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static enum`
  `DigestAuthenticator.AuthDigest`
  This enum exists because RFC 7616 and Java use different names for some digests.
  `static class`
  `DigestAuthenticator.DigestInfo`
  `static class`
  `DigestAuthenticator.NonceInfo`

  ## Nested classes/interfaces inherited from class org.apache.catalina.authenticator.AuthenticatorBase

  `AuthenticatorBase.AllowCorsPreflight`

  ## Nested classes/interfaces inherited from interface org.apache.catalina.Lifecycle

  `Lifecycle.SingleUse`

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `protected String`
  `key`
  Private key.
  `protected long`
  `lastTimestamp`
  The last timestamp used to generate a nonce.
  `protected final Object`
  `lastTimestampLock`
  `protected int`
  `nonceCacheSize`
  Maximum number of server nonces to keep in the cache.
  `protected int`
  `nonceCountWindowSize`
  The window size to use to track seen nonce count values for a given nonce.
  `protected Map<String,DigestAuthenticator.NonceInfo>`
  `nonces`
  List of server nonce values currently being tracked
  `protected long`
  `nonceValidity`
  How long server nonces are valid for in milliseconds.
  `protected String`
  `opaque`
  Opaque string.
  `protected static final String`
  `QOP`
  Tomcat's DIGEST implementation only supports auth quality of protection.
  `protected boolean`
  `validateUri`
  Should the URI be validated as required by RFC2617?

  ### Fields inherited from class org.apache.catalina.authenticator.AuthenticatorBase

  `alwaysUseSession, AUTH_HEADER_NAME, cache, changeSessionIdOnAuthentication, context, disableProxyCaching, jaspicCallbackHandlerClass, REALM_NAME, securePagesWithPragma, secureRandomAlgorithm, secureRandomClass, secureRandomProvider, sendAuthInfoResponseHeaders, sessionIdGenerator, sm, sso`

  ### Fields inherited from class org.apache.catalina.valves.ValveBase

  `asyncSupported, container, containerLog, next`

  ### 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
  Description
  `DigestAuthenticator()`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `protected boolean`
  `doAuthenticate(Request request, HttpServletResponse response)`
  Authenticate the user making this request, based on the specified login configuration.
  `protected String`
  `generateNonce(Request request)`
  Generate a unique token.
  `String`
  `getAlgorithms()`
  `protected String`
  `getAuthMethod()`
  Return the authentication method, which is vendor-specific and not defined by HttpServletRequest.
  `String`
  `getKey()`
  `int`
  `getNonceCacheSize()`
  `int`
  `getNonceCountWindowSize()`
  `long`
  `getNonceValidity()`
  `String`
  `getOpaque()`
  `protected boolean`
  `isPreemptiveAuthPossible(Request request)`
  Can the authenticator perform preemptive authentication for the given request?
  `boolean`
  `isValidateUri()`
  `protected static String`
  `removeQuotes(String quotedString)`
  Deprecated.
  This will be removed in Tomcat 11 onwards.
  `protected static String`
  `removeQuotes(String quotedString, boolean quotesRequired)`
  Deprecated.
  This will be removed in Tomcat 11 onwards.
  `void`
  `setAlgorithms(String algorithmsString)`
  `protected void`
  `setAuthenticateHeader(HttpServletRequest request, HttpServletResponse response, String nonce, boolean isNonceStale)`
  Generates the WWW-Authenticate header(s) as per RFC 7616.
  `void`
  `setKey(String key)`
  `void`
  `setNonceCacheSize(int nonceCacheSize)`
  `void`
  `setNonceCountWindowSize(int nonceCountWindowSize)`
  `void`
  `setNonceValidity(long nonceValidity)`
  `void`
  `setOpaque(String opaque)`
  `void`
  `setValidateUri(boolean validateUri)`
  `protected void`
  `startInternal()`
  Start this component and implement the requirements of `LifecycleBase.startInternal()`.

  ### Methods inherited from class org.apache.catalina.authenticator.AuthenticatorBase

  `allowCorsPreflightBypass, associate, authenticate, changeSessionID, checkForCachedAuthentication, doLogin, getAllowCorsPreflight, getAlwaysUseSession, getCache, getChangeSessionIdOnAuthentication, getContainer, getDisableProxyCaching, getJaspicCallbackHandlerClass, getRealmName, getSecurePagesWithPragma, getSecureRandomAlgorithm, getSecureRandomClass, getSecureRandomProvider, invoke, isContinuationRequired, isSendAuthInfoResponseHeaders, login, logout, notify, reauthenticateFromSSO, register, register, setAllowCorsPreflight, setAlwaysUseSession, setCache, setChangeSessionIdOnAuthentication, setContainer, setDisableProxyCaching, setJaspicCallbackHandlerClass, setSecurePagesWithPragma, setSecureRandomAlgorithm, setSecureRandomClass, setSecureRandomProvider, setSendAuthInfoResponseHeaders, stopInternal`

  ### Methods inherited from class org.apache.catalina.valves.ValveBase

  `backgroundProcess, getDomainInternal, getNext, getObjectNameKeyProperties, initInternal, isAsyncSupported, setAsyncSupported, setNext, toString`

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

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

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

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

  ### Methods inherited from class java.lang.Object

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

- ## Field Details

  - ### QOP

    protected static final String QOP
    Tomcat's DIGEST implementation only supports auth quality of protection.
    See Also:
      - Constant Field Values

  - ### nonces

    protected Map<String,DigestAuthenticator.NonceInfo> nonces
    List of server nonce values currently being tracked

  - ### lastTimestamp

    protected long lastTimestamp
    The last timestamp used to generate a nonce. Each nonce should get a unique timestamp.

  - ### lastTimestampLock

    protected final Object lastTimestampLock

  - ### nonceCacheSize

    protected int nonceCacheSize
    Maximum number of server nonces to keep in the cache. If not specified, the default value of 1000 is used.

  - ### nonceCountWindowSize

    protected int nonceCountWindowSize
    The window size to use to track seen nonce count values for a given nonce. If not specified, the default of 100 is used.

  - ### key

    protected String key
    Private key.

  - ### nonceValidity

    protected long nonceValidity
    How long server nonces are valid for in milliseconds. Defaults to 5 minutes.

  - ### opaque

    protected String opaque
    Opaque string.

  - ### validateUri

    protected boolean validateUri
    Should the URI be validated as required by RFC2617? Can be disabled in reverse proxies where the proxy has modified the URI.

- ## Constructor Details

  - ### DigestAuthenticator

    public DigestAuthenticator()

- ## Method Details

  - ### getNonceCountWindowSize

    public int getNonceCountWindowSize()

  - ### setNonceCountWindowSize

    public void setNonceCountWindowSize(int nonceCountWindowSize)

  - ### getNonceCacheSize

    public int getNonceCacheSize()

  - ### setNonceCacheSize

    public void setNonceCacheSize(int nonceCacheSize)

  - ### getKey

    public String getKey()

  - ### setKey

    public void setKey(String key)

  - ### getNonceValidity

    public long getNonceValidity()

  - ### setNonceValidity

    public void setNonceValidity(long nonceValidity)

  - ### getOpaque

    public String getOpaque()

  - ### setOpaque

    public void setOpaque(String opaque)

  - ### isValidateUri

    public boolean isValidateUri()

  - ### setValidateUri

    public void setValidateUri(boolean validateUri)

  - ### getAlgorithms

    public String getAlgorithms()

  - ### setAlgorithms

    public void setAlgorithms(String algorithmsString)

  - ### doAuthenticate

    protected boolean doAuthenticate(Request request, HttpServletResponse response) throws IOException
    Authenticate the user making this request, based on the specified login configuration. Return `true` if any specified constraint has been satisfied, or `false` if we have created a response challenge already.
    Specified by:
      `doAuthenticate` in class `AuthenticatorBase`
    Parameters:
      `request` - Request we are processing
      `response` - Response we are creating
    Returns:
      `true` if the the user was authenticated, otherwise `false`, in which case an authentication challenge will have been written to the response
    Throws:
      `IOException` - if an input/output error occurs

  - ### getAuthMethod

    protected String getAuthMethod()
    Description copied from class: `AuthenticatorBase`
    Return the authentication method, which is vendor-specific and not defined by HttpServletRequest.
    Specified by:
      `getAuthMethod` in class `AuthenticatorBase`
    Returns:
      the authentication method, which is vendor-specific and not defined by HttpServletRequest.

  - ### removeQuotes

    @Deprecated protected static String removeQuotes(String quotedString, boolean quotesRequired)
    Deprecated.
    This will be removed in Tomcat 11 onwards. Unused.
    Removes the quotes on a string. RFC2617 states quotes are optional for all parameters except realm.
    Parameters:
      `quotedString` - The quoted string
      `quotesRequired` - `true` if quotes were required
    Returns:
      The unquoted string

  - ### removeQuotes

    @Deprecated protected static String removeQuotes(String quotedString)
    Deprecated.
    This will be removed in Tomcat 11 onwards. Unused.
    Removes the quotes on a string.
    Parameters:
      `quotedString` - The quoted string
    Returns:
      The unquoted string

  - ### generateNonce

    protected String generateNonce(Request request)
    Generate a unique token. The token is generated according to the following pattern. NOnceToken = Base64 ( NONCE_DIGEST ( client-IP ":" time-stamp ":" private-key ) ).
    Parameters:
      `request` - HTTP Servlet request
    Returns:
      The generated nonce

  - ### setAuthenticateHeader

    protected void setAuthenticateHeader(HttpServletRequest request, HttpServletResponse response, String nonce, boolean isNonceStale)
    Generates the WWW-Authenticate header(s) as per RFC 7616.
    Parameters:
      `request` - HTTP Servlet request
      `response` - HTTP Servlet response
      `nonce` - nonce token
      `isNonceStale` - `true` to add a stale parameter

  - ### isPreemptiveAuthPossible

    protected boolean isPreemptiveAuthPossible(Request request)
    Description copied from class: `AuthenticatorBase`
    Can the authenticator perform preemptive authentication for the given request?
    Overrides:
      `isPreemptiveAuthPossible` in class `AuthenticatorBase`
    Parameters:
      `request` - The request to check for credentials
    Returns:
      `true` if preemptive authentication is possible, otherwise `false`

  - ### startInternal

    protected void startInternal() throws LifecycleException
    Description copied from class: `ValveBase`
    Start this component and implement the requirements of `LifecycleBase.startInternal()`.
    Overrides:
      `startInternal` in class `AuthenticatorBase`
    Throws:
      `LifecycleException` - if this component detects a fatal error that prevents this component from being used