backend.py: Use configured delimiter for joining fields.

[chopwood] / httpauth.py

### -*-python-*-
###
### HTTP authentication
###
### (c) 2013 Mark Wooding
###

###----- Licensing notice ---------------------------------------------------
###
### This file is part of Chopwood: a password-changing service.
###
### Chopwood is free software; you can redistribute it and/or modify
### it under the terms of the GNU Affero General Public License as
### published by the Free Software Foundation; either version 3 of the
### License, or (at your option) any later version.
###
### Chopwood is distributed in the hope that it will be useful,
### but WITHOUT ANY WARRANTY; without even the implied warranty of
### MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
### GNU Affero General Public License for more details.
###
### You should have received a copy of the GNU Affero General Public
### License along with Chopwood; if not, see
### <http://www.gnu.org/licenses/>.

from __future__ import with_statement

import base64 as BN
import hashlib as H
import hmac as HM
import itertools as I
import os as OS

import cgi as CGI
import config as CONF; CFG = CONF.CFG
import dbmaint as D
import output as O; PRINT = O.PRINT
import service as S
import subcommand as SC
import util as U

###--------------------------------------------------------------------------
### About the authentication scheme.
###
### We mustn't allow a CGI user to make changes (or even learn about a user's
### accounts) without authenticating first.  Curently, that means a username
### and password, though I really dislike this; maybe I'll add a feature for
### handling TLS client certificates some time.
###
### We're particularly worried about cross-site request forgery: a forged
### request to change a password to some known value lets a bad guy straight
### into a restricted service -- and a change to the `master' account lets
### him into all of them.
###
### Once we've satisfied ourselves of the user's credentials, we issue a
### short-lived session token, stored in a cookie namde `chpwd-token'.  This
### token has the form `DATE.TAG.USER': here, DATE is the POSIX time of
### issue, as a decimal number; USER is the user's login name; and TAG is a
### cryptographic MAC tag on the string `chpwd-token.DATE.USER'.  (The USER
### name is on the end so that it can contain `.' characters without
### introducing parsing difficulties.)
###
### Secrets for these MAC tags are stored in the database: secrets expire
### after 30 minutes (invalidating all tokens issued with them); we only
### issue a token with a secret that's at most five minutes old.  A session's
### lifetime, then, is somewhere between 25 and 30 minutes.  We choose the
### lower bound as the cookie lifetime, just so that error messages end up
### consistent.
###
### A cookie with a valid token is sufficient to grant read-only access to a
### user's account details.  However, this authority is ambient: during the
### validity period of the token, a cross-site request forgery can easily
### succeed, since there's nothing about the rest of a request which is hard
### to forge, and the cookie will be supplied automatically by the user
### agent.  Showing the user some information we were quite happy to release
### anyway isn't an interesting attack, but we must certainly require
### something stronger for state-change requests.  Here, we also check a
### special request parameter `%nonce': forms setting up a `POST' action must
### include an appropriate hidden input element.
###
### The `%nonce' parameter encodes a randomized `all-or-nothing transform' of
### the (deterministic) MAC tag on `chpwd-nonce.DATE.USER'.  The standard
### advice for defeating the BREACH attack (which uses differential
### compression of HTTP payloads which include attacker-provided data to
### recover CSRF tokens) is to transmit an XOR-split of the token; but that
### allows an adversary to recover the token two bytes at a time; this makes
### the attack take 256 times longer, which doesn't really seem enough.  A
### proper AONT, on the other hand, means that the adversary gets nothing if
### he can't guess the entire transformed token -- and if he could do that,
### he might as well just carry out the CSRF attack without messing with
### BREACH in the first place.
###
### Messing about with cookies is a bit annoying, but it's hard to come up
### with alternatives.  I'm trying to keep the URLs fairly pretty, and anyway
### putting secrets into them is asking for trouble, since user agents have
### an awful tendecy to store URLs in a history database, send them to
### motherships, leak them in `Referer' headers, and other awful things.  Our
### cookie is marked `HttpOnly' so, in particular, user agents must keep them
### out of the grubby mitts of Javascript programs.
###
### I promise that I'm only using these cookies for the purposes of
### maintaining security: I don't log them or do anything else at all with
### them.

###--------------------------------------------------------------------------
### Generating and checking authentication tokens.

## Secret lifetime parameters.
CONF.DEFAULTS.update(

  ## The lifetime of a session cookie, in seconds.
  SECRETLIFE = 30*60,

  ## Maximum age of an authentication key, in seconds.
  SECRETFRESH = 5*60,

  ## Hash function to use for crypto.
  AUTHHASH = H.sha256)

def cleansecrets():
  """Remove dead secrets from the database."""
  with D.DB:
    D.DB.execute("DELETE FROM secrets WHERE stamp < $stale",
                 stale = U.NOW - CFG.SECRETLIFE)

def getsecret(when):
  """
  Return the newest and most shiny secret no older than WHEN.

  If there is no such secret, or the only one available would have been stale
  at WHEN, then return `None'.
  """
  cleansecrets()
  with D.DB:
    D.DB.execute("""SELECT stamp, secret FROM secrets
                    WHERE stamp <= $when
                    ORDER BY stamp DESC""",
               when = when)
    row = D.DB.fetchone()
    if row is None: return None
    if row[0] < when - CFG.SECRETFRESH: return None
    return row[1].decode('base64')

def freshsecret():
  """Return a fresh secret."""
  cleansecrets()
  with D.DB:
    D.DB.execute("""SELECT secret FROM secrets
                    WHERE stamp >= $fresh
                    ORDER BY stamp DESC""",
                 fresh = U.NOW - CFG.SECRETFRESH)
    row = D.DB.fetchone()
    if row is not None:
      sec = row[0].decode('base64')
    else:
      sec = OS.urandom(16)
      D.DB.execute("""INSERT INTO secrets(stamp, secret)
                      VALUES ($stamp, $secret)""",
                   stamp = U.NOW, secret = sec.encode('base64'))
    return sec

def hack_octets(s):
  """Return the octet string S, in a vaguely pretty form."""
  return BN.b64encode(s, '+$').rstrip('=')

def unhack_octets(s):
  """Reverse the operation done by `hack_octets'."""
  pad = (len(s) + 3)&3 - len(s)
  try:
    return BN.b64decode(s + '='*pad, '+$')
  except TypeError:
    raise AuthenticationFailed, 'BADNONCE'

def auth_tag(sec, stamp, user):
  """Compute a tag using secret SEC on `STAMP.USER'."""
  hmac = HM.HMAC(sec, digestmod = CFG.AUTHHASH)
  hmac.update('chpwd-token.%d.%s' % (stamp, user))
  return hack_octets(hmac.digest())

def csrf_tag(sec, stamp, user):
  """Compute a tag using secret SEC on `STAMP.USER'."""
  hmac = HM.HMAC(sec, digestmod = CFG.AUTHHASH)
  hmac.update('chpwd-nonce.%d.%s' % (stamp, user))
  return hmac.digest()

def xor_strings(x, y):
  """Return the bitwise XOR of two octet strings."""
  return ''.join(chr(ord(xc) ^ ord(yc)) for xc, yc in I.izip(x, y))

def aont_step(x, y):
  """Perform a step of the OAEP-based all-or-nothing transform."""
  return xor_strings(y, CFG.AUTHHASH(x).digest())

def aont_transform(m):
  """
  Apply an all-or-nothing transform to a (short, binary) message M.

  The result is returned as a binary string.
  """

  ## The current all-or-nothing transform is basically OAEP: a two-round
  ## Feistel network applied to a (possibly lopsided) block consisting of the
  ## message and a random nonce.  Showing that this is an AONT (in the
  ## random-oracle model) is pretty easy.
  hashsz = CFG.AUTHHASH().digest_size
  assert len(m) <= hashsz
  r = OS.urandom(hashsz)
  m = aont_step(r, m)
  r = aont_step(m, r)
  return r + m

def aont_recover(c):
  """
  Recover a message from an all-or-nothing transform C (as a binary string).
  """
  hashsz = CFG.AUTHHASH().digest_size
  if not (hashsz <= len(c) <= 2*hashsz):
    raise AuthenticationFailed, 'BADNONCE'
  r, m = c[:hashsz], c[hashsz:]
  r = aont_step(m, r)
  m = aont_step(r, m)
  return m

def mint_token(user):
  """Make and return a fresh token for USER."""
  sec = freshsecret()
  tag = auth_tag(sec, U.NOW, user)
  return '%d.%s.%s' % (U.NOW, tag, user)

## Long messages for reasons why one might have been redirected back to the
## login page.
LOGIN_REASONS = {
  'AUTHFAIL': 'Incorrect user name or password',
  'NOAUTH': 'Not authenticated',
  'NONONCE': 'Missing nonce',
  'BADTOKEN': 'Malformed token',
  'BADTIME': 'Invalid timestamp',
  'BADNONCE': 'Nonce mismatch',
  'EXPIRED': 'Session timed out',
  'BADTAG': 'Incorrect tag',
  'NOUSER': 'Unknown user name',
  'LOGOUT': 'Explicitly logged out',
  None: None
}

class AuthenticationFailed (U.ExpectedError):
  """
  An authentication error.  The most interesting extra feature is an
  attribute `why' carrying a reason code, which can be looked up in
  `LOGIN_REASONS'.
  """
  def __init__(me, why):
    msg = LOGIN_REASONS[why]
    U.ExpectedError.__init__(me, 403, msg)
    me.why = why

def check_auth(token, nonce = None):
  """
  Check that the TOKEN is valid, comparing it against the NONCE if this is
  not `None'.

  If the token is OK, then return the correct user name, and set `NONCE' to a
  new nonce for the next request.  Otherwise raise an `AuthenticationFailed'
  exception with an appropriate `why'.
  """

  global NONCE

  ## If the token has been explicitly clobbered, then we're logged out.
  if token == 'logged-out': raise AuthenticationFailed, 'LOGOUT'

  ## Parse the token.
  bits = token.split('.', 3)
  if len(bits) != 3: raise AuthenticationFailed, 'BADTOKEN'
  stamp, tag, user = bits

  ## Check the stamp, and find the right secret.
  if not stamp.isdigit(): raise AuthenticationFailed, 'BADTIME'
  when = int(stamp)
  sec = getsecret(when)
  if sec is None: raise AuthenticationFailed, 'EXPIRED'

  ## Check the tag.
  t = auth_tag(sec, when, user)
  if t != tag: raise AuthenticationFailed, 'BADTAG'

  ## Determine the correct CSRF tag.
  ntag = csrf_tag(sec, when, user)

  ## Check that the nonce matches, if one was supplied.
  if nonce is not None:
    gtag = aont_recover(unhack_octets(nonce))
    if gtag != ntag: raise AuthenticationFailed, 'BADNONCE'

  ## Make a new nonce string for use in forms.
  NONCE = hack_octets(aont_transform(ntag))

  ## Make sure the user still exists.
  try: acct = S.SERVICES['master'].find(user)
  except S.UnknownUser: raise AuthenticationFailed, 'NOUSER'

  ## Done.
  return user

def bake_cookie(value):
  """
  Return a properly baked authentication-token cookie with the given VALUE.
  """
  return CGI.cookie('chpwd-token', value,
                    httponly = True,
                    secure = CGI.SSLP,
                    path = CFG.SCRIPT_NAME,
                    max_age = (CFG.SECRETLIFE - CFG.SECRETFRESH))

###--------------------------------------------------------------------------
### Authentication commands.

## A dummy string, for when we're invoked from the command-line.
NONCE = '@DUMMY-NONCE'

@CGI.subcommand(
  'login', ['cgi-noauth'],
  'Authenticate to the CGI machinery',
  opts = [SC.Opt('why', '-w', '--why',
                 'Reason for redirection back to the login page.',
                 argname = 'WHY')])
def cmd_login(why = None):
  CGI.page('login.fhtml',
           title = 'Chopwood: login',
           why = LOGIN_REASONS.get(why, '<unknown error %s>' % why))

@CGI.subcommand(
  'auth', ['cgi-noauth'],
  'Verify a user name and password',
  methods = ['POST'],
  params = [SC.Arg('u'), SC.Arg('pw')])
def cmd_auth(u, pw):
  svc = S.SERVICES['master']
  try:
    acct = svc.find(u)
    acct.check(pw)
  except (S.UnknownUser, S.IncorrectPassword):
    CGI.redirect(CGI.action('login', why = 'AUTHFAIL'))
  else:
    t = mint_token(u)
    CGI.redirect(CGI.action('list', u),
                 set_cookie = bake_cookie(t))

###----- That's all, folks --------------------------------------------------