3 ### HTTP authentication
5 ### (c) 2013 Mark Wooding
8 ###----- Licensing notice ---------------------------------------------------
10 ### This file is part of Chopwood: a password-changing service.
12 ### Chopwood is free software; you can redistribute it and/or modify
13 ### it under the terms of the GNU Affero General Public License as
14 ### published by the Free Software Foundation; either version 3 of the
15 ### License, or (at your option) any later version.
17 ### Chopwood is distributed in the hope that it will be useful,
18 ### but WITHOUT ANY WARRANTY; without even the implied warranty of
19 ### MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
20 ### GNU Affero General Public License for more details.
22 ### You should have received a copy of the GNU Affero General Public
23 ### License along with Chopwood; if not, see
24 ### <http://www.gnu.org/licenses/>.
26 from __future__ import with_statement
35 import config as CONF; CFG = CONF.CFG
37 import output as O; PRINT = O.PRINT
39 import subcommand as SC
42 ###--------------------------------------------------------------------------
43 ### About the authentication scheme.
45 ### We mustn't allow a CGI user to make changes (or even learn about a user's
46 ### accounts) without authenticating first. Curently, that means a username
47 ### and password, though I really dislike this; maybe I'll add a feature for
48 ### handling TLS client certificates some time.
50 ### We're particularly worried about cross-site request forgery: a forged
51 ### request to change a password to some known value lets a bad guy straight
52 ### into a restricted service -- and a change to the `master' account lets
53 ### him into all of them.
55 ### Once we've satisfied ourselves of the user's credentials, we issue a
56 ### short-lived session token, stored in a cookie namde `chpwd-token'. This
57 ### token has the form `DATE.TAG.USER': here, DATE is the POSIX time of
58 ### issue, as a decimal number; USER is the user's login name; and TAG is a
59 ### cryptographic MAC tag on the string `chpwd-token.DATE.USER'. (The USER
60 ### name is on the end so that it can contain `.' characters without
61 ### introducing parsing difficulties.)
63 ### Secrets for these MAC tags are stored in the database: secrets expire
64 ### after 30 minutes (invalidating all tokens issued with them); we only
65 ### issue a token with a secret that's at most five minutes old. A session's
66 ### lifetime, then, is somewhere between 25 and 30 minutes. We choose the
67 ### lower bound as the cookie lifetime, just so that error messages end up
70 ### A cookie with a valid token is sufficient to grant read-only access to a
71 ### user's account details. However, this authority is ambient: during the
72 ### validity period of the token, a cross-site request forgery can easily
73 ### succeed, since there's nothing about the rest of a request which is hard
74 ### to forge, and the cookie will be supplied automatically by the user
75 ### agent. Showing the user some information we were quite happy to release
76 ### anyway isn't an interesting attack, but we must certainly require
77 ### something stronger for state-change requests. Here, we also check a
78 ### special request parameter `%nonce': forms setting up a `POST' action must
79 ### include an appropriate hidden input element.
81 ### The `%nonce' parameter encodes a randomized `all-or-nothing transform' of
82 ### the (deterministic) MAC tag on `chpwd-nonce.DATE.USER'. The standard
83 ### advice for defeating the BREACH attack (which uses differential
84 ### compression of HTTP payloads which include attacker-provided data to
85 ### recover CSRF tokens) is to transmit an XOR-split of the token; but that
86 ### allows an adversary to recover the token two bytes at a time; this makes
87 ### the attack take 256 times longer, which doesn't really seem enough. A
88 ### proper AONT, on the other hand, means that the adversary gets nothing if
89 ### he can't guess the entire transformed token -- and if he could do that,
90 ### he might as well just carry out the CSRF attack without messing with
91 ### BREACH in the first place.
93 ### Messing about with cookies is a bit annoying, but it's hard to come up
94 ### with alternatives. I'm trying to keep the URLs fairly pretty, and anyway
95 ### putting secrets into them is asking for trouble, since user agents have
96 ### an awful tendecy to store URLs in a history database, send them to
97 ### motherships, leak them in `Referer' headers, and other awful things. Our
98 ### cookie is marked `HttpOnly' so, in particular, user agents must keep them
99 ### out of the grubby mitts of Javascript programs.
101 ### I promise that I'm only using these cookies for the purposes of
102 ### maintaining security: I don't log them or do anything else at all with
105 ###--------------------------------------------------------------------------
106 ### Generating and checking authentication tokens.
108 ## Secret lifetime parameters.
109 CONF.DEFAULTS.update(
111 ## The lifetime of a session cookie, in seconds.
114 ## Maximum age of an authentication key, in seconds.
117 ## Hash function to use for crypto.
121 """Remove dead secrets from the database."""
123 D.DB.execute("DELETE FROM secrets WHERE stamp < $stale",
124 stale = U.NOW - CFG.SECRETLIFE)
128 Return the newest and most shiny secret no older than WHEN.
130 If there is no such secret, or the only one available would have been stale
131 at WHEN, then return `None'.
135 D.DB.execute("""SELECT stamp, secret FROM secrets
137 ORDER BY stamp DESC""",
139 row = D.DB.fetchone()
140 if row is None: return None
141 if row[0] < when - CFG.SECRETFRESH: return None
142 return row[1].decode('base64')
145 """Return a fresh secret."""
148 D.DB.execute("""SELECT secret FROM secrets
149 WHERE stamp >= $fresh
150 ORDER BY stamp DESC""",
151 fresh = U.NOW - CFG.SECRETFRESH)
152 row = D.DB.fetchone()
154 sec = row[0].decode('base64')
157 D.DB.execute("""INSERT INTO secrets(stamp, secret)
158 VALUES ($stamp, $secret)""",
159 stamp = U.NOW, secret = sec.encode('base64'))
163 """Return the octet string S, in a vaguely pretty form."""
164 return BN.b64encode(s, '+$').rstrip('=')
166 def unhack_octets(s):
167 """Reverse the operation done by `hack_octets'."""
168 pad = (len(s) + 3)&3 - len(s)
170 return BN.b64decode(s + '='*pad, '+$')
172 raise AuthenticationFailed, 'BADNONCE'
174 def auth_tag(sec, stamp, user):
175 """Compute a tag using secret SEC on `STAMP.USER'."""
176 hmac = HM.HMAC(sec, digestmod = CFG.AUTHHASH)
177 hmac.update('chpwd-token.%d.%s' % (stamp, user))
178 return hack_octets(hmac.digest())
180 def csrf_tag(sec, stamp, user):
181 """Compute a tag using secret SEC on `STAMP.USER'."""
182 hmac = HM.HMAC(sec, digestmod = CFG.AUTHHASH)
183 hmac.update('chpwd-nonce.%d.%s' % (stamp, user))
186 def xor_strings(x, y):
187 """Return the bitwise XOR of two octet strings."""
188 return ''.join(chr(ord(xc) ^ ord(yc)) for xc, yc in I.izip(x, y))
191 """Perform a step of the OAEP-based all-or-nothing transform."""
192 return xor_strings(y, CFG.AUTHHASH(x).digest())
194 def aont_transform(m):
196 Apply an all-or-nothing transform to a (short, binary) message M.
198 The result is returned as a binary string.
201 ## The current all-or-nothing transform is basically OAEP: a two-round
202 ## Feistel network applied to a (possibly lopsided) block consisting of the
203 ## message and a random nonce. Showing that this is an AONT (in the
204 ## random-oracle model) is pretty easy.
205 hashsz = CFG.AUTHHASH().digest_size
206 assert len(m) <= hashsz
207 r = OS.urandom(hashsz)
214 Recover a message from an all-or-nothing transform C (as a binary string).
216 hashsz = CFG.AUTHHASH().digest_size
217 if not (hashsz <= len(c) <= 2*hashsz):
218 raise AuthenticationFailed, 'BADNONCE'
219 r, m = c[:hashsz], c[hashsz:]
224 def mint_token(user):
225 """Make and return a fresh token for USER."""
227 tag = auth_tag(sec, U.NOW, user)
228 return '%d.%s.%s' % (U.NOW, tag, user)
230 ## Long messages for reasons why one might have been redirected back to the
233 'AUTHFAIL': 'incorrect user name or password',
234 'NOAUTH': 'not authenticated',
235 'NONONCE': 'missing nonce',
236 'BADTOKEN': 'malformed token',
237 'BADTIME': 'invalid timestamp',
238 'BADNONCE': 'nonce mismatch',
239 'EXPIRED': 'session timed out',
240 'BADTAG': 'incorrect tag',
241 'NOUSER': 'unknown user name',
242 'LOGOUT': 'explicitly logged out',
246 class AuthenticationFailed (U.ExpectedError):
248 An authentication error. The most interesting extra feature is an
249 attribute `why' carrying a reason code, which can be looked up in
252 def __init__(me, why):
253 msg = LOGIN_REASONS[why]
254 U.ExpectedError.__init__(me, 403, msg)
257 def check_auth(token, nonce = None):
259 Check that the TOKEN is valid, comparing it against the NONCE if this is
262 If the token is OK, then return the correct user name, and set `NONCE' to a
263 new nonce for the next request. Otherwise raise an `AuthenticationFailed'
264 exception with an appropriate `why'.
269 ## If the token has been explicitly clobbered, then we're logged out.
270 if token == 'logged-out': raise AuthenticationFailed, 'LOGOUT'
273 bits = token.split('.', 3)
274 if len(bits) != 3: raise AuthenticationFailed, 'BADTOKEN'
275 stamp, tag, user = bits
277 ## Check the stamp, and find the right secret.
278 if not stamp.isdigit(): raise AuthenticationFailed, 'BADTIME'
280 sec = getsecret(when)
281 if sec is None: raise AuthenticationFailed, 'EXPIRED'
284 t = auth_tag(sec, when, user)
285 if t != tag: raise AuthenticationFailed, 'BADTAG'
287 ## Determine the correct CSRF tag.
288 ntag = csrf_tag(sec, when, user)
290 ## Check that the nonce matches, if one was supplied.
291 if nonce is not None:
292 gtag = aont_recover(unhack_octets(nonce))
293 if gtag != ntag: raise AuthenticationFailed, 'BADNONCE'
295 ## Make a new nonce string for use in forms.
296 NONCE = hack_octets(aont_transform(ntag))
298 ## Make sure the user still exists.
299 try: acct = S.SERVICES['master'].find(user)
300 except S.UnknownUser: raise AuthenticationFailed, 'NOUSER'
305 def bake_cookie(value):
307 Return a properly baked authentication-token cookie with the given VALUE.
309 return CGI.cookie('chpwd-token', value,
312 path = CFG.SCRIPT_NAME,
313 max_age = (CFG.SECRETLIFE - CFG.SECRETFRESH))
315 ###--------------------------------------------------------------------------
316 ### Authentication commands.
318 ## A dummy string, for when we're invoked from the command-line.
319 NONCE = '@DUMMY-NONCE'
322 'login', ['cgi-noauth'],
323 'Authenticate to the CGI machinery',
324 opts = [SC.Opt('why', '-w', '--why',
325 'Reason for redirection back to the login page.',
327 def cmd_login(why = None):
328 CGI.page('login.fhtml',
329 title = 'Chopwood: login',
330 why = LOGIN_REASONS.get(why, '<unknown error %s>' % why))
333 'auth', ['cgi-noauth'],
334 'Verify a user name and password',
335 params = [SC.Arg('u'), SC.Arg('pw')])
337 svc = S.SERVICES['master']
341 except (S.UnknownUser, S.IncorrectPassword):
342 CGI.redirect(CGI.action('login', why = 'AUTHFAIL'))
345 CGI.redirect(CGI.action('list', u),
346 set_cookie = bake_cookie(t))
348 ###----- That's all, folks --------------------------------------------------