1 """
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.
5
6 Usage:
7
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.
11
12 Then use 'parseAuthorization' to retrieve the 'auth_map' used in
13 'checkResponse'.
14
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.
18
19 SUPPORTED_ALGORITHM - list of supported 'Digest' algorithms
20 SUPPORTED_QOP - list of supported 'Digest' 'qop'.
21 """
22 __version__ = 1, 0, 0
23 __author__ = "Tiago Cogumbreiro <cogumbreiro@users.sf.net>"
24 __credits__ = """
25 Peter van Kampen for its recipe which implement most of Digest authentication:
26 http://aspn.activestate.com/ASPN/Cookbook/Python/Recipe/302378
27 """
28
29 __license__ = """
30 Copyright (c) 2005, Tiago Cogumbreiro <cogumbreiro@users.sf.net>
31 All rights reserved.
32
33 Redistribution and use in source and binary forms, with or without modification,
34 are permitted provided that the following conditions are met:
35
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.
44
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.
55 """
56
57 __all__ = ("digestAuth", "basicAuth", "doAuth", "checkResponse",
58 "parseAuthorization", "SUPPORTED_ALGORITHM", "md5SessionKey",
59 "calculateNonce", "SUPPORTED_QOP")
60
61
62 import md5
63 import time
64 import base64
65 import urllib2
66
67 MD5 = "MD5"
68 MD5_SESS = "MD5-sess"
69 AUTH = "auth"
70 AUTH_INT = "auth-int"
71
72 SUPPORTED_ALGORITHM = (MD5, MD5_SESS)
73 SUPPORTED_QOP = (AUTH, AUTH_INT)
74
75
76
77
78 DIGEST_AUTH_ENCODERS = {
79 MD5: lambda val: md5.new (val).hexdigest (),
80 MD5_SESS: lambda val: md5.new (val).hexdigest (),
81
82 }
83
85 """This is an auxaliary function that calculates 'nonce' value. It is used
86 to handle sessions."""
87
88 global SUPPORTED_ALGORITHM, DIGEST_AUTH_ENCODERS
89 assert algorithm in SUPPORTED_ALGORITHM
90
91 try:
92 encoder = DIGEST_AUTH_ENCODERS[algorithm]
93 except KeyError:
94 raise NotImplementedError ("The chosen algorithm (%s) does not have "\
95 "an implementation yet" % algorithm)
96
97 return encoder ("%d:%s" % (time.time(), realm))
98
111
113 """Challengenes the client for a Basic authentication."""
114 assert '"' not in realm, "Realms cannot contain the \" (quote) character."
115
116 return 'Basic realm="%s"' % realm
117
119 """'doAuth' function returns the challenge string b giving priority over
120 Digest and fallback to Basic authentication when the browser doesn't
121 support the first one.
122
123 This should be set in the HTTP header under the key 'WWW-Authenticate'."""
124
125 return digestAuth (realm) + " " + basicAuth (realm)
126
127
128
129
130
132
133 items = urllib2.parse_http_list (auth_params)
134 params = urllib2.parse_keqv_list (items)
135
136
137
138
139 required = ["username", "realm", "nonce", "uri", "response"]
140 for k in required:
141 if not params.has_key(k):
142 return None
143
144
145 if params.has_key("qop") and not params.has_key("cnonce") \
146 and params.has_key("cn"):
147 return None
148
149 return params
150
151
153 username, password = base64.decodestring (auth_params).split (":", 1)
154 return {"username": username, "password": password}
155
156 AUTH_SCHEMES = {
157 "basic": _parseBasicAuthorization,
158 "digest": _parseDigestAuthorization,
159 }
160
162 """parseAuthorization will convert the value of the 'Authorization' key in
163 the HTTP header to a map itself. If the parsing fails 'None' is returned.
164 """
165
166 global AUTH_SCHEMES
167
168 auth_scheme, auth_params = credentials.split(" ", 1)
169 auth_scheme = auth_scheme.lower ()
170
171 parser = AUTH_SCHEMES[auth_scheme]
172 params = parser (auth_params)
173
174 if params is None:
175 return
176
177 assert "auth_scheme" not in params
178 params["auth_scheme"] = auth_scheme
179 return params
180
181
182
183
184
186 """
187 If the "algorithm" directive's value is "MD5-sess", then A1
188 [the session key] is calculated only once - on the first request by the
189 client following receipt of a WWW-Authenticate challenge from the server.
190
191 This creates a 'session key' for the authentication of subsequent
192 requests and responses which is different for each "authentication
193 session", thus limiting the amount of material hashed with any one
194 key.
195
196 Because the server need only use the hash of the user
197 credentials in order to create the A1 value, this construction could
198 be used in conjunction with a third party authentication service so
199 that the web server would not need the actual password value. The
200 specification of such a protocol is beyond the scope of this
201 specification.
202 """
203
204 keys = ("username", "realm", "nonce", "cnonce")
205 params_copy = {}
206 for key in keys:
207 params_copy[key] = params[key]
208
209 params_copy["algorithm"] = MD5_SESS
210 return _A1 (params_copy, password)
211
212 -def _A1(params, password):
229
230
231 -def _A2(params, method, kwargs):
232
233
234
235 qop = params.get ("qop", "auth")
236 if qop == "auth":
237 return method + ":" + params["uri"]
238 elif qop == "auth-int":
239
240
241 entity_body = kwargs.get ("entity_body", "")
242 H = kwargs["H"]
243
244 return "%s:%s:%s" % (
245 method,
246 params["uri"],
247 H(entity_body)
248 )
249
250 else:
251 raise NotImplementedError ("The 'qop' method is unknown: %s" % qop)
252
254 """
255 Generates a response respecting the algorithm defined in RFC 2617
256 """
257 params = auth_map
258
259 algorithm = params.get ("algorithm", MD5)
260
261 H = DIGEST_AUTH_ENCODERS[algorithm]
262 KD = lambda secret, data: H(secret + ":" + data)
263
264 qop = params.get ("qop", None)
265
266 H_A2 = H(_A2(params, method, kwargs))
267
268 if algorithm == MD5_SESS and A1 is not None:
269 H_A1 = H(A1)
270 else:
271 H_A1 = H(_A1(params, password))
272
273 if qop == "auth" or aop == "auth-int":
274
275
276
277
278
279
280
281 request = "%s:%s:%s:%s:%s" % (
282 params["nonce"],
283 params["nc"],
284 params["cnonce"],
285 params["qop"],
286 H_A2,
287 )
288
289 elif qop is None:
290
291
292
293
294 request = "%s:%s" % (params["nonce"], H_A2)
295
296 return KD(H_A1, request)
297
299 """This function is used to verify the response given by the client when
300 he tries to authenticate.
301 Optional arguments:
302 entity_body - when 'qop' is set to 'auth-int' you MUST provide the
303 raw data you are going to send to the client (usually the
304 HTML page.
305 """
306
307 response = _computeDigestResponse(auth_map, password, method, A1,**kwargs)
308
309 return response == auth_map["response"]
310
312 return encrypt(auth_map["password"]) == password
313
314 AUTH_RESPONSES = {
315 "basic": _checkBasicResponse,
316 "digest": _checkDigestResponse,
317 }
318
319 -def checkResponse (auth_map, password, method = "GET", encrypt=None, **kwargs):
320 """'checkResponse' compares the auth_map with the password and optionally
321 other arguments that each implementation might need.
322
323 If the response is of type 'Basic' then the function has the following
324 signature:
325
326 checkBasicResponse (auth_map, password) -> bool
327
328 If the response is of type 'Digest' then the function has the following
329 signature:
330
331 checkDigestResponse (auth_map, password, method = 'GET', A1 = None) -> bool
332
333 The 'A1' argument is only used in MD5_SESS algorithm based responses.
334 Check md5SessionKey() for more info.
335 """
336 global AUTH_RESPONSES
337 checker = AUTH_RESPONSES[auth_map["auth_scheme"]]
338 return checker (auth_map, password, method=method, encrypt=encrypt, **kwargs)
339