cherrypy.lib.auth_digest module

HTTP Digest Authentication tool.

An implementation of the server-side of HTTP Digest Access Authentication, which is described in RFC 2617.

Example usage, using the built-in get_ha1_dict_plain function which uses a dict of plaintext passwords as the credentials store:

userpassdict = {'alice' : '4x5istwelve'}
get_ha1 = cherrypy.lib.auth_digest.get_ha1_dict_plain(userpassdict)
digest_auth = {'tools.auth_digest.on': True,
               'tools.auth_digest.realm': 'wonderland',
               'tools.auth_digest.get_ha1': get_ha1,
               'tools.auth_digest.key': 'a565c27146791cfb',
               'tools.auth_digest.accept_charset': 'UTF-8',
app_config = { '/' : digest_auth }

The hash function H.

class cherrypy.lib.auth_digest.HttpDigestAuthorization(auth_header, http_method, debug=False, accept_charset='UTF-8')[source]

Bases: object

Parses a Digest Authorization header and performs re-calculation of the digest.


Return the H(A2) string.

See RFC 2617 section


Return True if a validated nonce is stale.

The nonce contains a timestamp in plaintext and also a secure hash of the timestamp. You should first validate the nonce to ensure the plaintext timestamp is not spoofed.

classmethod matches(header)[source]
request_digest(ha1, entity_body='')[source]

Calculates the Request-Digest. See RFC 2617 section


The HA1 string obtained from the credentials store.


If ‘qop’ is set to ‘auth-int’, then A2 includes a hash of the “entity body”. The entity body is the part of the message which follows the HTTP headers. See RFC 2617 section 4.3. This refers to the entity the user agent sent in the request which has the Authorization header. Typically GET requests don’t have an entity, and POST requests do.

scheme = 'digest'
validate_nonce(s, key)[source]

Validate the nonce. Returns True if nonce was generated by synthesize_nonce() and the timestamp is not spoofed, else returns False.


A string related to the resource, such as the hostname of the server.


A secret string known only to the server.

Both s and key must be the same values which were used to synthesize the nonce we are trying to validate.

cherrypy.lib.auth_digest._respond_401(realm, key, accept_charset, debug, **kwargs)[source]

Respond with 401 status and a WWW-Authenticate header.

cherrypy.lib.auth_digest._try_decode_header(header, charset)[source]
cherrypy.lib.auth_digest.digest_auth(realm, get_ha1, key, debug=False, accept_charset='utf-8')[source]

A CherryPy tool that hooks at before_handler to perform HTTP Digest Access Authentication, as specified in RFC 2617.

If the request has an ‘authorization’ header with a ‘Digest’ scheme, this tool authenticates the credentials supplied in that header. If the request has no ‘authorization’ header, or if it does but the scheme is not “Digest”, or if authentication fails, the tool sends a 401 response with a ‘WWW-Authenticate’ Digest header.


A string containing the authentication realm.


A callable that looks up a username in a credentials store and returns the HA1 string, which is defined in the RFC to be MD5(username : realm : password). The function’s signature is: get_ha1(realm, username) where username is obtained from the request’s ‘authorization’ header. If username is not found in the credentials store, get_ha1() returns None.


A secret string known only to the server, used in the synthesis of nonces.


Return a get_ha1 function which obtains a HA1 password hash from a dictionary of the form: {username : HA1}.

If you want a dictionary-based authentication scheme, but with pre-computed HA1 hashes instead of plain-text passwords, use get_ha1_dict(my_userha1_dict) as the value for the get_ha1 argument to digest_auth().


Return a get_ha1 function which obtains a plaintext password from a dictionary of the form: {username : password}.

If you want a simple dictionary-based authentication scheme, with plaintext passwords, use get_ha1_dict_plain(my_userpass_dict) as the value for the get_ha1 argument to digest_auth().


Return a get_ha1 function which obtains a HA1 password hash from a flat file with lines of the same format as that produced by the Apache htdigest utility. For example, for realm ‘wonderland’, username ‘alice’, and password ‘4x5istwelve’, the htdigest line would be:


If you want to use an Apache htdigest file as the credentials store, then use get_ha1_file_htdigest(my_htdigest_file) as the value for the get_ha1 argument to digest_auth(). It is recommended that the filename argument be an absolute path, to avoid problems.

cherrypy.lib.auth_digest.synthesize_nonce(s, key, timestamp=None)[source]

Synthesize a nonce value which resists spoofing and can be checked for staleness. Returns a string suitable as the value for ‘nonce’ in the www-authenticate header.


A string related to the resource, such as the hostname of the server.


A secret string known only to the server.


An integer seconds-since-the-epoch timestamp

cherrypy.lib.auth_digest.www_authenticate(realm, key, algorithm='MD5', nonce=None, qop='auth', stale=False, accept_charset='UTF-8')[source]

Constructs a WWW-Authenticate header for Digest authentication.