HTTP Digest authentication support

docs/examples/digest_auth.py

@@ -0,0 +1,16 @@
+from twisted.internet.task import react
+from _utils import print_response
+
+import treq
+from treq.auth import HTTPDigestAuth
+
+
+def main(reactor, *args):
+    d = treq.get(
+        'http://httpbin.org/digest-auth/auth/treq/treq',
+        auth=HTTPDigestAuth('treq', 'treq')
+    )
+    d.addCallback(print_response)
+    return d
+
+react(main, [])

docs/howto.rst

@@ -52,7 +52,25 @@ The ``auth`` argument should be a tuple of the form ``('username', 'password')``
 
 Full example: :download:`basic_auth.py <examples/basic_auth.py>`
 
+HTTP Digest authentication is supported by passing an instance of
+:py:class:`treq.auth.HTTPDigestAuth` to any of the request functions by using the `auth` keyword argument.
+We support only "auth" QoP as defined at `RFC 2617`_
+or simple `RFC 2069`_ without QoP at the moment. Treq takes care of
+HTTP digest credentials caching - after authorization on any URL/method pair,
+the library will use the first time received HTTP digest credentials on that endpoint
+for further requests, and will not perform any redundant requests for obtaining the creds.
+
+:py:class:`treq.auth.HTTPDigestAuth` class accepts ``username`` and ``password``
+as constructor arguments.
+
+.. literalinclude:: examples/digest_auth.py
+    :linenos:
+    :lines: 5-14
+
+Full example: :download:`digest_auth.py <examples/digest_auth.py>`
+
 .. _RFC 2617: http://www.ietf.org/rfc/rfc2617.txt
+.. _RFC 2069: http://www.ietf.org/rfc/rfc2069.txt
 
 Redirects
 ---------

docs/index.rst

@@ -71,7 +71,7 @@ Here is a list of `requests`_ features and their status in treq.
 +----------------------------------+----------+----------+
 | Basic Authentication             | yes      | yes      |
 +----------------------------------+----------+----------+
-| Digest Authentication            | yes      | no       |
+| Digest Authentication            | yes      | yes      |
 +----------------------------------+----------+----------+
 | Elegant Key/Value Cookies        | yes      | yes      |
 +----------------------------------+----------+----------+

treq/auth.py

@@ -1,7 +1,46 @@
 from __future__ import absolute_import, division, print_function
+import re
+import time
+import base64
+import hashlib
 
+from six.moves.urllib.parse import urlparse
 from twisted.web.http_headers import Headers
-import base64
+from twisted.python.randbytes import secureRandom
+from requests.utils import parse_dict_header
+
+
+_DIGEST_HEADER_PREFIX_REGEXP = re.compile(r'digest ', flags=re.IGNORECASE)
+
+
+def generate_client_nonce(server_side_nonce):
+    return hashlib.sha1(
+        hashlib.sha1(server_side_nonce).digest() +
+        secureRandom(16) +
+        time.ctime()
+    ).hexdigest()[:16]
+
+
+def _md5_utf_digest(x):
+    if isinstance(x, str):
+        x = x.encode('utf-8')
+    return hashlib.md5(x).hexdigest()
+
+
+def _sha1_utf_digest(x):
+    if isinstance(x, str):
+        x = x.encode('utf-8')
+    return hashlib.sha1(x).hexdigest()
+
+
+class HTTPDigestAuth(object):
+    """
+    The container for HTTP Digest authentication credentials
+    """
+
+    def __init__(self, username, password):
+        self.username = username
+        self.password = password
 
 
 class UnknownAuthConfig(Exception):
@@ -10,6 +49,25 @@ def __init__(self, config):
             '{0!r} not of a known type.'.format(config))
 
 
+class UnknownQopForDigestAuth(Exception):
+
+    def __init__(self, qop):
+        super(Exception, self).__init__(
+            'Unsupported Quality Of Protection value passed: {qop}'.format(
+                qop=qop
+            )
+        )
+
+
+class UnknownDigestAuthAlgorithm(Exception):
+
+    def __init__(self, algorithm):
+        super(Exception, self).__init__(
+            'Unsupported Digest Auth algorithm identifier passed: {algorithm}'
+            .format(algorithm=algorithm)
+        )
+
+
 class _RequestHeaderSettingAgent(object):
     def __init__(self, agent, request_headers):
         self._agent = agent
@@ -26,6 +84,228 @@ def request(self, method, uri, headers=None, bodyProducer=None):
             method, uri, headers=headers, bodyProducer=bodyProducer)
 
 
+class _RequestDigestAuthenticationAgent(object):
+
+    digest_auth_cache = {}
+
+    def __init__(self, agent, username, password):
+        self._agent = agent
+        self._username = username
+        self._password = password
+
+    def _build_digest_authentication_header(self, agent, path, method, cached,
+        nonce, realm, qop=None, algorithm='MD5', opaque=None):
+        """
+        Build the authorization header for credentials got from the server.
+        Algorithm is accurately ported from http://python-requests.org
+            with small adjustments.
+        See
+        https://github.com/kennethreitz/requests/blob/v2.5.1/requests/auth.py#L72
+            for details.
+        :param agent: _RequestDigestAuthenticationAgent instance
+        :param algorithm: algorithm to be used for authentication,
+            defaults to MD5, supported values are
+            "MD5", "MD5-SESS" and "SHA"
+        :param realm: HTTP Digest authentication realm
+        :param nonce: "nonce" HTTP Digest authentication param
+        :param qop: Quality Of Protection HTTP Digest auth param
+        :param opaque: "opaque" HTTP Digest authentication param
+             (should be sent back to server unchanged)
+        :param cached: Identifies that authentication already have been
+             performed for URI/method,
+             and new request should use the same params as first
+             authenticated request
+        :param path: the URI path where we are authenticating
+        :param method: HTTP method to be used when requesting
+        :return: HTTP Digest authentication string
+        """
+        algo = algorithm.upper()
+        original_algo = algorithm
+        path_parsed = urlparse(path)
+        actual_path = path_parsed.path
+
+        if path_parsed.query:
+            actual_path += '?' + path_parsed.query
+
+        a1 = '%s:%s:%s' % (
+            self._username,
+            realm,
+            self._password
+        )
+
+        a2 = '%s:%s' % (
+            method,
+            actual_path
+        )
+
+        if algo == 'MD5' or algo == 'MD5-SESS':
+            digest_hash_func = _md5_utf_digest
+        elif algo == 'SHA':
+            digest_hash_func = _sha1_utf_digest
+        else:
+            raise UnknownDigestAuthAlgorithm(algo)
+
+        ha1 = digest_hash_func(a1)
+        ha2 = digest_hash_func(a2)
+
+        cnonce = generate_client_nonce(nonce)
+
+        if algo == 'MD5-SESS':
+            ha1 = digest_hash_func("%s:%s:%s" % (ha1, nonce, cnonce), algo)
+
+        if cached:
+            agent.digest_auth_cache[(method, path)]['c'] += 1
+            nonce_count = agent.digest_auth_cache[
+                (method, path)
+            ]['c']
+        else:
+            nonce_count = 1
+
+        ncvalue = '%08x' % nonce_count
+        if qop is None:
+            response_digest = digest_hash_func(
+                "%s:%s" % (ha1, "%s:%s" % (ha2, nonce))
+            )
+        else:
+            noncebit = "%s:%s:%s:%s:%s" % (
+                nonce, ncvalue, cnonce.encode('utf-8'), 'auth', ha2
+            )
+            response_digest = digest_hash_func("%s:%s" % (ha1, noncebit))
+
+        hb = 'username="%s", realm="%s", nonce="%s", uri="%s", response="%s"' % (
+            self._username, realm, nonce, actual_path, response_digest
+        )
+        if opaque:
+            hb += ', opaque="%s"' % opaque
+        if original_algo:
+            hb += ', algorithm="%s"' % original_algo
+        if qop:
+            hb += ', qop="auth", nc=%s, cnonce="%s"' % (ncvalue, cnonce)
+        if not cached:
+            cache_params = {
+                'agent': agent,
+                'path': path,
+                'method': method,
+                'cached': cached,
+                'nonce': nonce,
+                'realm': realm,
+                'qop': qop,
+                'algorithm': algorithm,
+                'opaque': opaque
+            }
+            agent.digest_auth_cache[(method, path)] = {
+                'p': cache_params,
+                'c': 1
+            }
+        return 'Digest %s' % hb
+
+    def _on_401_response(self, www_authenticate_response, method, uri, headers,
+                         bodyProducer):
+        """
+        Handle the server`s 401 response, that is capable with authentication
+            headers, build the Authorization header
+        for
+        :param www_authenticate_response: t.w.client.Response object
+        :param method: HTTP method to be used to perform the request
+        :param uri: URI to be used
+        :param headers: Additional headers to be sent with the request,
+            instead of "Authorization" header
+        :param bodyProducer: IBodyProducer implementer instance that would be
+            used to fetch the response body
+        :return:
+        """
+        assert www_authenticate_response.code == 401, \
+            """Got invalid pre-authentication response code, probably URL
+            does not support Digest auth
+        """
+        www_authenticate_header_string = www_authenticate_response.\
+            headers._rawHeaders.get('www-authenticate', [''])[0]
+        digest_authentication_params = parse_dict_header(
+            _DIGEST_HEADER_PREFIX_REGEXP.sub(
+                '', www_authenticate_header_string, count=1
+            )
+        )
+        if digest_authentication_params.get('qop', None) is not None and \
+            digest_authentication_params['qop'] != 'auth' and \
+                'auth' not in digest_authentication_params['qop'].split(','):
+            # We support only "auth" QoP as defined in rfc-2617 or rfc-2069
+            raise UnknownQopForDigestAuth(digest_authentication_params['qop'])
+        digest_authentication_header = self._build_digest_authentication_header(
+            self,
+            uri,
+            method,
+            False,
+            digest_authentication_params['nonce'],
+            digest_authentication_params['realm'],
+            qop=digest_authentication_params['qop']
+        )
+        return self._perform_request(
+            digest_authentication_header, method, uri, headers, bodyProducer
+        )
+
+    def _perform_request(self, digest_authentication_header, method, uri,
+                         headers, bodyProducer):
+        """
+        Add Authorization header and perform the request with
+            actual credentials
+        :param digest_authentication_header: HTTP Digest Authorization
+            header string
+        :param method: HTTP method to be used to perform the request
+        :param uri: URI to be used
+        :param headers: Headers to be sent with the request
+        :param bodyProducer: IBodyProducer implementer instance that would be
+            used to fetch the response body
+        :return: t.i.defer.Deferred (holding the result of the request)
+        """
+        if not headers:
+            headers = Headers({'Authorization': digest_authentication_header})
+        else:
+            headers.addRawHeader('Authorization', digest_authentication_header)
+        return self._agent.request(
+            method, uri, headers=headers, bodyProducer=bodyProducer
+        )
+
+    def request(self, method, uri, headers=None, bodyProducer=None):
+        """
+        Wrap the agent with HTTP Digest authentication.
+        :param method: HTTP method to be used to perform the request
+        :param uri: URI to be used
+        :param headers: Headers to be sent with the request
+        :param bodyProducer: IBodyProducer implementer instance that would be
+            used to fetch the response body
+        :return: t.i.defer.Deferred (holding the result of the request)
+        """
+        if self.digest_auth_cache.get((method, uri), None) is None:
+            # Perform first request for getting the realm;
+            # the client awaits for 401 response code here
+            d = self._agent.request('GET', uri,
+                                    headers=headers, bodyProducer=None)
+            d.addCallback(self._on_401_response, method, uri,
+                          headers, bodyProducer)
+        else:
+            # We have performed authentication on that URI already
+            digest_params_from_cache = self.digest_auth_cache.get(
+                (method, uri)
+            )['p']
+            digest_params_from_cache['cached'] = True
+            digest_authentication_header = self._build_digest_authentication_header(
+                self,
+                digest_params_from_cache['path'],
+                digest_params_from_cache['method'],
+                digest_params_from_cache['cached'],
+                digest_params_from_cache['nonce'],
+                digest_params_from_cache['realm'],
+                qop=digest_params_from_cache['qop'],
+                algorithm=digest_params_from_cache['algorithm'],
+                opaque=digest_params_from_cache['opaque']
+            )
+            d = self._perform_request(
+                digest_authentication_header, method,
+                uri, headers, bodyProducer
+            )
+        return d
+
+
 def add_basic_auth(agent, username, password):
     creds = base64.b64encode(
         '{0}:{1}'.format(username, password).encode('ascii'))
@@ -34,8 +314,16 @@ def add_basic_auth(agent, username, password):
         Headers({b'Authorization': [b'Basic ' + creds]}))
 
 
+def add_digest_auth(agent, http_digest_auth):
+    return _RequestDigestAuthenticationAgent(
+        agent, http_digest_auth.username, http_digest_auth.password
+    )
+
+
 def add_auth(agent, auth_config):
     if isinstance(auth_config, tuple):
         return add_basic_auth(agent, auth_config[0], auth_config[1])
+    elif isinstance(auth_config, HTTPDigestAuth):
+        return add_digest_auth(agent, auth_config)
 
     raise UnknownAuthConfig(auth_config)