1
# This file is part of CherryPy <http://www.cherrypy.org/>
2
# -*- coding: utf-8 -*-
3
# vim:ts=4:sw=4:expandtab:fileencoding=utf-8
5
__doc__ = """An implementation of the server-side of HTTP Digest Access
6
Authentication, which is described in :rfc:`2617`.
8
Example usage, using the built-in get_ha1_dict_plain function which uses a dict
9
of plaintext passwords as the credentials store::
11
userpassdict = {'alice' : '4x5istwelve'}
12
get_ha1 = cherrypy.lib.auth_digest.get_ha1_dict_plain(userpassdict)
13
digest_auth = {'tools.auth_digest.on': True,
14
'tools.auth_digest.realm': 'wonderland',
15
'tools.auth_digest.get_ha1': get_ha1,
16
'tools.auth_digest.key': 'a565c27146791cfb',
18
app_config = { '/' : digest_auth }
21
__author__ = 'visteya'
22
__date__ = 'April 2009'
26
from cherrypy._cpcompat import parse_http_list, parse_keqv_list
29
from cherrypy._cpcompat import md5, ntob
30
md5_hex = lambda s: md5(ntob(s)).hexdigest()
33
qop_auth_int = 'auth-int'
34
valid_qops = (qop_auth, qop_auth_int)
36
valid_algorithms = ('MD5', 'MD5-sess')
40
cherrypy.log(msg, context='TOOLS.AUTH_DIGEST')
42
# Three helper functions for users of the tool, providing three variants
43
# of get_ha1() functions for three different kinds of credential stores.
44
def get_ha1_dict_plain(user_password_dict):
45
"""Returns a get_ha1 function which obtains a plaintext password from a
46
dictionary of the form: {username : password}.
48
If you want a simple dictionary-based authentication scheme, with plaintext
49
passwords, use get_ha1_dict_plain(my_userpass_dict) as the value for the
50
get_ha1 argument to digest_auth().
52
def get_ha1(realm, username):
53
password = user_password_dict.get(username)
55
return md5_hex('%s:%s:%s' % (username, realm, password))
60
def get_ha1_dict(user_ha1_dict):
61
"""Returns a get_ha1 function which obtains a HA1 password hash from a
62
dictionary of the form: {username : HA1}.
64
If you want a dictionary-based authentication scheme, but with
65
pre-computed HA1 hashes instead of plain-text passwords, use
66
get_ha1_dict(my_userha1_dict) as the value for the get_ha1
67
argument to digest_auth().
69
def get_ha1(realm, username):
70
return user_ha1_dict.get(user)
74
def get_ha1_file_htdigest(filename):
75
"""Returns a get_ha1 function which obtains a HA1 password hash from a
76
flat file with lines of the same format as that produced by the Apache
77
htdigest utility. For example, for realm 'wonderland', username 'alice',
78
and password '4x5istwelve', the htdigest line would be::
80
alice:wonderland:3238cdfe91a8b2ed8e39646921a02d4c
82
If you want to use an Apache htdigest file as the credentials store,
83
then use get_ha1_file_htdigest(my_htdigest_file) as the value for the
84
get_ha1 argument to digest_auth(). It is recommended that the filename
85
argument be an absolute path, to avoid problems.
87
def get_ha1(realm, username):
89
f = open(filename, 'r')
91
u, r, ha1 = line.rstrip().split(':')
92
if u == username and r == realm:
101
def synthesize_nonce(s, key, timestamp=None):
102
"""Synthesize a nonce value which resists spoofing and can be checked for staleness.
103
Returns a string suitable as the value for 'nonce' in the www-authenticate header.
106
A string related to the resource, such as the hostname of the server.
109
A secret string known only to the server.
112
An integer seconds-since-the-epoch timestamp
115
if timestamp is None:
116
timestamp = int(time.time())
117
h = md5_hex('%s:%s:%s' % (timestamp, s, key))
118
nonce = '%s:%s' % (timestamp, h)
123
"""The hash function H"""
127
class HttpDigestAuthorization (object):
128
"""Class to parse a Digest Authorization header and perform re-calculation
133
return 'Digest Authorization header: %s' % s
135
def __init__(self, auth_header, http_method, debug=False):
136
self.http_method = http_method
138
scheme, params = auth_header.split(" ", 1)
139
self.scheme = scheme.lower()
140
if self.scheme != 'digest':
141
raise ValueError('Authorization scheme is not "Digest"')
143
self.auth_header = auth_header
145
# make a dict of the params
146
items = parse_http_list(params)
147
paramsd = parse_keqv_list(items)
149
self.realm = paramsd.get('realm')
150
self.username = paramsd.get('username')
151
self.nonce = paramsd.get('nonce')
152
self.uri = paramsd.get('uri')
153
self.method = paramsd.get('method')
154
self.response = paramsd.get('response') # the response digest
155
self.algorithm = paramsd.get('algorithm', 'MD5')
156
self.cnonce = paramsd.get('cnonce')
157
self.opaque = paramsd.get('opaque')
158
self.qop = paramsd.get('qop') # qop
159
self.nc = paramsd.get('nc') # nonce count
161
# perform some correctness checks
162
if self.algorithm not in valid_algorithms:
163
raise ValueError(self.errmsg("Unsupported value for algorithm: '%s'" % self.algorithm))
165
has_reqd = self.username and \
171
raise ValueError(self.errmsg("Not all required parameters are present."))
174
if self.qop not in valid_qops:
175
raise ValueError(self.errmsg("Unsupported value for qop: '%s'" % self.qop))
176
if not (self.cnonce and self.nc):
177
raise ValueError(self.errmsg("If qop is sent then cnonce and nc MUST be present"))
179
if self.cnonce or self.nc:
180
raise ValueError(self.errmsg("If qop is not sent, neither cnonce nor nc can be present"))
184
return 'authorization : %s' % self.auth_header
186
def validate_nonce(self, s, key):
187
"""Validate the nonce.
188
Returns True if nonce was generated by synthesize_nonce() and the timestamp
189
is not spoofed, else returns False.
192
A string related to the resource, such as the hostname of the server.
195
A secret string known only to the server.
197
Both s and key must be the same values which were used to synthesize the nonce
198
we are trying to validate.
201
timestamp, hashpart = self.nonce.split(':', 1)
202
s_timestamp, s_hashpart = synthesize_nonce(s, key, timestamp).split(':', 1)
203
is_valid = s_hashpart == hashpart
205
TRACE('validate_nonce: %s' % is_valid)
207
except ValueError: # split() error
212
def is_nonce_stale(self, max_age_seconds=600):
213
"""Returns True if a validated nonce is stale. The nonce contains a
214
timestamp in plaintext and also a secure hash of the timestamp. You should
215
first validate the nonce to ensure the plaintext timestamp is not spoofed.
218
timestamp, hashpart = self.nonce.split(':', 1)
219
if int(timestamp) + max_age_seconds > int(time.time()):
221
except ValueError: # int() error
224
TRACE("nonce is stale")
228
def HA2(self, entity_body=''):
229
"""Returns the H(A2) string. See :rfc:`2617` section 3.2.2.3."""
231
# If the "qop" directive's value is "auth" or is unspecified, then A2 is:
232
# A2 = method ":" digest-uri-value
234
# If the "qop" value is "auth-int", then A2 is:
235
# A2 = method ":" digest-uri-value ":" H(entity-body)
236
if self.qop is None or self.qop == "auth":
237
a2 = '%s:%s' % (self.http_method, self.uri)
238
elif self.qop == "auth-int":
239
a2 = "%s:%s:%s" % (self.http_method, self.uri, H(entity_body))
241
# in theory, this should never happen, since I validate qop in __init__()
242
raise ValueError(self.errmsg("Unrecognized value for qop!"))
246
def request_digest(self, ha1, entity_body=''):
247
"""Calculates the Request-Digest. See :rfc:`2617` section 3.2.2.1.
250
The HA1 string obtained from the credentials store.
253
If 'qop' is set to 'auth-int', then A2 includes a hash
254
of the "entity body". The entity body is the part of the
255
message which follows the HTTP headers. See :rfc:`2617` section
256
4.3. This refers to the entity the user agent sent in the request which
257
has the Authorization header. Typically GET requests don't have an entity,
258
and POST requests do.
261
ha2 = self.HA2(entity_body)
262
# Request-Digest -- RFC 2617 3.2.2.1
264
req = "%s:%s:%s:%s:%s" % (self.nonce, self.nc, self.cnonce, self.qop, ha2)
266
req = "%s:%s" % (self.nonce, ha2)
270
# If the "algorithm" directive's value is "MD5" or is unspecified, then A1 is:
271
# A1 = unq(username-value) ":" unq(realm-value) ":" passwd
273
# If the "algorithm" directive's value is "MD5-sess", then A1 is
274
# calculated only once - on the first request by the client following
275
# receipt of a WWW-Authenticate challenge from the server.
276
# A1 = H( unq(username-value) ":" unq(realm-value) ":" passwd )
277
# ":" unq(nonce-value) ":" unq(cnonce-value)
278
if self.algorithm == 'MD5-sess':
279
ha1 = H('%s:%s:%s' % (ha1, self.nonce, self.cnonce))
281
digest = H('%s:%s' % (ha1, req))
286
def www_authenticate(realm, key, algorithm='MD5', nonce=None, qop=qop_auth, stale=False):
287
"""Constructs a WWW-Authenticate header for Digest authentication."""
288
if qop not in valid_qops:
289
raise ValueError("Unsupported value for qop: '%s'" % qop)
290
if algorithm not in valid_algorithms:
291
raise ValueError("Unsupported value for algorithm: '%s'" % algorithm)
294
nonce = synthesize_nonce(realm, key)
295
s = 'Digest realm="%s", nonce="%s", algorithm="%s", qop="%s"' % (
296
realm, nonce, algorithm, qop)
298
s += ', stale="true"'
302
def digest_auth(realm, get_ha1, key, debug=False):
303
"""A CherryPy tool which hooks at before_handler to perform
304
HTTP Digest Access Authentication, as specified in :rfc:`2617`.
306
If the request has an 'authorization' header with a 'Digest' scheme, this
307
tool authenticates the credentials supplied in that header. If
308
the request has no 'authorization' header, or if it does but the scheme is
309
not "Digest", or if authentication fails, the tool sends a 401 response with
310
a 'WWW-Authenticate' Digest header.
313
A string containing the authentication realm.
316
A callable which looks up a username in a credentials store
317
and returns the HA1 string, which is defined in the RFC to be
318
MD5(username : realm : password). The function's signature is:
319
``get_ha1(realm, username)``
320
where username is obtained from the request's 'authorization' header.
321
If username is not found in the credentials store, get_ha1() returns
325
A secret string known only to the server, used in the synthesis of nonces.
328
request = cherrypy.serving.request
330
auth_header = request.headers.get('authorization')
331
nonce_is_stale = False
332
if auth_header is not None:
334
auth = HttpDigestAuthorization(auth_header, request.method, debug=debug)
336
raise cherrypy.HTTPError(400, "The Authorization header could not be parsed.")
341
if auth.validate_nonce(realm, key):
342
ha1 = get_ha1(realm, auth.username)
344
# note that for request.body to be available we need to hook in at
345
# before_handler, not on_start_resource like 3.1.x digest_auth does.
346
digest = auth.request_digest(ha1, entity_body=request.body)
347
if digest == auth.response: # authenticated
349
TRACE("digest matches auth.response")
350
# Now check if nonce is stale.
351
# The choice of ten minutes' lifetime for nonce is somewhat arbitrary
352
nonce_is_stale = auth.is_nonce_stale(max_age_seconds=600)
353
if not nonce_is_stale:
354
request.login = auth.username
356
TRACE("authentication of %s successful" % auth.username)
359
# Respond with 401 status and a WWW-Authenticate header
360
header = www_authenticate(realm, key, stale=nonce_is_stale)
363
cherrypy.serving.response.headers['WWW-Authenticate'] = header
364
raise cherrypy.HTTPError(401, "You are not authorized to access that resource")
added
removed
src/cherrypy/lib/auth_digest.py
