-# -*-python-*-
+### -*-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
-import struct as _S
+
+###--------------------------------------------------------------------------
+### 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):
- if me.c.__class__.blksz:
- iv = _C.rand.block(me.c.__class__.blksz)
+ """
+ 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)
- else:
- iv = ''
- y = iv + me.c.encrypt(pt)
- t = me.m().hash(y).done()
- return t + y
+ b.put(iv)
+ b.put(me.c.encrypt(pt))
+ t = me.m().hash(b).done()
+ return t + str(buffer(b))
+
def decrypt(me, ct):
- t = ct[:me.m.__class__.tagsz]
- y = ct[me.m.__class__.tagsz:]
- if t != me.m().hash(y).done():
- raise DecryptError
- iv = y[:me.c.__class__.blksz]
- if me.c.__class__.blksz: me.c.setiv(iv)
- return me.c.decrypt(y[me.c.__class__.blksz:])
+ """
+ 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())
+ h().hash('cipher:' + tag).done(),
+ h().hash('mac:' + tag).done())
me.salt = salt
-class Buffer (object):
- def __init__(me, s):
- me.str = s
- me.i = 0
- def get(me, n):
- i = me.i
- if n + i > len(me.str):
- raise IndexError, 'buffer underflow'
- me.i += n
- return me.str[i:i + n]
- def getbyte(me):
- return ord(me.get(1))
- def unpack(me, fmt):
- return _S.unpack(fmt, me.get(_S.calcsize(fmt)))
- def getstring(me):
- return me.get(me.unpack('>H')[0])
- def checkend(me):
- if me.i != len(me.str):
- raise ValueError, 'junk at end of buffer'
-
-def _wrapstr(s):
- return _S.pack('>H', len(s)) + s
-
-class PWIter (object):
- def __init__(me, pw):
- me.pw = pw
- me.k = me.pw.db.firstkey()
- def next(me):
- k = me.k
- while True:
- if k is None:
- raise StopIteration
- if k[0] == '$':
- break
- k = me.pw.db.nextkey(k)
- me.k = me.pw.db.nextkey(k)
- return me.pw.unpack(me.pw.db[k])[0]
+###--------------------------------------------------------------------------
+### 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):
- def __init__(me, file, mode = 'r'):
- me.db = _G.open(file, mode)
- c = _C.gcciphers[me.db['cipher']]
- h = _C.gchashes[me.db['hash']]
- m = _C.gcmacs[me.db['mac']]
- tag = me.db['tag']
- ppk = PPK(_C.ppread(tag), c, h, m, me.db['salt'])
+ """
+ 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:
- buf = Buffer(ppk.decrypt(me.db['key']))
+ b = _C.ReadBuffer(ppk.decrypt(me.db.get_meta('key')))
except DecryptError:
_C.ppcancel(tag)
raise
- me.ck = buf.getstring()
- me.mk = buf.getstring()
- buf.checkend()
+ 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['magic'])
+ 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):
- return '$' + me.k.h().hash(me.magic).hash(key).done()
+ """Transform the KEY (actually a password tag) into a password label."""
+ return me.k.h().hash(me.magic).hash(key).done()
+
def changepp(me):
- tag = me.db['tag']
+ """
+ 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__)
- me.db['key'] = ppk.encrypt(_wrapstr(me.ck) + _wrapstr(me.mk))
- me.db['salt'] = ppk.salt
+ 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):
- w = _wrapstr(key) + _wrapstr(value)
- pl = (len(w) + 255) & ~255
- w += '\0' * (pl - len(w))
- return me.k.encrypt(w)
- def unpack(me, p):
- buf = Buffer(me.k.decrypt(p))
- key = buf.getstring()
- value = buf.getstring()
+ """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):
- try:
- return me.unpack(me.db[me.keyxform(key)])[1]
- except KeyError:
- raise KeyError, 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):
- me.db[me.keyxform(key)] = me.pack(key, value)
+ """Associate the password VALUE with the KEY."""
+ me.db.put_passwd(me.keyxform(key), me.pack(key, value))
+
def __delitem__(me, key):
- try:
- del me.db[me.keyxform(key)]
- except KeyError:
- raise KeyError, key
+ """Forget all about the KEY."""
+ try: me.db.del_passwd(me.keyxform(key))
+ except KeyError: raise KeyError, key
+
def __iter__(me):
- return PWIter(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 --------------------------------------------------
~mdw / catacomb-python / blobdiff