This module defines functions to implement HTTP Digest Authentication (RFC 2617). This has full compliance with ‘Digest’ and ‘Basic’ authentication methods. In ‘Digest’ it supports both MD5 and MD5-sess algorithms.


First use ‘doAuth’ to request the client authentication for a certain resource. You should send an httplib.UNAUTHORIZED response to the client so he knows he has to authenticate itself.

Then use ‘parseAuthorization’ to retrieve the ‘auth_map’ used in ‘checkResponse’.

To use ‘checkResponse’ you must have already verified the password associated with the ‘username’ key in ‘auth_map’ dict. Then you use the ‘checkResponse’ function to verify if the password matches the one sent by the client.

SUPPORTED_ALGORITHM - list of supported ‘Digest’ algorithms SUPPORTED_QOP - list of supported ‘Digest’ ‘qop’.


cherrypy.lib.httpauth.calculateNonce(realm, algorithm='MD5')

This is an auxaliary function that calculates ‘nonce’ value. It is used to handle sessions.

cherrypy.lib.httpauth.digestAuth(realm, algorithm='MD5', nonce=None, qop='auth')

Challenges the client for a Digest authentication.


Challengenes the client for a Basic authentication.


‘doAuth’ function returns the challenge string b giving priority over Digest and fallback to Basic authentication when the browser doesn’t support the first one.

This should be set in the HTTP header under the key ‘WWW-Authenticate’.


parseAuthorization will convert the value of the ‘Authorization’ key in the HTTP header to a map itself. If the parsing fails ‘None’ is returned.

cherrypy.lib.httpauth.md5SessionKey(params, password)

If the “algorithm” directive’s value is “MD5-sess”, then A1 [the session key] is calculated only once - on the first request by the client following receipt of a WWW-Authenticate challenge from the server.

This creates a ‘session key’ for the authentication of subsequent requests and responses which is different for each “authentication session”, thus limiting the amount of material hashed with any one key.

Because the server need only use the hash of the user credentials in order to create the A1 value, this construction could be used in conjunction with a third party authentication service so that the web server would not need the actual password value. The specification of such a protocol is beyond the scope of this specification.

cherrypy.lib.httpauth.checkResponse(auth_map, password, method='GET', encrypt=None, **kwargs)

‘checkResponse’ compares the auth_map with the password and optionally other arguments that each implementation might need.

If the response is of type ‘Basic’ then the function has the following signature:

checkBasicResponse(auth_map, password) -> bool

If the response is of type ‘Digest’ then the function has the following signature:

checkDigestResponse(auth_map, password, method='GET', A1=None) -> bool

The ‘A1’ argument is only used in MD5_SESS algorithm based responses. Check md5SessionKey() for more info.