Documentation

How it works

Passwords itself is basically a database frontend with the abilities to add, delete, modify and retrieve entries to/from this database. The de- and encryption is done by some other program which can be specified in the configuration file.

When passwords starts up it reads the database into memory before it can look up an entry, add a new one, modify an existing one or delete an entry. The encrypted database is filtered through the decryption program as can be seen on the picture to the left.

The decryption program to use is configured in passwords configuration file and it can contain any shell construct because it is given literally as the argument to the "sh -c" command. It is however important that the decryption program must read the encrypted data from standard input and write the cleartext to standard output, which is then read by passwords. If you start passwords for the first time it creates a configuration file for you with the default command "cat" used for both de- and encryption. This totally insecure default was choosen only because password can not know what cryptography tools may be available on your system and this default is guaranteed to "work" on any system. You should really change this!

If the database has been changed (e.g. a new entry was added or an existing one has been modified) the updated database must be stored on disk. Prior to being written to disk it is filtered through the encryption program just like described above but in the other direction (see picture to the right). The encryption program must read the cleartext from standard input and write the encrypted data to standard output, which is redirected to a temporary disk file.

If the encryption went well, i.e. the command returned with an successful exit value, the original database file is overwritten with zero data in order to avoid leaving portions of the database file scattered throughout the disk in the freed blocks. Then the database file is removed and the temporary file is renamed to the name of the database file.

The recommended way to use this software is in concert with GnuPG. You should set up a keypair prior to using passwords if you have not already done so. See the Links section for pointers to instructions on how to do this. There you will also find links to alternative encryption and password storage tools. If you have generated a keypair with GnuPG you can find the recommended configuration settings for passwords in the man page under the section entitled EXAMPLES. If you have any further questions or comments regarding passwords please direct them to the author Matthias Czapla (dermatsch@gmx.de).