PASSWORDS(1) PASSWORDS(1) NAME passwords - store and retrieve passwords SYNOPSIS passwords [-hilv] [-s sep] [name] passwords [-i] -a|-m [-u user] [-p pass] [-c comm] name passwords [-i] -d name DESCRIPTION Passwords allows the storage and retrieval of passwords and additional data in a single secure database. The encryption method is completely configurable because pass­ words does not do this itself. Instead the cleartext database is filtered through an external application (e.g. GnuPG) for encryption. Therefore it is recommended that you set up GnuPG and generate a keypair prior to using passwords if you have not already done so. See section SEE ALSO for pointers to instructions on how to do this. Each database entry consists of the following fields: a unique name for the entry, an optional user name, optional password and optional comment. There is no imposed limit on the length or the allowable characters of any field. If Passwords is invoked without the option -i it performs one of four possible operations and then exits. The option -i causes passwords to enter interactive mode after performing any of the operations specified on the command line (see section INTERACTIVE MODE below for more informa­ tion on it). The four possibilities on the command line are show, add, modify or delete. If none of the options -a, -m or -d is specified, passwords retrieves (shows) the password of the entry with the given name. If the name is omited passwords dumps the complete database. The option -l produces a long listing format with the fields name, user, password and comment printed in this order. The fields are separated by the string " : ", which can be changed in the configuration file and with the -s option. The option -a can be used to add a new entry with the given name. You can specify a user name, password and comment with the -u, -p and -c options respectively. It is an error if an entry with this name already exists. Similarly the -m option allows you to modify the user name, password and comment of the entry with the given name. It is an error if no entry with this name exists. The -d option deletes the entry with the given name from the database. OPTIONS -a Add a new entry to th database. -c comm The comment field for add and modify mode. -d Delete the entry from the database. -h Display a short help message. -i Enter interactive mode (see below) possibly after performing any operations specified on the command line. -l Use a long listing format for show mode. -m Modify existing entry. -p pass The password field for add and modify mode. -s sep Use this string as the separator between the fields in show mode. -u user The user field for add and modify mode. -V Display version information. -v Be verbose; Produces lots of output about what is going on. Mainly useful for debugging. INTERACTIVE MODE If passwords has been invoked with the option -i it enters interactive mode after performing the operation specified on the command line, if any. In interactive mode pass­ words displays a prompt and waits for the user to input commands. Passwords uses the GNU Readline library for command line editing so all the usual convenient features (like command line history and Emacs-style key bindings) are available. To include whitespace characters in an argument to any of the commands described below, they must be surrounded by double quotes. To include a double quote character in a quoted string, precede it with a backslash. The possible commands are: show [-e command] [name] Show the entry with the specified name or all entries if no name is specified. The option -e specifies an external command to pipe the output through. This is useful for example to grep for a specific entry or view the output with a pager pro­ gram. Any valid shell construct is possible. Note that the show command always uses the long listing format. add [-u user] [-p pass] [-c comm] name Add an entry with the given name to the database. The options -u, -p and -c specify the user name, password and comment for the entry respectively. modify [-u user] [-p pass] [-c comm] name Modify the the entry with the given name which must already exist. The options have the same meaning as described above for the add command. delete name Delete the the entry with the given name from the database. quit Exit the program, writing the updated database to disk if it has been modified during this session. exit Exit the program but do not write the changes to disk. The database will remain in the state it was in before passwords was invoked. help Print a short summary of the available commands. Finally note that all commands can be abbreviated to the smallest unambiguous string. Currently this means that it is enough to type the first character of a command because they all start with a different one. SECURITY The memory used for the cleartext data is overwritten with zero data on exit. During encryption the data is written to a temporary file and only if everything went well, the old database file is overwritten with zero data and then removed. Finally the temporary file is renamed to the name of the database file. The newly written database file is always created with mode 0600. If the database does not contain an entry (i.e. it is empty) nothing is written to disk and the old database file is removed after having been overwritten with zero data. If your shell supports a command line history it is recom­ mended that you remove any typed command line containing sensitive data from this history immediately afterwards. For the bash shell typing the key combinations Ctrl-P, Ctrl-U, Ctrl-N one after another should do this. After you have been reminded about the password you should clear the screen by typing Ctrl-L if you are not the only one who can watch your terminal. If your terminal provides a scrollback buffer you should also take appropriate mea­ sures to make any sensitive information that may be pre­ sent there unavailable. CONFIGURATION Passwords stores its configuration file and the database in a directory named ".passwords" in the users home direc­ tory. The configuration file is a simple text file named "options" and contains option variables and their values in the form OPTION = "value" The values must be enclosed inside double quotes. To include a double quote in the value it must be preceded by a backslash character. Comments are introduced by the hash character '#' and extend to the end of the line. Whites­ pace around options, the equal sign and the value string are ignored. The option variables are not case sensitive. Passwords recognizes the following options in the configu­ ration file: DECRYPT_CMD This is the command used to decrypt the database. The value is given literally as the argument to the command "sh -c" so you can use any shell construct and program available on the system. The command recieves the encrypted data on standard input and is required to write the cleartext to standard out­ put. ENCRYPT_CMD The same as above but the other direction. The com­ mand recieves the cleartext on standard input and must write the ciphertext to standard output. SEPARATOR This string is used as the separator between the fields if the long listing format is selected. The separator specified with the -s option takes prece­ dence over this configuration option. PROMPT The command prompt in interactive mode. The default value for this option is "passwords>". EXAMPLES Sample configuration with no encryption # These commands do no encryption at all and are only meant # to show the principle working and that each command must be # the reverse of the other one. # Compress only ENCRYPT_CMD = "bzip2 -c" DECRYPT_CMD = "bzip2 -c -d" Sample configuration with public key encryption (recommended) # This is the recommended configuration with strong encryption. # You must set up gpg and generate a keypair before you can use # this configuration (see section "SEE ALSO" below). Replace # "my_id" with the user ID associated with your key. # Public key encryption using gpg ENCRYPT_CMD = "gpg -e -r \"my_id\"" DECRYPT_CMD = "gpg --decrypt" FILES ~/.passwords/ This is the directory where passwords stores its configuration file and database. It is automati­ cally created on the first run. ~/.passwords/options The configuration file. The format of this file is explained in the section CONFIGURATION above. If the directory ~/.passwords does not exist when passwords is executed it writes a default configu­ ration file (which really should be edited since it provides no encryption!) ~/.passwords/db The encrypted password database. ~/.passwords/db~ Temporary file while writing the updated database to disk. After the writing process has finished the old database is overwritten with zero data and removed and the temporary file is renamed to the name of the database. SEE ALSO sh(1), gpg(1) The GnuPG homepage http://www.gnupg.org/ The GNU Privacy Handbook, esp. section "Generating a new keypair" http://www.gnupg.org/gph/en/manual.html BUGS Report bugs to AUTHOR Matthias Czapla PASSWORDS(1)