Package com.helger.http.digestauth

Class DigestAuthServerBuilder

java.lang.Object
com.helger.http.digestauth.DigestAuthServerBuilder
@NotThreadSafe public class DigestAuthServerBuilder extends Object
Helper class to build the value of the CHttpHeader.WWW_AUTHENTICATE value send from the server to client.
Author:
Philip Helger

  • Constructor Summary

    Constructors
    Constructor
    Description
    DigestAuthServerBuilder()
    Constructor creating an empty Digest authentication server builder.

  • Method Summary

    Modifier and Type
    Method
    Description
    @NonNull DigestAuthServerBuilder
    addDomain(@NonNull com.helger.url.ISimpleURL aURL)
    Add an URIs, as specified in RFC XURI, that define the protection space.
    @NonNull 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.
    @NonNull @Nonempty String
    build()
    Build the WWW-Authenticate header value for Digest authentication.
    boolean
    isValid()
     
    @NonNull DigestAuthServerBuilder
    setAlgorithm(@NonNull String sAlgorithm)
    A string indicating a pair of algorithms used to produce the digest and a checksum.
    @NonNull DigestAuthServerBuilder
    setNonce(@NonNull String sNonce)
    A server-specified data string which should be uniquely generated each time a 401 response is made.
    @NonNull 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.
    @NonNull DigestAuthServerBuilder
    setRealm(@NonNull String sRealm)
    A string to be displayed to users so they know which username and password to use.
    @NonNull DigestAuthServerBuilder
    setStale(@NonNull com.helger.base.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 Details

    • DigestAuthServerBuilder

      public DigestAuthServerBuilder()
      Constructor creating an empty Digest authentication server builder.

  • Method Details

    • setRealm

      public @NonNull 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

      public @NonNull DigestAuthServerBuilder addDomain(@NonNull com.helger.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

      public @NonNull 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

      public @NonNull 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

      public @NonNull DigestAuthServerBuilder setStale(@NonNull com.helger.base.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

      public @NonNull 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

      public @NonNull 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()
      Returns:
      true if both realm and nonce are set, making this builder valid for building.

    • build

      @Nonempty public @NonNull @Nonempty String build()
      Build the WWW-Authenticate header value for Digest authentication.
      Returns:
      The complete header value string. Neither null nor empty.
      Throws:
      IllegalStateException - If the builder is not valid (realm or nonce missing).