Introduction
pwdb is a command-line-based password manager, designed to work well
when the password database is stored in a version control system.
In order to do this, it stores each account's details in a separate
file. Other password managers tend to store everything in a single
encrypted database file; if you add two different accounts from two
different machines, then the resulting commits will conflict on a
binary file, requiring some level of manual work to merge them!
Other interesting features include:
* Accounts have an arbitrary number of key=value fields, to support
things like credit cards as well as traditional username/password
accounts.
* Any of those fields may be marked as "obscured", meaning pwdb
never displays them onscreen unless you force it to.
* Highly scriptable.
* Support for generating new accounts from configurable templates.
* Support for arbitrarily nested encryption, requiring extra
authentication to access more sensitive accounts' details.
Getting Started
Install pwdb by installing Chicken Scheme, then running:
chicken-install pwdb
Go to the directory where you'll store your password files.
Set up a basic template:
echo '(account (url "FIXME") (username "FIXME") (password ,(make-passphrase) obscured))' | pwdb -n TEMPLATE.pwdb
You'll be prompted for a new passphrase; enter it twice. This will be
used to encrypt all your accounts (by default), because it's used to
encrypt the template.
Now create a new account from that template:
pwdb -ne Amazon.pwdb TEMPLATE.pwdb
You'll be prompted for the passphrase to decrypt the template, then an
editor (your choice in $EDITOR) will pop up with the template for you
to edit (with a random passphrase generated for you). When you save
it, the same passphrase you used to decrypt the template will be used
to encrypt the new account file.
To look at an account, do this:
pwdb Amazon.pwdb
You'll see that anything marked "obscured" isn't displayed (unless
you add the -a flag to the command line).
You can pull out a specific field, which is handy in scripts:
pwdb Amazon.pwdb url
If you specify -a, you can even pull out obscured fields. A
good trick is:
pwdb -a Amazon.pwdb password | xclip
If you've installed xclip, that will put your Amazon password in your
X selection buffer, so a middle-click in that password box will paste
it for you. However, it'll be left in the selection buffer afterwards,
so a better idea is;
pwdb -i xclip Amazon.pwdb
That will list the un-obscured fields, and then prompt you for a
number. If you enter the number of the password field, it will pipe
the password into xclip for you to paste. But when you enter
q to quit interactive mode, it'll clear the selection buffer
for you by feeding an empty string to xclip.
If you want to edit an account:
pwdb -e Amazon.pwdb
That won't show you the contents of obscured fields, but you can add,
remove, or change obscured fields - any field left as
<obscured> will just pick up the value it had
originally; if you replace <obscured> with "Secret
Password" then the obscured field will be changed!
Or you can do:
pwdb -ea Amazon.pwdb
...to edit the entire account, obscured fields and all.
Multi-layer encryption
Let's make a template for bank cards, which requires an additional
passphrase for extra security. Don't think of that in terms of "more
encryption is harder to brute-force"; think of it in terms of "the
passphrase you enter a few times a day to get into social networking
web-sites isn't enough to also get your credit card numbers".
echo '(account (card-number "FIXME") (expiry "FIXME") (cvv "FIXME" obscured) (pin "FIXME" obscured))' | pwdb -n BANK-CARDS-TEMPLATE.pwdb cards
Note that as well as changing the template layout, we've added an
extra argument to pwdb: "cards". This is a tag we
have chosen to name the extra passphrase.
When creating the template account, pwdb will now ask us for the usual
passphrase, and also a passphrase "for cards". Use something different
for this one!
The storage format for pwdb files is always encrypted by the "general"
passphrase, but if additional passphrases are used, then they are
layered; only after undoing the outer "general" encryption will pwdb
even know that the contents are further encrypted, and with what
passphrase. So when you use that template, you will be prompted for
the normal passphrase, then you'll be prompted for the passphrase "for
cards"; only when both are entered correctly will pwdb be able to read
the actual template within; and that encryption setup is inherited by
accounts created from this template.
Templates
Templates aren't special - they're just pwdb files like any other, and
you can use any pwdb file as a template to create another. However,
when a template is used to create a new pwdb file, some special field
values cause the random generation of passwords and passphrases:
,(make-passphrase)
...creates a passphrase from four random Lojban gismu words.
,(make-password LEN)
...creates a random password of LEN random characters, chosen from a
hardcoded reasonable set (avoiding easy-to-confuse symbols such as
0OoIl).
Scripting
pwdb won't prompt for a passphrase if it finds it in the
environment. Set the environment variable PWDB to your
passphrase, and PWDB_..tag... (eg, PWDB_cards) for a
multi-layer encryption tag passphrase, to avoid being prompted for
them. This is handy when scripting bulk operations over all your
accounts, but be careful of who else is running code on your
machine...
Command Reference
pwdb -n NEW-FILENAME [TAGS...]
Creates a new pwdb file from an account sexpression on standard
input. If TAGS... are given, then they're the passphrase-tags
for extra layers of encryption, from outermost to innermost.
pwdb -ne NEW-FILENAME TEMPLATE-FILENAME
Reads a file to use as a template, expands any ,(...)
commands in it, asks the user to edit it with $EDITOR, then
saves it to the new filename (with the same encryption keys as the
template).
pwdb [-a] FILENAME
Displays the account on stdout; unless -a is specified,
fields marked as obscured will have their values obscured.
pwdb [-a] FILENAME FIELD...
Dumps the values of the named fields to stdout, one per line; unless
-a is specified, fields marked as obscured will have their
values obscured.
pwdb -e [-a] FILENAME
Opens up the specified account in $EDITOR; unless -a
is specified, fields marked as obscured will have their values
obscured in the editable text, and any obscured fields in the saved
text will have their values filled in from the same-named fields in
the original account data. This means that if you deleted obscured
fields, or add new ones or edit existing ones to have values, those
values will be saved to the new account.
Account sexpr format
An account is stored like so:
(account (KEY "VALUE" [OPTIONS...])...)
Options can either be a bare symbol, or a property of the form
(KEY "VALUE").
The only supported option at this time is obscured, which
marks the field so that its value is not displayed by default.
Bugs
* Doesn't use a proper key derivation function; the key is just
based on the SHA hash of the passphrase entered, which makes it
easier to brute-force.
* Doesn't make any effort to prevent plaintext or keys from being
swapped out and all that.
* No easy way to re-encrypt a file to change the passphrase (but it
can be easily added).
* Not enough configurability for password/passphrase generation.
* sexpr format exposed by -e (edit) and -n
(create new) commands is ugly when formatted all onto one line by
pp.
* When dumping specified named fields to stdout, any that are
missing in the account will just be skipped, and a script has no
way of knowing which one(s) were skipped.