httpauth.py: Allow configuration of the hash function.

[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 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.NONCE.TAG.USER': here, DATE is the POSIX time of
### issue, as a decimal number; NONCE is a randomly chosen string, encoded in
### base64, USER is the user's login name, and TAG is a cryptographic MAC tag
### on the string `DATE.NONCE.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 that a
### special request parameter `%nonce' matches the token's NONCE field: forms
### setting up a `POST' action must include an appropriate hidden input
### element.
###
### 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('=') \
           .replace('/', '$')

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

def mint_token(user):
  """Make and return a fresh token for USER."""
  sec = freshsecret()
  nonce = hack_octets(OS.urandom(16))
  tag = auth_tag(sec, U.NOW, nonce, user)
  return '%d.%s.%s.%s' % (U.NOW, nonce, 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' set
  to the appropriate portion of the token.  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) != 4: raise AuthenticationFailed, 'BADTOKEN'
  stamp, NONCE, tag, user = bits

  ## Check that the nonce matches, if one was supplied.
  if nonce is not None and nonce != NONCE:
    raise AuthenticationFailed, 'BADNONCE'

  ## 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, NONCE, user)
  if t != tag: raise AuthenticationFailed, 'BADTAG'

  ## 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',
  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 --------------------------------------------------