Package cherrypy :: Package lib :: Module httpauth
[hide private]
[frames] | no frames]

Module httpauth

source code


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.

Usage:
    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'.


Author: Tiago Cogumbreiro <cogumbreiro@users.sf.net>

License: Copyright (c) 2005, Tiago Cogumbreiro <cogumbreiro@users.sf.net> All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: * Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. * Neither the name of Sylvain Hellegouarch nor the names of his contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Functions [hide private]
 
calculateNonce(realm, algorithm='MD5')
This is an auxaliary function that calculates 'nonce' value.
source code
 
digestAuth(realm, algorithm='MD5', nonce=None, qop='auth')
Challenges the client for a Digest authentication.
source code
 
basicAuth(realm)
Challengenes the client for a Basic authentication.
source code
 
doAuth(realm)
'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.
source code
 
_parseDigestAuthorization(auth_params) source code
 
_parseBasicAuthorization(auth_params) source code
 
parseAuthorization(credentials)
parseAuthorization will convert the value of the 'Authorization' key in the HTTP header to a map itself.
source code
 
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.
source code
 
_A1(params, password) source code
 
_A2(params, method, kwargs) source code
 
_computeDigestResponse(auth_map, password, method='GET', A1=None, **kwargs)
Generates a response respecting the algorithm defined in RFC 2617
source code
 
_checkDigestResponse(auth_map, password, method='GET', A1=None, **kwargs)
This function is used to verify the response given by the client when he tries to authenticate.
source code
 
_checkBasicResponse(auth_map, password, method='GET', encrypt=None, **kwargs) source code
 
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.
source code
Variables [hide private]
  __credits__ = '\n Peter van Kampen for its recipe which imp...
  MD5 = 'MD5'
  MD5_SESS = 'MD5-sess'
  AUTH = 'auth'
  AUTH_INT = 'auth-int'
  SUPPORTED_ALGORITHM = ('MD5', 'MD5-sess')
  SUPPORTED_QOP = ('auth', 'auth-int')
  DIGEST_AUTH_ENCODERS = {'MD5': <__builtin__.function object>, ...
  AUTH_SCHEMES = {'basic': <__builtin__.function object>, 'diges...
  AUTH_RESPONSES = {'basic': <__builtin__.function object>, 'dig...
  __package__ = 'cherrypy.lib'
Function Details [hide private]

calculateNonce(realm, algorithm='MD5')

source code 

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

doAuth(realm)

source code 

'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(credentials)

source code 

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

md5SessionKey(params, password)

source code 

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.

_checkDigestResponse(auth_map, password, method='GET', A1=None, **kwargs)

source code 
This function is used to verify the response given by the client when
he tries to authenticate.
Optional arguments:
 entity_body - when 'qop' is set to 'auth-int' you MUST provide the
               raw data you are going to send to the client (usually the
               HTML page.
 request_uri - the uri from the request line compared with the 'uri'
               directive of the authorization map. They must represent
               the same resource (unused at this time).

checkResponse(auth_map, password, method='GET', encrypt=None, **kwargs)

source code 

'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.


Variables Details [hide private]

__credits__

Value:
'''
    Peter van Kampen for its recipe which implement most of Digest
    authentication:
    http://aspn.activestate.com/ASPN/Cookbook/Python/Recipe/302378
'''

DIGEST_AUTH_ENCODERS

Value:
{'MD5': <__builtin__.function object>,
 'MD5-sess': <__builtin__.function object>}

AUTH_SCHEMES

Value:
{'basic': <__builtin__.function object>,
 'digest': <__builtin__.function object>}

AUTH_RESPONSES

Value:
{'basic': <__builtin__.function object>,
 'digest': <__builtin__.function object>}