DigestScheme (HttpClient Library (Version 3.1))
Date: 2019-09-02

org.apache.commons.httpclient.auth

## Class DigestScheme

- java.lang.Object
- - org.apache.commons.httpclient.auth.RFC2617Scheme
  - - org.apache.commons.httpclient.auth.DigestScheme

- All Implemented Interfaces:
    AuthScheme

      public class DigestScheme
      extends RFC2617Scheme

  Digest authentication scheme as defined in RFC 2617. Both MD5 (default) and MD5-sess are supported. Currently only qop=auth or no qop is supported. qop=auth-int is unsupported. If auth and auth-int are provided, auth is used.

  Credential charset is configured via the `credential charset` parameter. Since the digest username is included as clear text in the generated Authentication header, the charset of the username must be compatible with the `http element charset`.

  TODO: make class more stateful regarding repeated authentication requests
  Author:
    Remy Maucherat, Rodney Waldhoff, Jeff Dever, Ortwin Glueck, Sean C. Sullivan, Adrian Sutton, Mike Bowler, Oleg Kalnichevski

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `DigestScheme()` Default constructor for the digest authetication scheme.
    `DigestScheme(java.lang.String challenge)` Deprecated. Use parameterless constructor and `AuthScheme.processChallenge(String)` method

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `java.lang.String` | `authenticate(Credentials credentials, HttpMethod method)` Produces a digest authorization string for the given set of `Credentials`, method name and URI.
    `java.lang.String` | `authenticate(Credentials credentials, java.lang.String method, java.lang.String uri)` Deprecated. Use `authenticate(Credentials, HttpMethod)`
    `static java.lang.String` | `createCnonce()` Creates a random cnonce value based on the current time.
    `java.lang.String` | `getID()` Deprecated. no longer used
    `java.lang.String` | `getSchemeName()` Returns textual designation of the digest authentication scheme.
    `boolean` | `isComplete()` Tests if the Digest authentication process has been completed.
    `boolean` | `isConnectionBased()` Returns `false`.
    `void` | `processChallenge(java.lang.String challenge)` Processes the Digest challenge.

    - ### Methods inherited from class org.apache.commons.httpclient.auth.RFC2617Scheme

      `getParameter, getParameters, getRealm`

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

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

- - ### Constructor Detail

    - #### DigestScheme

          public DigestScheme()

      Default constructor for the digest authetication scheme.
      Since:
        3.0

    - #### DigestScheme

          public DigestScheme(java.lang.String challenge)
                       throws MalformedChallengeException

      Deprecated. Use parameterless constructor and `AuthScheme.processChallenge(String)` method
      Constructor for the digest authetication scheme.
      Parameters:
        `challenge` - authentication challenge
      Throws:
        `MalformedChallengeException` - is thrown if the authentication challenge is malformed

  - ### Method Detail

    - #### getID

          public java.lang.String getID()

      Deprecated. no longer used
      Gets an ID based upon the realm and the nonce value. This ensures that requests to the same realm with different nonce values will succeed. This differentiation allows servers to request re-authentication using a fresh nonce value.
      Specified by:
        `getID` in interface `AuthScheme`
      Overrides:
        `getID` in class `RFC2617Scheme`
      Returns:
        String a String identifying the authentication challenge. The returned value may be null.

    - #### processChallenge

          public void processChallenge(java.lang.String challenge)
                                throws MalformedChallengeException

      Processes the Digest challenge.
      Specified by:
        `processChallenge` in interface `AuthScheme`
      Overrides:
        `processChallenge` in class `RFC2617Scheme`
      Parameters:
        `challenge` - the challenge string
      Throws:
        `MalformedChallengeException` - is thrown if the authentication challenge is malformed
      Since:
        3.0

    - #### isComplete

          public boolean isComplete()

      Tests if the Digest authentication process has been completed.
      Returns:
        `true` if Digest authorization has been processed, `false` otherwise.
      Since:
        3.0

    - #### getSchemeName

          public java.lang.String getSchemeName()

      Returns textual designation of the digest authentication scheme.
      Returns:
        `digest`

    - #### isConnectionBased

          public boolean isConnectionBased()

      Returns `false`. Digest authentication scheme is request based.
      Returns:
        `false`.
      Since:
        3.0

    - #### authenticate

          public java.lang.String authenticate(Credentials credentials,
                                               java.lang.String method,
                                               java.lang.String uri)
                                        throws AuthenticationException

      Deprecated. Use `authenticate(Credentials, HttpMethod)`
      Produces a digest authorization string for the given set of `Credentials`, method name and URI.
      Parameters:
        `credentials` - A set of credentials to be used for athentication
        `method` - the name of the method that requires authorization.
        `uri` - The URI for which authorization is needed.
      Returns:
        a digest authorization string
      Throws:
        `InvalidCredentialsException` - if authentication credentials are not valid or not applicable for this authentication scheme
        `AuthenticationException` - if authorization string cannot be generated due to an authentication failure
      See Also:
        `HttpMethod.getName()`, `HttpMethod.getPath()`

    - #### authenticate

          public java.lang.String authenticate(Credentials credentials,
                                               HttpMethod method)
                                        throws AuthenticationException

      Produces a digest authorization string for the given set of `Credentials`, method name and URI.
      Parameters:
        `credentials` - A set of credentials to be used for athentication
        `method` - The method being authenticated
      Returns:
        a digest authorization string
      Throws:
        `InvalidCredentialsException` - if authentication credentials are not valid or not applicable for this authentication scheme
        `AuthenticationException` - if authorization string cannot be generated due to an authentication failure
      Since:
        3.0

    - #### createCnonce

          public static java.lang.String createCnonce()

      Creates a random cnonce value based on the current time.
      Returns:
        The cnonce value as String.
      Throws:
        `HttpClientError` - if MD5 algorithm is not supported.

Copyright (c) 1999-2005 - Apache Software Foundation