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:

RegistrationListener, MBeanRegistration, 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"

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	Holds the parsed and validated information from a Digest authentication request.
static class	DigestAuthenticator.NonceInfo	Tracks information about a server nonce, including timestamp and seen nonce counts.

Nested classes/interfaces inherited from class AuthenticatorBase

AuthenticatorBase.AllowCorsPreflight, AuthenticatorBase.SsoReauthenticationMode

Nested classes/interfaces inherited from interface 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	Lock object used to ensure unique timestamps for nonce generation.
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 AuthenticatorBase

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

Fields inherited from class ValveBase

asyncSupported, container, containerLog, next

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
DigestAuthenticator()	Construct a new DigestAuthenticator with caching disabled.

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()	Get the configured authentication algorithms as a comma-separated list.
protected String	getAuthMethod()	Return the authentication method, which is vendor-specific and not defined by HttpServletRequest.
String	getKey()	Get the private key used for nonce generation.
int	getNonceCacheSize()	Get the maximum number of server nonces to keep in the cache.
int	getNonceCountWindowSize()	Get the window size to use to track seen nonce count values for a given nonce.
long	getNonceValidity()	Get how long server nonces are valid for in milliseconds.
String	getOpaque()	Get the opaque string.
protected boolean	isPreemptiveAuthPossible(Request request)	Can the authenticator perform preemptive authentication for the given request?
boolean	isValidateUri()	Get whether the URI should be validated as required by RFC2617.
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)	Set the configured authentication algorithms as a comma-separated list.
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)	Set the private key used for nonce generation.
void	setNonceCacheSize(int nonceCacheSize)	Set the maximum number of server nonces to keep in the cache.
void	setNonceCountWindowSize(int nonceCountWindowSize)	Set the window size to use to track seen nonce count values for a given nonce.
void	setNonceValidity(long nonceValidity)	Set how long server nonces are valid for in milliseconds.
void	setOpaque(String opaque)	Set the opaque string.
void	setValidateUri(boolean validateUri)	Set whether the URI should be validated as required by RFC2617.
protected void	startInternal()	Start this component and implement the requirements of LifecycleBase.startInternal().

Methods inherited from class AuthenticatorBase

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

Methods inherited from class ValveBase

backgroundProcess, getDomainInternal, getNext, getObjectNameKeyProperties, initInternal, isAsyncSupported, setAsyncSupported, setNext, 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

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

Lock object used to ensure unique timestamps for nonce generation.

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

Construct a new DigestAuthenticator with caching disabled.

Method Details

getNonceCountWindowSize

public int getNonceCountWindowSize()

Get the window size to use to track seen nonce count values for a given nonce.

Returns:

Nonce count window size

setNonceCountWindowSize

public void setNonceCountWindowSize(int nonceCountWindowSize)

Set the window size to use to track seen nonce count values for a given nonce.

Parameters:

nonceCountWindowSize - Nonce count window size

getNonceCacheSize

public int getNonceCacheSize()

Get the maximum number of server nonces to keep in the cache.

Returns:

Nonce cache size

setNonceCacheSize

public void setNonceCacheSize(int nonceCacheSize)

Set the maximum number of server nonces to keep in the cache.

Parameters:

nonceCacheSize - Nonce cache size

getKey

public String getKey()

Get the private key used for nonce generation.

Returns:

Private key

setKey

public void setKey(String key)

Set the private key used for nonce generation.

Parameters:

key - Private key

getNonceValidity

public long getNonceValidity()

Get how long server nonces are valid for in milliseconds.

Returns:

Nonce validity in milliseconds

setNonceValidity

public void setNonceValidity(long nonceValidity)

Set how long server nonces are valid for in milliseconds.

Parameters:

nonceValidity - Nonce validity in milliseconds

getOpaque

public String getOpaque()

Get the opaque string.

Returns:

Opaque string

setOpaque

public void setOpaque(String opaque)

Set the opaque string.

Parameters:

opaque - Opaque string

isValidateUri

public boolean isValidateUri()

Get whether the URI should be validated as required by RFC2617.

Returns:

true if URI validation is enabled

setValidateUri

public void setValidateUri(boolean validateUri)

Set whether the URI should be validated as required by RFC2617.

Parameters:

validateUri - true to enable URI validation

getAlgorithms

public String getAlgorithms()

Get the configured authentication algorithms as a comma-separated list.

Returns:

Comma-separated list of algorithm names

setAlgorithms

public void setAlgorithms(String algorithmsString)

Set the configured authentication algorithms as a comma-separated list.

Parameters:

algorithmsString - Comma-separated list of algorithm names

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