com.helger.http.digestauth

Class DigestAuthServerBuilder

java.lang.Object

com.helger.http.digestauth.DigestAuthServerBuilder

All Implemented Interfaces:

Serializable

@NotThreadSafe
public class DigestAuthServerBuilder
extends Object
implements Serializable

Helper class to build the value of the CHttpHeader.WWW_AUTHENTICATE value send from the server to client.

Author:

Philip Helger

See Also:

Serialized Form

Constructor Summary

Constructors

Constructor and Description
DigestAuthServerBuilder()

Method Summary

Modifier and Type	Method and Description
DigestAuthServerBuilder	addDomain(com.helger.commons.url.ISimpleURL aURL) Add an URIs, as specified in RFC XURI, that define the protection space.
DigestAuthServerBuilder	addQOP(String sQOP) This directive is optional, but is made so only for backward compatibility with RFC 2069 [6]; it SHOULD be used by all implementations compliant with this version of the Digest scheme.
String	build()
boolean	isValid()
DigestAuthServerBuilder	setAlgorithm(String sAlgorithm) A string indicating a pair of algorithms used to produce the digest and a checksum.
DigestAuthServerBuilder	setNonce(String sNonce) A server-specified data string which should be uniquely generated each time a 401 response is made.
DigestAuthServerBuilder	setOpaque(String sOpaque) A string of data, specified by the server, which should be returned by the client unchanged in the Authorization header of subsequent requests with URIs in the same protection space.
DigestAuthServerBuilder	setRealm(String sRealm) A string to be displayed to users so they know which username and password to use.
DigestAuthServerBuilder	setStale(com.helger.commons.state.ETriState eStale) A flag, indicating that the previous request from the client was rejected because the nonce value was stale.

Methods inherited from class java.lang.Object

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

Constructor Detail

DigestAuthServerBuilder

public DigestAuthServerBuilder()

Method Detail

setRealm

@Nonnull
public DigestAuthServerBuilder setRealm(@Nonnull
                                                  String sRealm)

A string to be displayed to users so they know which username and password to use. This string should contain at least the name of the host performing the authentication and might additionally indicate the collection of users who might have access. An example might be "registered_users@gotham.news.com".

Parameters:

sRealm - The realm to be used. May not be null and should not be empty.

Returns:

this

addDomain

@Nonnull
public DigestAuthServerBuilder addDomain(@Nonnull
                                                   com.helger.commons.url.ISimpleURL aURL)

Add an URIs, as specified in RFC XURI, that define the protection space. If a URI is an abs_path, it is relative to the canonical root URL of the server being accessed. An absoluteURI in this list may refer to a different server than the one being accessed. The client can use this list to determine the set of URIs for which the same authentication information may be sent: any URI that has a URI in this list as a prefix (after both have been made absolute) may be assumed to be in the same protection space. If this directive is omitted or its value is empty, the client should assume that the protection space consists of all URIs on the responding server. This directive is not meaningful in Proxy-Authenticate headers, for which the protection space is always the entire proxy; if present it should be ignored.

Parameters:

aURL - The absolute or relative path which is protected. May not be null.

Returns:

this

setNonce

@Nonnull
public DigestAuthServerBuilder setNonce(@Nonnull
                                                  String sNonce)

A server-specified data string which should be uniquely generated each time a 401 response is made. It is recommended that this string be base64 or hexadecimal data. Specifically, since the string is passed in the header lines as a quoted string, the double-quote character is not allowed.
The contents of the nonce are implementation dependent. The quality of the implementation depends on a good choice. A nonce might, for example, be constructed as the base 64 encoding of
time-stamp H(time-stamp ":" ETag ":" private-key)
where time-stamp is a server-generated time or other non-repeating value, ETag is the value of the HTTP ETag header associated with the requested entity, and private-key is data known only to the server. With a nonce of this form a server would recalculate the hash portion after receiving the client authentication header and reject the request if it did not match the nonce from that header or if the time-stamp value is not recent enough. In this way the server can limit the time of the nonce’s validity. The inclusion of the ETag prevents a replay request for an updated version of the resource. (Note: including the IP address of the client in the nonce would appear to offer the server the ability to limit the reuse of the nonce to the same client that originally got it. However, that would break proxy farms, where requests from a single user often go through different proxies in the farm. Also, IP address spoofing is not that hard.)
An implementation might choose not to accept a previously used nonce or a previously used digest, in order to protect against a replay attack. Or, an implementation might choose to use one-time nonces or digests for POST or PUT requests and a time-stamp for GET requests. For more details on the issues involved see section 4. of this document.
The nonce is opaque to the client.

Parameters:

sNonce - The nonce value to be set. May not be null.

Returns:

this

setOpaque

@Nonnull
public DigestAuthServerBuilder setOpaque(@Nonnull
                                                   String sOpaque)

A string of data, specified by the server, which should be returned by the client unchanged in the Authorization header of subsequent requests with URIs in the same protection space. It is recommended that this string be base64 or hexadecimal data.

Parameters:

sOpaque - The opaque value. May not be null.

Returns:

this

setStale

@Nonnull
public DigestAuthServerBuilder setStale(@Nonnull
                                                  com.helger.commons.state.ETriState eStale)

A flag, indicating that the previous request from the client was rejected because the nonce value was stale. If stale is TRUE (case-insensitive), the client may wish to simply retry the request with a new encrypted response, without reprompting the user for a new username and password. The server should only set stale to TRUE if it receives a request for which the nonce is invalid but with a valid digest for that nonce (indicating that the client knows the correct username/password). If stale is FALSE, or anything other than TRUE, or the stale directive is not present, the username and/or password are invalid, and new values must be obtained.

Parameters:

eStale - Stale value. May not be null.

Returns:

this

setAlgorithm

@Nonnull
public DigestAuthServerBuilder setAlgorithm(@Nonnull
                                                      String sAlgorithm)

A string indicating a pair of algorithms used to produce the digest and a checksum. If this is not present it is assumed to be "MD5". If the algorithm is not understood, the challenge should be ignored (and a different one used, if there is more than one). In this document the string obtained by applying the digest algorithm to the data "data" with secret "secret" will be denoted by KD(secret, data), and the string obtained by applying the checksum algorithm to the data "data" will be denoted H(data). The notation unq(X) means the value of the quoted-string X without the surrounding quotes.
For the "MD5" and "MD5-sess" algorithms
H(data) = MD5(data)
and
KD(secret, data) = H(concat(secret, ":", data))
i.e., the digest is the MD5 of the secret concatenated with a colon concatenated with the data. The "MD5-sess" algorithm is intended to allow efficient 3rd party authentication servers; for the difference in usage, see the description in section 3.2.2.2.

Parameters:

sAlgorithm - Algorithm name

Returns:

this

addQOP

@Nonnull
public DigestAuthServerBuilder addQOP(@Nonnull
                                                String sQOP)

This directive is optional, but is made so only for backward compatibility with RFC 2069 [6]; it SHOULD be used by all implementations compliant with this version of the Digest scheme. If present, it is a quoted string of one or more tokens indicating the "quality of protection" values supported by the server. The value "auth" indicates authentication; the value "auth-int" indicates authentication with integrity protection; see the descriptions below for calculating the response directive value for the application of this choice. Unrecognized options MUST be ignored.

Parameters:

sQOP - The qop-option to add. May not be null.

Returns:

this

isValid

public boolean isValid()

build

@Nonnull
 @Nonempty
public String build()