2
httpauth modules defines functions to implement HTTP Digest Authentication (RFC 2617).
3
This has full compliance with 'Digest' and 'Basic' authentication methods. In
4
'Digest' it supports both MD5 and MD5-sess algorithms.
8
First use 'doAuth' to request the client authentication for a
9
certain resource. You should send an httplib.UNAUTHORIZED response to the
10
client so he knows he has to authenticate itself.
12
Then use 'parseAuthorization' to retrieve the 'auth_map' used in
15
To use 'checkResponse' you must have already verified the password associated
16
with the 'username' key in 'auth_map' dict. Then you use the 'checkResponse'
17
function to verify if the password matches the one sent by the client.
19
SUPPORTED_ALGORITHM - list of supported 'Digest' algorithms
20
SUPPORTED_QOP - list of supported 'Digest' 'qop'.
23
__author__ = "Tiago Cogumbreiro <cogumbreiro@users.sf.net>"
25
Peter van Kampen for its recipe which implement most of Digest authentication:
26
http://aspn.activestate.com/ASPN/Cookbook/Python/Recipe/302378
30
Copyright (c) 2005, Tiago Cogumbreiro <cogumbreiro@users.sf.net>
33
Redistribution and use in source and binary forms, with or without modification,
34
are permitted provided that the following conditions are met:
36
* Redistributions of source code must retain the above copyright notice,
37
this list of conditions and the following disclaimer.
38
* Redistributions in binary form must reproduce the above copyright notice,
39
this list of conditions and the following disclaimer in the documentation
40
and/or other materials provided with the distribution.
41
* Neither the name of Sylvain Hellegouarch nor the names of his contributors
42
may be used to endorse or promote products derived from this software
43
without specific prior written permission.
45
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
46
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
47
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
48
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE
49
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
50
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
51
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
52
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
53
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
54
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
57
__all__ = ("digestAuth", "basicAuth", "doAuth", "checkResponse",
58
"parseAuthorization", "SUPPORTED_ALGORITHM", "md5SessionKey",
59
"calculateNonce", "SUPPORTED_QOP")
61
################################################################################
64
from hashlib import md5
66
from md5 import new as md5
69
from urllib2 import parse_http_list, parse_keqv_list
76
SUPPORTED_ALGORITHM = (MD5, MD5_SESS)
77
SUPPORTED_QOP = (AUTH, AUTH_INT)
79
################################################################################
82
DIGEST_AUTH_ENCODERS = {
83
MD5: lambda val: md5(val).hexdigest(),
84
MD5_SESS: lambda val: md5(val).hexdigest(),
85
# SHA: lambda val: sha.new (val).hexdigest (),
88
def calculateNonce (realm, algorithm = MD5):
89
"""This is an auxaliary function that calculates 'nonce' value. It is used
90
to handle sessions."""
92
global SUPPORTED_ALGORITHM, DIGEST_AUTH_ENCODERS
93
assert algorithm in SUPPORTED_ALGORITHM
96
encoder = DIGEST_AUTH_ENCODERS[algorithm]
98
raise NotImplementedError ("The chosen algorithm (%s) does not have "\
99
"an implementation yet" % algorithm)
101
return encoder ("%d:%s" % (time.time(), realm))
103
def digestAuth (realm, algorithm = MD5, nonce = None, qop = AUTH):
104
"""Challenges the client for a Digest authentication."""
105
global SUPPORTED_ALGORITHM, DIGEST_AUTH_ENCODERS, SUPPORTED_QOP
106
assert algorithm in SUPPORTED_ALGORITHM
107
assert qop in SUPPORTED_QOP
110
nonce = calculateNonce (realm, algorithm)
112
return 'Digest realm="%s", nonce="%s", algorithm="%s", qop="%s"' % (
113
realm, nonce, algorithm, qop
116
def basicAuth (realm):
117
"""Challengenes the client for a Basic authentication."""
118
assert '"' not in realm, "Realms cannot contain the \" (quote) character."
120
return 'Basic realm="%s"' % realm
123
"""'doAuth' function returns the challenge string b giving priority over
124
Digest and fallback to Basic authentication when the browser doesn't
125
support the first one.
127
This should be set in the HTTP header under the key 'WWW-Authenticate'."""
129
return digestAuth (realm) + " " + basicAuth (realm)
132
################################################################################
133
# Parse authorization parameters
135
def _parseDigestAuthorization (auth_params):
136
# Convert the auth params to a dict
137
items = parse_http_list(auth_params)
138
params = parse_keqv_list(items)
140
# Now validate the params
142
# Check for required parameters
143
required = ["username", "realm", "nonce", "uri", "response"]
148
# If qop is sent then cnonce and nc MUST be present
149
if "qop" in params and not ("cnonce" in params \
153
# If qop is not sent, neither cnonce nor nc can be present
154
if ("cnonce" in params or "nc" in params) and \
161
def _parseBasicAuthorization (auth_params):
162
username, password = base64.decodestring (auth_params).split (":", 1)
163
return {"username": username, "password": password}
166
"basic": _parseBasicAuthorization,
167
"digest": _parseDigestAuthorization,
170
def parseAuthorization (credentials):
171
"""parseAuthorization will convert the value of the 'Authorization' key in
172
the HTTP header to a map itself. If the parsing fails 'None' is returned.
177
auth_scheme, auth_params = credentials.split(" ", 1)
178
auth_scheme = auth_scheme.lower ()
180
parser = AUTH_SCHEMES[auth_scheme]
181
params = parser (auth_params)
186
assert "auth_scheme" not in params
187
params["auth_scheme"] = auth_scheme
191
################################################################################
192
# Check provided response for a valid password
194
def md5SessionKey (params, password):
196
If the "algorithm" directive's value is "MD5-sess", then A1
197
[the session key] is calculated only once - on the first request by the
198
client following receipt of a WWW-Authenticate challenge from the server.
200
This creates a 'session key' for the authentication of subsequent
201
requests and responses which is different for each "authentication
202
session", thus limiting the amount of material hashed with any one
205
Because the server need only use the hash of the user
206
credentials in order to create the A1 value, this construction could
207
be used in conjunction with a third party authentication service so
208
that the web server would not need the actual password value. The
209
specification of such a protocol is beyond the scope of this
213
keys = ("username", "realm", "nonce", "cnonce")
216
params_copy[key] = params[key]
218
params_copy["algorithm"] = MD5_SESS
219
return _A1 (params_copy, password)
221
def _A1(params, password):
222
algorithm = params.get ("algorithm", MD5)
223
H = DIGEST_AUTH_ENCODERS[algorithm]
226
# If the "algorithm" directive's value is "MD5" or is
227
# unspecified, then A1 is:
228
# A1 = unq(username-value) ":" unq(realm-value) ":" passwd
229
return "%s:%s:%s" % (params["username"], params["realm"], password)
231
elif algorithm == MD5_SESS:
233
# This is A1 if qop is set
234
# A1 = H( unq(username-value) ":" unq(realm-value) ":" passwd )
235
# ":" unq(nonce-value) ":" unq(cnonce-value)
236
h_a1 = H ("%s:%s:%s" % (params["username"], params["realm"], password))
237
return "%s:%s:%s" % (h_a1, params["nonce"], params["cnonce"])
240
def _A2(params, method, kwargs):
241
# If the "qop" directive's value is "auth" or is unspecified, then A2 is:
242
# A2 = Method ":" digest-uri-value
244
qop = params.get ("qop", "auth")
246
return method + ":" + params["uri"]
247
elif qop == "auth-int":
248
# If the "qop" value is "auth-int", then A2 is:
249
# A2 = Method ":" digest-uri-value ":" H(entity-body)
250
entity_body = kwargs.get ("entity_body", "")
253
return "%s:%s:%s" % (
260
raise NotImplementedError ("The 'qop' method is unknown: %s" % qop)
262
def _computeDigestResponse(auth_map, password, method = "GET", A1 = None,**kwargs):
264
Generates a response respecting the algorithm defined in RFC 2617
268
algorithm = params.get ("algorithm", MD5)
270
H = DIGEST_AUTH_ENCODERS[algorithm]
271
KD = lambda secret, data: H(secret + ":" + data)
273
qop = params.get ("qop", None)
275
H_A2 = H(_A2(params, method, kwargs))
277
if algorithm == MD5_SESS and A1 is not None:
280
H_A1 = H(_A1(params, password))
282
if qop in ("auth", "auth-int"):
283
# If the "qop" value is "auth" or "auth-int":
284
# request-digest = <"> < KD ( H(A1), unq(nonce-value)
286
# ":" unq(cnonce-value)
290
request = "%s:%s:%s:%s:%s" % (
298
# If the "qop" directive is not present (this construction is
299
# for compatibility with RFC 2069):
301
# <"> < KD ( H(A1), unq(nonce-value) ":" H(A2) ) > <">
302
request = "%s:%s" % (params["nonce"], H_A2)
304
return KD(H_A1, request)
306
def _checkDigestResponse(auth_map, password, method = "GET", A1 = None, **kwargs):
307
"""This function is used to verify the response given by the client when
308
he tries to authenticate.
310
entity_body - when 'qop' is set to 'auth-int' you MUST provide the
311
raw data you are going to send to the client (usually the
313
request_uri - the uri from the request line compared with the 'uri'
314
directive of the authorization map. They must represent
315
the same resource (unused at this time).
318
if auth_map['realm'] != kwargs.get('realm', None):
321
response = _computeDigestResponse(auth_map, password, method, A1,**kwargs)
323
return response == auth_map["response"]
325
def _checkBasicResponse (auth_map, password, method='GET', encrypt=None, **kwargs):
326
# Note that the Basic response doesn't provide the realm value so we cannot
329
return encrypt(auth_map["password"], auth_map["username"]) == password
331
return encrypt(auth_map["password"]) == password
334
"basic": _checkBasicResponse,
335
"digest": _checkDigestResponse,
338
def checkResponse (auth_map, password, method = "GET", encrypt=None, **kwargs):
339
"""'checkResponse' compares the auth_map with the password and optionally
340
other arguments that each implementation might need.
342
If the response is of type 'Basic' then the function has the following
345
checkBasicResponse (auth_map, password) -> bool
347
If the response is of type 'Digest' then the function has the following
350
checkDigestResponse (auth_map, password, method = 'GET', A1 = None) -> bool
352
The 'A1' argument is only used in MD5_SESS algorithm based responses.
353
Check md5SessionKey() for more info.
355
global AUTH_RESPONSES
356
checker = AUTH_RESPONSES[auth_map["auth_scheme"]]
357
return checker (auth_map, password, method=method, encrypt=encrypt, **kwargs)
added
removed
cherrypy/lib/httpauth.py
