Added a digest authentication helper

This is the initial work by jf from aio-libs#2213, which I rebased onto the tip
of master. It is fully brought back to life in subsequent commits.

Author: feus4177

Diff for: CHANGES/2218.feature.rst

@@ -0,0 +1 @@
+Added a digest authentication helper class.

Diff for: CONTRIBUTORS.txt

@@ -193,6 +193,7 @@ Jesus Cea
 Jian Zeng
 Jinkyu Yi
 Joel Watts
+John Feusi
 John Parton
 Jon Nabozny
 Jonas Krüger Svensson

Diff for: aiohttp/helpers.py

@@ -8,6 +8,7 @@
 import datetime
 import enum
 import functools
+import hashlib
 import inspect
 import netrc
 import os
@@ -53,7 +54,7 @@
 from propcache.api import under_cached_property as reify
 from yarl import URL
 
-from . import hdrs
+from . import client_exceptions, hdrs
 from .log import client_logger
 from .typedefs import PathLike  # noqa
 
@@ -71,7 +72,14 @@
         dataclasses.dataclass, frozen=True, slots=True
     )
 
-__all__ = ("BasicAuth", "ChainMapProxy", "ETag", "frozen_dataclass_decorator", "reify")
+__all__ = (
+    "BasicAuth",
+    "ChainMapProxy",
+    "ETag",
+    "frozen_dataclass_decorator",
+    "reify",
+    "DigestAuth",
+)
 
 PY_310 = sys.version_info >= (3, 10)
 
@@ -279,6 +287,172 @@ def basicauth_from_netrc(netrc_obj: Optional[netrc.netrc], host: str) -> BasicAu
     return BasicAuth(username, password)
 
 
+def parse_pair(pair):
+    key, value = pair.split("=", 1)
+
+    # If it has a trailing comma, remove it.
+    if value[-1] == ",":
+        value = value[:-1]
+
+    # If it is quoted, then remove them.
+    if value[0] == value[-1] == '"':
+        value = value[1:-1]
+
+    return key, value
+
+
+def parse_key_value_list(header):
+    return {
+        key: value
+        for key, value in [parse_pair(header_pair) for header_pair in header.split(" ")]
+    }
+
+
+class DigestAuth:
+    """
+    HTTP digest authentication helper.
+
+    The work here is based off of
+    https://github.com/requests/requests/blob/v2.18.4/requests/auth.py.
+    """
+
+    def __init__(self, username, password, session, previous=None):
+        if previous is None:
+            previous = {}
+
+        self.username = username
+        self.password = password
+        self.last_nonce = previous.get("last_nonce", "")
+        self.nonce_count = previous.get("nonce_count", 0)
+        self.challenge = previous.get("challenge")
+        self.args = {}
+        self.session = session
+
+    async def request(self, method, url, *, headers=None, **kwargs):
+        if headers is None:
+            headers = {}
+
+        # Save the args so we can re-run the request
+        self.args = {"method": method, "url": url, "headers": headers, "kwargs": kwargs}
+
+        if self.challenge:
+            headers[hdrs.AUTHORIZATION] = self._build_digest_header(method.upper(), url)
+
+        response = await self.session.request(method, url, headers=headers, **kwargs)
+
+        # Only try performing digest authentication if the response status is
+        # from 400 to 500.
+        if 400 <= response.status < 500:
+            return await self._handle_401(response)
+
+        return response
+
+    def _build_digest_header(self, method, url):
+        """
+        Build digest header
+
+        :rtype: str
+        """
+        realm = self.challenge["realm"]
+        nonce = self.challenge["nonce"]
+        qop = self.challenge.get("qop")
+        algorithm = self.challenge.get("algorithm", "MD5").upper()
+        opaque = self.challenge.get("opaque")
+
+        if qop and not (qop == "auth" or "auth" in qop.split(",")):
+            raise client_exceptions.ClientError("Unsupported qop value: %s" % qop)
+
+        # lambdas assume digest modules are imported at the top level
+        if algorithm == "MD5" or algorithm == "MD5-SESS":
+            hash_fn = hashlib.md5
+        elif algorithm == "SHA":
+            hash_fn = hashlib.sha1
+        else:
+            return ""
+
+        def H(x):
+            return hash_fn(x.encode()).hexdigest()
+
+        def KD(s, d):
+            return H(f"{s}:{d}")
+
+        path = URL(url).path_qs
+        A1 = f"{self.username}:{realm}:{self.password}"
+        A2 = f"{method}:{path}"
+
+        HA1 = H(A1)
+        HA2 = H(A2)
+
+        if nonce == self.last_nonce:
+            self.nonce_count += 1
+        else:
+            self.nonce_count = 1
+
+        self.last_nonce = nonce
+
+        ncvalue = "%08x" % self.nonce_count
+
+        # cnonce is just a random string generated by the client.
+        cnonce_data = "".join(
+            [
+                str(self.nonce_count),
+                nonce,
+                time.ctime(),
+                os.urandom(8).decode(errors="ignore"),
+            ]
+        ).encode()
+        cnonce = hashlib.sha1(cnonce_data).hexdigest()[:16]
+
+        if algorithm == "MD5-SESS":
+            HA1 = H(f"{HA1}:{nonce}:{cnonce}")
+
+        # This assumes qop was validated to be 'auth' above. If 'auth-int'
+        # support is added this will need to change.
+        if qop:
+            noncebit = ":".join([nonce, ncvalue, cnonce, "auth", HA2])
+            response_digest = KD(HA1, noncebit)
+        else:
+            response_digest = KD(HA1, f"{nonce}:{HA2}")
+
+        base = ", ".join(
+            [
+                'username="%s"' % self.username,
+                'realm="%s"' % realm,
+                'nonce="%s"' % nonce,
+                'uri="%s"' % path,
+                'response="%s"' % response_digest,
+                'algorithm="%s"' % algorithm,
+            ]
+        )
+        if opaque:
+            base += ', opaque="%s"' % opaque
+        if qop:
+            base += f', qop="auth", nc={ncvalue}, cnonce="{cnonce}"'
+
+        return "Digest %s" % base
+
+    async def _handle_401(self, response):
+        """
+        Takes the given response and tries digest-auth, if needed.
+
+        :rtype: ClientResponse
+        """
+        auth_header = response.headers.get("www-authenticate", "")
+
+        parts = auth_header.split(" ", 1)
+        if "digest" == parts[0].lower() and len(parts) > 1:
+            self.challenge = parse_key_value_list(parts[1])
+
+            return await self.request(
+                self.args["method"],
+                self.args["url"],
+                headers=self.args["headers"],
+                **self.args["kwargs"],
+            )
+
+        return response
+
+
 def proxies_from_env() -> Dict[str, ProxyInfo]:
     proxy_urls = {
         k: URL(v)

Diff for: docs/client_reference.rst

@@ -2011,6 +2011,117 @@ Utilities
       :return: encoded authentication data, :class:`str`.
 
 
+DigestAuth
+^^^^^^^^^^
+
+.. class:: DigestAuth(login, password', session)
+
+   HTTP digest authentication helper. Unlike :class:`DigestAuth`, this helper
+   CANNOT be passed to the *auth* parameter of a :meth:`ClientSession.request`.
+
+   :param str login: login
+   :param str password: password
+   :param `ClientSession` session: underlying session that will use digest auth
+   :param dict previous: dict containing previous auth data. ``None`` by
+                         default (optional).
+
+   .. comethod:: request(method, url, *, params=None, data=None, \
+                               json=None,\
+                               headers=None, cookies=None, auth=None, \
+                               allow_redirects=True, max_redirects=10, \
+                               encoding='utf-8', \
+                               version=HttpVersion(major=1, minor=1), \
+                               compress=None, chunked=None, expect100=False, \
+                               connector=None, loop=None,\
+                               read_until_eof=True)
+      :coroutine:
+
+      Perform an asynchronous HTTP request. Return a response object
+      (:class:`ClientResponse` or derived from).
+
+      :param str method: HTTP method
+
+      :param url: Requested URL, :class:`str` or :class:`~yarl.URL`
+
+      :param dict params: Parameters to be sent in the query
+                          string of the new request (optional)
+
+      :param dict|bytes|file data: Dictionary, bytes, or file-like object to
+                   send in the body of the request (optional)
+
+      :param json: Any json compatible python object (optional). *json* and *data*
+                   parameters could not be used at the same time.
+
+      :param dict headers: HTTP Headers to send with the request (optional)
+
+      :param dict cookies: Cookies to send with the request (optional)
+
+      :param aiohttp.BasicAuth auth: an object that represents HTTP Basic
+                                     Authorization (optional)
+
+      :param bool allow_redirects: If set to ``False``, do not follow redirects.
+                                   ``True`` by default (optional).
+
+      :param aiohttp.protocol.HttpVersion version: Request HTTP version (optional)
+
+      :param bool compress: Set to ``True`` if request has to be compressed
+                            with deflate encoding.
+                            ``False`` instructs aiohttp to not compress data.
+                            ``None`` by default (optional).
+
+      :param int chunked: Enables chunked transfer encoding.
+                          ``None`` by default (optional).
+
+      :param bool expect100: Expect 100-continue response from server.
+                             ``False`` by default (optional).
+
+      :param aiohttp.connector.BaseConnector connector: BaseConnector sub-class
+         instance to support connection pooling.
+
+      :param bool read_until_eof: Read response until EOF if response
+                                  does not have Content-Length header.
+                                  ``True`` by default (optional).
+
+      :param loop: :ref:`event loop<asyncio-event-loop>`
+                   used for processing HTTP requests.
+                   If param is ``None``, :func:`asyncio.get_event_loop`
+                   is used for getting default event loop.
+
+                   .. deprecated:: 2.0
+
+      :rtype: :class:`client response <ClientResponse>`
+
+   Usage::
+
+      import aiohttp
+      import asyncio
+
+      async def fetch(client):
+          auth = aiohttp.DigestAuth('usr', 'psswd', client)
+          resp = await auth.request('GET', 'http://httpbin.org/digest-auth/auth/usr/psswd/MD5/never')
+          assert resp.status == 200
+          # If you don't reuse the DigestAuth object you can store this data
+          # and pass it as the last argument the next time you instantiate a
+          # DigestAuth object. For example,
+          # aiohttp.DigestAuth('usr', 'psswd', client, previous). This will
+          # save a second request being launched to re-authenticate.
+          previous = {
+              'nonce_count': auth.nonce_count,
+              'last_nonce': auth.last_nonce,
+              'challenge': auth.challenge,
+          }
+
+          return await resp.text()
+
+      async def main():
+          async with aiohttp.ClientSession() as client:
+              text = await fetch(client)
+              print(text)
+
+      loop = asyncio.get_event_loop()
+      loop.run_until_complete(main())
+
+
 .. class:: CookieJar(*, unsafe=False, quote_cookie=True, treat_as_secure_origin = [])
 
    The cookie jar instance is available as :attr:`ClientSession.cookie_jar`.