From: Mark Wooding Date: Sun, 28 May 2017 18:03:08 +0000 (+0100) Subject: pwsafe.1: Documentation for the password safe. X-Git-Tag: 1.3.0~36 X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~mdw/git/catacomb-python/commitdiff_plain/a8f59fc004c0f4ec4b1ec64e7a54f7d9f2fd587c?ds=sidebyside pwsafe.1: Documentation for the password safe. --- diff --git a/pwsafe.1 b/pwsafe.1 new file mode 100644 index 0000000..361ba95 --- /dev/null +++ b/pwsafe.1 @@ -0,0 +1,878 @@ +.\" -*-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, +. +.\"----- That's all, folks -------------------------------------------------- diff --git a/setup.py b/setup.py index fe0ed53..89a56b8 100755 --- a/setup.py +++ b/setup.py @@ -24,5 +24,6 @@ MS.setup(name = 'catacomb-python', license = 'GNU General Public License', packages = ['catacomb'], scripts = ['pwsafe'], + data_files = [('share/man/man1', ['pwsafe.1'])], genfiles = [MS.Generate('algorithms.h')], ext_modules = [cat])