--- /dev/null
+.\" -*-nroff-*-
+.\"
+.\" Describe the password safe
+.\"
+.\" (c) 2016 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.
+.
+.ie t \{\
+. if \n(.g \{\
+. fam P
+. \}
+. ds o \(bu
+.\}
+.el \{\
+. ds o o
+.\}
+.
+.de hP
+.IP
+\h'-\w'\fB\\$1\ \fP'u'\fB\\$1\ \fP\c
+..
+.
+.TH pwsafe 1 "13 May 2016" "Straylight/Edgeware" "Catacomb cryptographic library"
+.SH NAME
+pwsafe \- store passwords somewhat securely
+.
+.\"--------------------------------------------------------------------------
+.SH SYNOPSIS
+.
+.B pwsafe
+.RB [ \-f
+.IR file ]
+.I command
+.RI [ arguments
+\&...]
+.PP
+Subcommands:
+'RS
+.B changepp
+.br
+.B copy
+.I dest-file
+.RI [ glob-pattern ]
+.br
+.B create
+.RB [ \-c
+.IR cipher ]
+.RB [ \-d
+.IR db-type ]
+.RB [ \-h
+.IR hash ]
+.RB [ \-m
+.IR mac ]
+.RI [ pp-tag ]
+.br
+.B delete
+.I tag
+.br
+.RB [ find ]
+.I label
+.br
+.B list
+.RI [ glob-pattern ]
+.br
+.B store
+.I label
+.RI [ value ]
+.br
+.B to-pixie
+.RI [ label
+.RI [ pixie-tag ]]
+.br
+.B xfer
+.RB [ \-d
+.IR db-type ]
+.I dest-file
+.RE
+.
+.\"--------------------------------------------------------------------------
+.SH DESCRIPTION
+.
+The
+.B pwsafe
+command maintains a database of passwords
+or other short-ish textual secrets.
+Each password is identified by a
+.IR label .
+The database is ultimately protected by a master password.
+It should quite difficult for an adversary
+who has the database file(s)
+but not your master password
+to find out what any of the stored passwords are,
+or even what the labels are.
+.PP
+The
+.B pwsafe
+program will prompt you for the password as necessary.
+If you are running the Catacomb
+.BR pixie (1)
+then it will first ask the pixie for any necessary passwords,
+and use the pixie to remember the master password for a short while.
+.PP
+A number of database backends are available.
+.TP
+.B gdbm
+Uses the GDBM database library to store a database as a single file.
+Provided for compatibility;
+not recommended for new databases.
+.TP
+.B sqlite
+Uses the SQLite3 library to store a database as a single file.
+SQLite3 has good performance and integrity properties.
+.TP
+.B flat
+Stores the password database as a flat text file.
+Not recommended for large databases because performance will be bad,
+but the simple format admits easy hacking.
+.TP
+.B dir
+Stores the password database as a directory structure.
+This uses much more disk space than the alternatives,
+and enumerating passwords is slow,
+but the directory structure can easily be managed by
+a version control system such as Git.
+.PP
+The following command-line options are available.
+.TP
+.B "\-h, \-\-help"
+Print a help summary to standard output,
+and exit with status zero.
+.TP
+.B "\-v, \-\-version"
+Print the program's version number to standard output,
+and exit with status zero.
+.TP
+.B "\-u, \-\-usage"
+Print a very terse usage summary to standard output,
+and exit with status zero.
+.TP
+.BI "\-f, \-\-file=" file
+Use
+.I file
+as the password database file or directory.
+If this is not specified,
+then the value of the
+.B PWSAFE
+environment variable is used;
+if that too is unset, then the default
+.IB home /.pwsafe \fR,
+is used, where
+.I home
+is the value of the
+.B HOME
+environment variable.
+It is a fatal error if
+.B HOME
+is unset.
+.PP
+The provided commands are described in their own sections below.
+.
+.SS "create"
+Create a new, empty password database.
+As a safety check,
+the file/directory named by the top-level
+.B \-f
+option (or default value)
+must not exist.
+.PP
+You will be prompted (twice) for a master password for the database.
+.PP
+The optional positional argument is the tag
+by which the database's master password
+will be known to the passphrase pixie.
+The default tag is
+.BR pwsafe .
+.PP
+The following options are accepted.
+.TP
+.BI "\-c, \-\-cipher=" cipher
+Use the Catacomb
+.I cipher
+to encrypt blobs.
+Run
+.B catcrypt show cipher
+for a list.
+The default is
+.BR rijndael-cbc .
+.TP
+.BI "\-d, \-\-database=" db-type
+Use the
+.I db-type
+database backend.
+See above for a list of the supported backends.
+Note that
+.B gdbm
+and
+.B sqlite
+depend on external modules, and may not be available.
+The default is
+.BR flat .
+.TP
+.BI "\-h, \-\-hash=" hash
+Use the Catacomb
+.I hash
+for key derivation and password-label mangling.
+Run
+.B catcrypt show hash
+for a list.
+The default is
+.BR sha256 .
+.TP
+.BI "\-m, \-\-mac=" mac
+Use the Catacomb
+.I mac
+to protect the integrity of blobs.
+Run
+.B catcrypt show mac
+for a list.
+The default is
+.IR hash -hmac
+where
+.I hash
+is the hash function chosen by the
+.B \-h
+option.
+.
+.SS "changepp"
+Change the master password for a database.
+This will
+.I not
+re-encrypt all of the records,
+so its utility is somewhat limited.
+See also the
+.B copy
+command.
+The program will prompt you for
+the existing master password (if it's not known by the pixie)
+and the new one (twice, always).
+.
+.SS "copy"
+Copy password records from the
+.I file
+to the
+.I dest-file
+which must be an existing password database.
+If a
+.B glob-pattern
+is given,
+then only records whose
+.I label
+matches the pattern are copied;
+otherwise all password records are copied.
+Any existing passwords in the destination database with the same labels
+will be overwritten.
+.PP
+The destination need not use the same database backend
+or cryptographic parameters as the source.
+.PP
+You will be prompted for the necessary master passwords.
+.
+.SS "delete"
+Delete the password with the given
+.I label
+from the database.
+An error is reported if there is no such password.
+.PP
+You will be prompted for master password if necessary.
+.
+.SS "find"
+Write the password with the given label to standard output,
+followed by a newline.
+.PP
+You will be prompted for master password if necessary.
+.PP
+This is the default operation:
+as a convenience,
+you can write
+.IP
+.B pwsafe
+.I label
+.PP
+rather than
+.IP
+.B pwsafe
+.B find
+.I label
+.PP
+if the
+.I label
+isn't the same as any of
+.BR pwsafe 's
+command names.
+.
+.SS "list"
+Write the labels of the passwords in the database,
+one per line,
+to standard output.
+(If labels contain newline characters,
+you will end up with a mess.)
+If a
+.I glob-pattern
+is supplied,
+then only labels which match the pattern are written.
+.PP
+You will be prompted for master password if necessary.
+.
+.SS "store"
+Store a password, associating it with the given
+.IR label .
+.PP
+If a
+.I value
+is supplied on the command line,
+then it is used as the password value.
+(Note that command-line arguments can be seen
+by other users of the system,
+and may be recorded by the shell.
+This is usually a bad idea.)
+.PP
+As a special case, if the
+.I value
+is
+.BR \- ,
+then the password is read from the first line of standard input;
+the trailing newline is removed.
+The author commonly writes
+.IP
+.BI "gorp -fbase64 | pwsafe store " label " \-"
+.PP
+to set random passwords.
+.PP
+Finally, if no
+.I value
+is given,
+then
+.B pwsafe
+will prompt twice for the password.
+.PP
+You will be prompted for the master password if necessary
+.I before
+the new password value is fetched.
+.PP
+If there is an existing password with the same
+.I label
+then it is overwritten.
+.
+.SS "topixie"
+With no arguments,
+store
+.I all
+of the passwords in the database in the pixie,
+with correspondingly named tags.
+This is probably a bad idea.
+.PP
+With a
+.IR label ,
+store only the labelled password in the pixie.
+With a
+.IR pixie-tag ,
+use that as the tag;
+otherwise use the
+.IR label .
+.PP
+You will be prompted for the master password if necessary.
+.
+.SS "xfer"
+Create a new database containing all of the records of an existing one.
+.PP
+This works at the storage-backend level.
+The new database contains exactly the same metadata and passwords
+as the original.
+It is
+.I not
+necessary to enter a password:
+the blobs are simply copied over without being decrypted.
+.PP
+The following options are accepted.
+.TP
+.BI "\-d, \-\-database=" db-type
+Use the
+.I db-type
+database backend.
+See above for a list of the supported backends.
+Note that
+.B gdbm
+and
+.B sqlite
+depend on external modules, and may not be available.
+The default is
+.BR flat .
+.
+.\"--------------------------------------------------------------------------
+.SH TECHNICAL DETAILS
+.
+The password database contains two kinds of records:
+.I metadata records
+hold important information about the database itself,
+and particularly the various cryptographic options
+chosen when the database was created,
+and the various internal keys used to secure the database;
+while
+.I password records
+actually store your encrypted passwords.
+The various backends store these kinds records in different ways;
+see below for the gory details.
+.
+.SS Metadata
+The metadata records are as follows.
+.TP
+.B cipher
+The symmetric cipher used to encrypt data.
+This names a Catacomb
+.B cipher
+class.
+.TP
+.B hash
+The hash function used in various places.
+This names a Catacomb
+.B hash
+class.
+.TP
+.B key
+A blob,
+protected by the
+.I derived
+keys (see below),
+containing the
+.I main
+secrecy and integrity keys.
+The blob payload consists of the main secrecy and integrity keys,
+each prefixed by its 16-bit length (in network byte order)
+and concatenated.
+.TP
+.B mac
+The message authentication code used to protect integrity.
+This names a Catacomb
+.B mac
+class.
+.TP
+.B magic
+A blob containing a string
+used to construct the database keys for password records;
+see below.
+The magic string is chosen at random
+when the database is created,
+and never changes;
+it is the same length as the chosen hash function's output.
+The blob is protected by the
+.I main
+keys.
+.TP
+.B salt
+A random string
+mixed into the key derivation process.
+.TP
+.B tag
+The passphrase tag,
+used to identify the master password
+to the passphrase
+.BR pixie (1).
+.
+.SS Keys
+The following keys are used.
+.TP
+The \fImaster password\fP
+Remembered (hopefully) by the user;
+used to unlock the
+.I main
+keys.
+.TP
+The \fIderived\fP keys
+A secrecy and integrity pair,
+derived from the
+.I master password
+and
+salt using a hash function.
+.TP
+The \fImain\fP keys
+A secrecy and integrity pair,
+kept in a blob in the database
+(the
+.B key
+metadata item)
+protected by the
+.I derived
+keys.
+The main keys are generated at random
+when the database is created
+and they never change;
+the Catacomb default key lengths are used.
+.
+.SS Deriving keys from the master password
+The keys used for protecting the
+.I main
+secrecy and integrity keys
+are derived by hashing strings of the form
+.IB purpose : password \e0 salt \fR,
+where
+.I purpose
+is
+.B cipher
+or
+.B mac
+to derive the secrecy and integrity keys, respectively.
+The
+.I salt
+string is the value of the
+.B salt
+metadata item described below.
+.PP
+No attempt is made to make the key derivation slow;
+.B pwsafe
+takes the view that you are have been specifically targetted for attack
+by a well-resourced adversary,
+and that you
+.I will
+lose if your password is guessable.
+.
+.SS Making a blob
+A
+.I blob
+contains a
+.IR payload ,
+protecting its secrecy and integrity.
+A blob is constructed using a pair of secrecy and integrity keys;
+most blobs are protected with the
+.I main
+keys;
+the main keys themselves are protected with the
+.I derived
+keys.
+.PP
+The steps to construct a blob are as follows.
+.hP 1.
+Choose a random IV of the appropriate length for the chosen
+.BR cipher .
+.hP 2.
+Encrypt the blob payload
+using the chosen
+.B cipher
+with the secrecy key
+and the IV from step 1,
+to form a ciphertext.
+Prefix the ciphertext with the IV
+to form an augmented ciphertext.
+.hP 3.
+Compute a tag over the augmented ciphertext from step 2
+using the chosen
+.B mac
+with the integrity key.
+Prefix the augmented ciphertext with the tag
+to form the blob.
+.PP
+(It seems more usual to put the tag on the end of the ciphertext,
+but that turned out to be pointlessly harder to implement.)
+.
+.SS Password records
+Conceptually,
+password records are indexed with a textual
+.I label
+chosen by the user.
+But users may want to not only keep their passwords secret,
+but also information about
+.I which
+passwords they have.
+The
+.B pwsafe
+program attempts to maintain the privacy of password record labels,
+but it isn't completely successful, as we shall see.
+Most critically,
+the database backends tend to leak information about
+the
+.I order
+in which records were added into the database.
+.PP
+At the database backend,
+the key used for looking up a password record is a hash,
+in binary:
+specifically, it's a hash of
+the record label
+prefixed by the
+.I magic
+string which is the payload of the blob stored in the
+.B magic
+metadata record.
+.PP
+The value of the password record is a blob,
+protected by the
+.I main
+keys,
+whose payload consists of
+.hP \*o
+the 16-bit network-byte-order length of the record label;
+.hP \*o
+the record label itself;
+.hP \*o
+the 16-bit network-byte-order length of the password;
+.hP \*o
+the password itself; and
+.hP \*o
+zero or more zero-valued octets,
+so as to make the payload a multiple of 256 octets long.
+.PP
+The padding serves to conceal the length of the label and password
+from an adversary who has obtained a copy of the database.
+.
+.SS Backend formats
+The various password-database backends
+represent the records described above as follows.
+.TP
+.B gdbm
+A GDBM-backed database is stored in a single file.
+A metadata record with key
+.I r
+and value
+.I v
+is stored in a GDBM record also named
+.IR r ,
+and with value
+.I v ;
+a password record with hash
+.I h
+and blob
+.I b
+is stored in a GDBM record named
+.BI $ h
+with value
+.IR b ,
+both in raw binary.
+.TP
+.B sqlite
+A SQLite-backed database is stored in a single file.
+It contains two tables,
+named
+.B meta
+and
+.BR passwd .
+The
+.B meta
+table has a primary key
+.B name
+and a further column
+.BR value ;
+a metadata record with key
+.I r
+and value
+.I v
+is held in a
+.B meta
+record
+with
+.B name
+.I r
+and
+.B value
+.IR v ;
+additionally, there is a record with
+.B name
+.B $version
+whose
+.B value
+is the schema version;
+this is currently always 0.
+The
+.B passwd
+table has a primary key
+.B label
+and a further column
+.BR payload ;
+a password record with hash
+.I h
+and blob
+.I b
+is stored in a
+.B passwd
+record with
+.B label
+.IR h
+and
+.B payload
+.IR b ,
+both in raw binary.
+.TP
+.B flat
+A flat-file-backed database is stored in a single file,
+with one record per line.
+The first line must be exactly
+.RS
+.IP
+.B "### pwsafe password database"
+.PP
+Blank lines and lines beginning with a
+.RB ` # '
+are ignored.
+.PP
+A metadata record named
+.I r
+with value
+.I v
+is stored as a line of the form
+.IB r\fR\(fm = v\fR\(fm
+where
+.IR r \fR\(fm
+and
+.IR v \fR\(fm
+are encodings of the strings
+.I r
+and
+.I v
+respectively.
+If
+.I r
+consists only of letters, digits,
+and the punctuation characters
+.RB ` \- ',
+.RB ` _ ',
+.RB ` : ',
+.RB ` . ',
+and
+.RB ` / '
+then
+.IR r \fR\(fm
+is simply
+.IR r ;
+otherwise
+.IR r \fR\(fm
+is formed by (simultaneously) replacing
+each space character in
+.I r
+with
+.RB ` + '
+and each other character
+which is not a letter, digit, or
+one of the punctuation characters listed above
+with
+.RB ` % '
+followed by that character's ASCII code in hex,
+and prefixing the whole lot by
+.RB ` ! '.
+Similarly,
+if
+.I v
+consists of letters, digits,
+and the punctuation characters listed above,
+then
+.IR v \fR\(fm
+is simply
+.IR v ;
+otherwise
+.IR v \fR\(fm
+consists of a
+.RB ` ? '
+followed by the base64 encoding of
+.IR v ,
+without any trailing
+.RB ` = '
+characters.
+.PP
+A password record with hash
+.I h
+and blob
+.I b
+is stored as a line of the form
+.BI $ h\fR\(fm = b\fR\(fm
+where
+.IR h \(fm
+and
+.IR b \(fm
+are the base64 encodings of
+.I h
+and
+.I b
+respectively,
+without trailing
+.RB ` = '
+characters.
+.PP
+The records may appear in any order.
+The file is completely rewritten when any change is made;
+if the file is named
+.I f
+then this is done by writing the new contents to
+.IB f .new
+and then renaming
+.IB f .new
+to
+.IR f .
+.RE
+.TP
+.B dir
+A directory-backed database is stored as a directory,
+named
+.I d
+in the sequel.
+The directory must contain a file
+.IB d /meta
+whose first line is
+.RS
+.IP
+.B "### pwsafe password directory metadata"
+.PP
+and directories
+.IB d /pw
+and
+.IB d /tmp \fR.
+.PP
+Metadata records are stored in file
+.IB d /meta
+with one record per line,
+exactly as for the
+.B file
+backend described above.
+.PP
+A password record with hash
+.I h
+and blob
+.I b
+is stored as file named
+.IB d /pw/ h \fR\(fm
+where
+.IR h \(fm
+is the base64 encodings of
+.I h
+without trailing
+.RB ` = '
+characters,
+and with all
+.RB ` / '
+characters
+replaced by
+.RB ` . 's,
+whose content is
+.IR b .
+.PP
+The directory
+.IB d /tmp/
+is used in an unspecified manner
+when creating new password-record files.
+The
+.IB d /meta
+and
+.IB d /pw/ h \fR\(fm
+files are updated by creating a new temporary file and renaming.
+.RE
+.
+.\"--------------------------------------------------------------------------
+.
+.SH BUGS
+This is quite an old program,
+though the manpage is new.
+It provides more footguns than is ideal.
+.
+.SH SEE ALSO
+.BR catcrypt (1),
+.BR pixie (1).
+.
+.SH AUTHOR
+Mark Wooding, <mdw@distorted.org.uk>
+.
+.\"----- That's all, folks --------------------------------------------------
~mdw / catacomb-python / commitdiff