catacomb/pwsafe.py: Split out the GDBM-specifics from StorageBackend.

[catacomb-python] / catacomb / pwsafe.py

### -*-python-*-
###
### Management of a secure password database
###
### (c) 2005 Straylight/Edgeware
###

###----- Licensing notice ---------------------------------------------------
###
### This file is part of the Python interface to Catacomb.
###
### Catacomb/Python is free software; you can redistribute it and/or modify
### it under the terms of the GNU General Public License as published by
### the Free Software Foundation; either version 2 of the License, or
### (at your option) any later version.
###
### Catacomb/Python 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 General Public License for more details.
###
### You should have received a copy of the GNU General Public License along
### with Catacomb/Python; if not, write to the Free Software Foundation,
### Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.

###--------------------------------------------------------------------------
### Imported modules.

from __future__ import with_statement

import catacomb as _C
import gdbm as _G

###--------------------------------------------------------------------------
### Underlying cryptography.

class DecryptError (Exception):
  """
  I represent a failure to decrypt a message.

  Usually this means that someone used the wrong key, though it can also
  mean that a ciphertext has been modified.
  """
  pass

class Crypto (object):
  """
  I represent a symmetric crypto transform.

  There's currently only one transform implemented, which is the obvious
  generic-composition construction: given a message m, and keys K0 and K1, we
  choose an IV v, and compute:

    * y = v || E(K0, v; m)
    * t = M(K1; y)

  The final ciphertext is t || y.
  """

  def __init__(me, c, h, m, ck, mk):
    """
    Initialize the Crypto object with a given algorithm selection and keys.

    We need a GCipher subclass C, a GHash subclass H, a GMAC subclass M, and
    keys CK and MK for C and M respectively.
    """
    me.c = c(ck)
    me.m = m(mk)
    me.h = h

  def encrypt(me, pt):
    """
    Encrypt the message PT and return the resulting ciphertext.
    """
    blksz = me.c.__class__.blksz
    b = _C.WriteBuffer()
    if blksz:
      iv = _C.rand.block(blksz)
      me.c.setiv(iv)
      b.put(iv)
    b.put(me.c.encrypt(pt))
    t = me.m().hash(b).done()
    return t + str(buffer(b))

  def decrypt(me, ct):
    """
    Decrypt the ciphertext CT, returning the plaintext.

    Raises DecryptError if anything goes wrong.
    """
    blksz = me.c.__class__.blksz
    tagsz = me.m.__class__.tagsz
    b = _C.ReadBuffer(ct)
    t = b.get(tagsz)
    h = me.m()
    if blksz:
      iv = b.get(blksz)
      me.c.setiv(iv)
      h.hash(iv)
    x = b.get(b.left)
    h.hash(x)
    if t != h.done(): raise DecryptError
    return me.c.decrypt(x)

class PPK (Crypto):
  """
  I represent a crypto transform whose keys are derived from a passphrase.

  The password is salted and hashed; the salt is available as the `salt'
  attribute.
  """

  def __init__(me, pp, c, h, m, salt = None):
    """
    Initialize the PPK object with a passphrase and algorithm selection.

    We want a passphrase PP, a GCipher subclass C, a GHash subclass H, a GMAC
    subclass M, and a SALT.  The SALT may be None, if we're generating new
    keys, indicating that a salt should be chosen randomly.
    """
    if not salt: salt = _C.rand.block(h.hashsz)
    tag = '%s\0%s' % (pp, salt)
    Crypto.__init__(me, c, h, m,
                    h().hash('cipher:' + tag).done(),
                    h().hash('mac:' + tag).done())
    me.salt = salt

###--------------------------------------------------------------------------
### Backend storage.

class StorageBackend (object):
  """
  I provide basic protocol for password storage backends.

  I'm an abstract class: you want one of my subclasses if you actually want
  to do something useful.

  Backends are responsible for storing and retrieving stuff, but not for the
  cryptographic details.  Backends need to store two kinds of information:

    * metadata, consisting of a number of property names and their values;
      and

    * password mappings, consisting of a number of binary labels and
      payloads.

  Backends need to implement the following ordinary methods.  See the calling
  methods for details of the subclass responsibilities.

  BE._create(FILE)      Create a new database in FILE; used by `create'.

  BE._open(FILE, WRITEP)
                        Open the existing database FILE; used by `open'.

  BE._close()           Close the database, freeing up any resources.

  BE._get_meta(NAME, DEFAULT)
                        Return the value of the metadata item with the given
                        NAME, or DEFAULT if it doesn't exist; used by
                        `get_meta'.

  BE._put_meta(NAME, VALUE)
                        Set the VALUE of the metadata item with the given
                        NAME, creating one if necessary; used by `put_meta'.

  BE._del_meta(NAME)    Forget the metadata item with the given NAME; raise
                        `KeyError' if there is no such item; used by
                        `del_meta'.

  BE._iter_meta()       Return an iterator over the metadata (NAME, VALUE)
                        pairs; used by `iter_meta'.

  BE._get_passwd(LABEL)
                        Return the password payload stored with the (binary)
                        LABEL; used by `get_passwd'.

  BE._put_passwd(LABEL, PAYLOAD)
                        Associate the (binary) PAYLOAD with the LABEL,
                        forgetting any previous payload for that LABEL; used
                        by `put_passwd'.

  BE._del_passwd(LABEL) Forget the password record with the given LABEL; used
                        by `_del_passwd'.

  BE._iter_passwds()    Return an iterator over the password (LABEL, PAYLOAD)
                        pairs; used by `iter_passwds'.
  """

  FAIL = ['FAIL']

  ## Life cycle methods.

  @classmethod
  def create(cls, file):
    """
    Create a new database in the named FILE, using this backend.

    Subclasses must implement the `_create' instance method.
    """
    return cls(writep = True, _magic = lambda me: me._create(file))

  def __init__(me, file = None, writep = False, _magic = None, *args, **kw):
    """
    Main constructor.

    Subclasses are not, in general, expected to override this: there's a
    somewhat hairy protocol between the constructor and some of the class
    methods.  Instead, the main hook for customization is the subclass's
    `_open' method, which is invoked in the usual case.
    """
    super(StorageBackend, me).__init__(*args, **kw)
    if _magic is not None: _magic(me)
    elif file is None: raise ValueError, 'missing file parameter'
    else: me._open(file, writep)
    me._writep = writep
    me._livep = True

  def close(me):
    """
    Close the database.

    It is harmless to attempt to close a database which has been closed
    already.  Calls the subclass's `_close' method.
    """
    if me._livep:
      me._livep = False
      me._close()

  ## Utilities.

  def _check_live(me):
    """Raise an error if the receiver has been closed."""
    if not me._livep: raise ValueError, 'database is closed'

  def _check_write(me):
    """Raise an error if the receiver is not open for writing."""
    me._check_live()
    if not me._writep: raise ValueError, 'database is read-only'

  def _check_meta_name(me, name):
    """
    Raise an error unless NAME is a valid name for a metadata item.

    Metadata names may not start with `$': such names are reserved for
    password storage.
    """
    if name.startswith('$'):
      raise ValueError, "invalid metadata key `%s'" % name

  ## Context protocol.

  def __enter__(me):
    """Context protocol: make sure the database is closed on exit."""
    return me
  def __exit__(me, exctype, excvalue, exctb):
    """Context protocol: see `__enter__'."""
    me.close()

  ## Metadata.

  def get_meta(me, name, default = FAIL):
    """
    Fetch the value for the metadata item NAME.

    If no such item exists, then return DEFAULT if that was set; otherwise
    raise a `KeyError'.

    This calls the subclass's `_get_meta' method, which should return the
    requested item or return the given DEFAULT value.  It may assume that the
    name is valid and the database is open.
    """
    me._check_meta_name(name)
    me._check_live()
    value = me._get_meta(name, default)
    if value is StorageBackend.FAIL: raise KeyError, name
    return value

  def put_meta(me, name, value):
    """
    Store VALUE in the metadata item called NAME.

    This calls the subclass's `_put_meta' method, which may assume that the
    name is valid and the database is open for writing.
    """
    me._check_meta_name(name)
    me._check_write()
    me._put_meta(name, value)

  def del_meta(me, name):
    """
    Forget about the metadata item with the given NAME.

    This calls the subclass's `_del_meta' method, which may assume that the
    name is valid and the database is open for writing.
    """
    me._check_meta_name(name)
    me._check_write()
    me._del_meta(name)

  def iter_meta(me):
    """
    Return an iterator over the name/value metadata items.

    This calls the subclass's `_iter_meta' method, which may assume that the
    database is open.
    """
    me._check_live()
    return me._iter_meta()

  def get_passwd(me, label):
    """
    Fetch and return the payload stored with the (opaque, binary) LABEL.

    If there is no such payload then raise `KeyError'.

    This calls the subclass's `_get_passwd' method, which may assume that the
    database is open.
    """
    me._check_live()
    return me._get_passwd(label)

  def put_passwd(me, label, payload):
    """
    Associate the (opaque, binary) PAYLOAD with the (opaque, binary) LABEL.

    Any previous payload for LABEL is forgotten.

    This calls the subclass's `_put_passwd' method, which may assume that the
    database is open for writing.
    """
    me._check_write()
    me._put_passwd(label, payload)

  def del_passwd(me, label):
    """
    Forget any PAYLOAD associated with the (opaque, binary) LABEL.

    If there is no such payload then raise `KeyError'.

    This calls the subclass's `_del_passwd' method, which may assume that the
    database is open for writing.
    """
    me._check_write()
    me._del_passwd(label, payload)

  def iter_passwds(me):
    """
    Return an iterator over the stored password label/payload pairs.

    This calls the subclass's `_iter_passwds' method, which may assume that
    the database is open.
    """
    me._check_live()
    return me._iter_passwds()

class GDBMStorageBackend (StorageBackend):
  """
  My instances store password data in a GDBM database.

  Metadata and password entries are mixed into the same database.  The key
  for a metadata item is simply its name; the key for a password entry is
  the entry's label prefixed by `$', since we're guaranteed that no
  metadata item name begins with `$'.
  """

  def _open(me, file, writep):
    try: me._db = _G.open(file, writep and 'w' or 'r')
    except _G.error, e: raise StorageBackendRefusal, e

  def _create(me, file):
    me._db = _G.open(file, 'n', 0600)

  def _close(me):
    me._db.close()
    me._db = None

  def _get_meta(me, name, default):
    try: return me._db[name]
    except KeyError: return default

  def _put_meta(me, name, value):
    me._db[name] = value

  def _del_meta(me, name):
    del me._db[name]

  def _iter_meta(me):
    k = me._db.firstkey()
    while k is not None:
      if not k.startswith('$'): yield k, me._db[k]
      k = me._db.nextkey(k)

  def _get_passwd(me, label):
    return me._db['$' + label]

  def _put_passwd(me, label, payload):
    me._db['$' + label] = payload

  def _del_passwd(me, label):
    del me._db['$' + label]

  def _iter_passwds(me):
    k = me._db.firstkey()
    while k is not None:
      if k.startswith('$'): yield k[1:], me._db[k]
      k = me._db.nextkey(k)

###--------------------------------------------------------------------------
### Password storage.

class PW (object):
  """
  I represent a secure (ish) password store.

  I can store short secrets, associated with textual names, in a way which
  doesn't leak too much information about them.

  I implement (some of) the Python mapping protocol.

  I keep track of everything using a StorageBackend object.  This contains
  password entries, identified by cryptographic labels, and a number of
  metadata items.

  cipher        Names the Catacomb cipher selected.

  hash          Names the Catacomb hash function selected.

  key           Cipher and MAC keys, each prefixed by a 16-bit big-endian
                length and concatenated, encrypted using the master
                passphrase.

  mac           Names the Catacomb message authentication code selected.

  magic         A magic string for obscuring password tag names.

  salt          The salt for hashing the passphrase.

  tag           The master passphrase's tag, for the Pixie's benefit.

  Password entries are assigned labels of the form `$' || H(MAGIC || TAG);
  the corresponding value consists of a pair (TAG, PASSWD), prefixed with
  16-bit lengths, concatenated, padded to a multiple of 256 octets, and
  encrypted using the stored keys.
  """

  def __init__(me, file, writep = False):
    """
    Initialize a PW object from the database in FILE.

    If WRITEP is false (the default) then the database is opened read-only;
    if true then it may be written.  Requests the database password from the
    Pixie, which may cause interaction.
    """

    ## Open the database.
    me.db = GDBMStorageBackend(file, writep)

    ## Find out what crypto to use.
    c = _C.gcciphers[me.db.get_meta('cipher')]
    h = _C.gchashes[me.db.get_meta('hash')]
    m = _C.gcmacs[me.db.get_meta('mac')]

    ## Request the passphrase and extract the master keys.
    tag = me.db.get_meta('tag')
    ppk = PPK(_C.ppread(tag), c, h, m, me.db.get_meta('salt'))
    try:
      b = _C.ReadBuffer(ppk.decrypt(me.db.get_meta('key')))
    except DecryptError:
      _C.ppcancel(tag)
      raise
    me.ck = b.getblk16()
    me.mk = b.getblk16()
    if not b.endp: raise ValueError, 'trailing junk'

    ## Set the key, and stash it and the tag-hashing secret.
    me.k = Crypto(c, h, m, me.ck, me.mk)
    me.magic = me.k.decrypt(me.db.get_meta('magic'))

  @classmethod
  def create(cls, file, tag, c, h, m):
    """
    Create and initialize a new database FILE.

    We want a GCipher subclass C, a GHash subclass H, and a GMAC subclass M;
    and a Pixie passphrase TAG.

    This doesn't return a working object: it just creates the database file
    and gets out of the way.
    """

    ## Set up the cryptography.
    pp = _C.ppread(tag, _C.PMODE_VERIFY)
    ppk = PPK(pp, c, h, m)
    ck = _C.rand.block(c.keysz.default)
    mk = _C.rand.block(c.keysz.default)
    k = Crypto(c, h, m, ck, mk)

    ## Set up and initialize the database.
    kct = ppk.encrypt(_C.WriteBuffer().putblk16(ck).putblk16(mk))
    with GDBM.StorageBackend.create(file) as db:
      db.put_meta('tag', tag)
      db.put_meta('salt', ppk.salt)
      db.put_meta('cipher', c.name)
      db.put_meta('hash', h.name)
      db.put_meta('mac', m.name)
      db.put_meta('key', kct)
      db.put_meta('magic', k.encrypt(_C.rand.block(h.hashsz)))

  def keyxform(me, key):
    """Transform the KEY (actually a password tag) into a password label."""
    return me.k.h().hash(me.magic).hash(key).done()

  def changepp(me):
    """
    Change the database password.

    Requests the new password from the Pixie, which will probably cause
    interaction.
    """
    tag = me.db.get_meta('tag')
    _C.ppcancel(tag)
    ppk = PPK(_C.ppread(tag, _C.PMODE_VERIFY),
              me.k.c.__class__, me.k.h, me.k.m.__class__)
    kct = ppk.encrypt(_C.WriteBuffer().putblk16(me.ck).putblk16(me.mk))
    me.db.put_meta('key', kct)
    me.db.put_meta('salt', ppk.salt)

  def pack(me, key, value):
    """Pack the KEY and VALUE into a ciphertext, and return it."""
    b = _C.WriteBuffer()
    b.putblk16(key).putblk16(value)
    b.zero(((b.size + 255) & ~255) - b.size)
    return me.k.encrypt(b)

  def unpack(me, ct):
    """
    Unpack a ciphertext CT and return a (KEY, VALUE) pair.

    Might raise DecryptError, of course.
    """
    b = _C.ReadBuffer(me.k.decrypt(ct))
    key = b.getblk16()
    value = b.getblk16()
    return key, value

  ## Mapping protocol.

  def __getitem__(me, key):
    """Return the password for the given KEY."""
    try: return me.unpack(me.db.get_passwd(me.keyxform(key)))[1]
    except KeyError: raise KeyError, key

  def __setitem__(me, key, value):
    """Associate the password VALUE with the KEY."""
    me.db.put_passwd(me.keyxform(key), me.pack(key, value))

  def __delitem__(me, key):
    """Forget all about the KEY."""
    try: me.db.del_passwd(me.keyxform(key))
    except KeyError: raise KeyError, key

  def __iter__(me):
    """Iterate over the known password tags."""
    for _, pld in me.db.iter_passwds():
      yield me.unpack(pld)[0]

  ## Context protocol.

  def __enter__(me):
    return me
  def __exit__(me, excty, excval, exctb):
    me.db.close()

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