3 .\" Describe the password safe
5 .\" (c) 2016 Straylight/Edgeware
8 .\"----- Licensing notice ---------------------------------------------------
10 .\" This file is part of the Python interface to Catacomb.
12 .\" Catacomb/Python is free software; you can redistribute it and/or modify
13 .\" it under the terms of the GNU General Public License as published by
14 .\" the Free Software Foundation; either version 2 of the License, or
15 .\" (at your option) any later version.
17 .\" Catacomb/Python is distributed in the hope that it will be useful,
18 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
19 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
20 .\" GNU General Public License for more details.
22 .\" You should have received a copy of the GNU General Public License
23 .\" along with Catacomb/Python; if not, write to the Free Software Foundation,
24 .\" Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
38 \h'-\w'\fB\\$1\ \fP'u'\fB\\$1\ \fP\c
41 .TH pwsafe 1 "13 May 2016" "Straylight/Edgeware" "Catacomb cryptographic library"
43 pwsafe \- store passwords somewhat securely
45 .\"--------------------------------------------------------------------------
97 .\"--------------------------------------------------------------------------
102 command maintains a database of passwords
103 or other short-ish textual secrets.
104 Each password is identified by a
106 The database is ultimately protected by a master password.
107 It should quite difficult for an adversary
108 who has the database file(s)
109 but not your master password
110 to find out what any of the stored passwords are,
111 or even what the labels are.
115 program will prompt you for the password as necessary.
116 If you are running the Catacomb
118 then it will first ask the pixie for any necessary passwords,
119 and use the pixie to remember the master password for a short while.
121 A number of database backends are available.
124 Uses the GDBM database library to store a database as a single file.
125 Provided for compatibility;
126 not recommended for new databases.
129 Uses the SQLite3 library to store a database as a single file.
130 SQLite3 has good performance and integrity properties.
133 Stores the password database as a flat text file.
134 Not recommended for large databases because performance will be bad,
135 but the simple format admits easy hacking.
138 Stores the password database as a directory structure.
139 This uses much more disk space than the alternatives,
140 and enumerating passwords is slow,
141 but the directory structure can easily be managed by
142 a version control system such as Git.
144 The following command-line options are available.
147 Print a help summary to standard output,
148 and exit with status zero.
150 .B "\-v, \-\-version"
151 Print the program's version number to standard output,
152 and exit with status zero.
155 Print a very terse usage summary to standard output,
156 and exit with status zero.
158 .BI "\-f, \-\-file=" file
161 as the password database file or directory.
162 If this is not specified,
163 then the value of the
165 environment variable is used;
166 if that too is unset, then the default
167 .IB home /.pwsafe \fR,
172 environment variable.
173 It is a fatal error if
177 The provided commands are described in their own sections below.
180 Create a new, empty password database.
182 the file/directory named by the top-level
184 option (or default value)
187 You will be prompted (twice) for a master password for the database.
189 The optional positional argument is the tag
190 by which the database's master password
191 will be known to the passphrase pixie.
195 The following options are accepted.
197 .BI "\-c, \-\-cipher=" cipher
202 .B catcrypt show cipher
207 .BI "\-d, \-\-database=" db-type
211 See above for a list of the supported backends.
216 depend on external modules, and may not be available.
220 .BI "\-h, \-\-hash=" hash
223 for key derivation and password-label mangling.
225 .B catcrypt show hash
230 .BI "\-m, \-\-mac=" mac
233 to protect the integrity of blobs.
241 is the hash function chosen by the
246 Change the master password for a database.
249 re-encrypt all of the records,
250 so its utility is somewhat limited.
254 The program will prompt you for
255 the existing master password (if it's not known by the pixie)
256 and the new one (twice, always).
259 Copy password records from the
263 which must be an existing password database.
267 then only records whose
269 matches the pattern are copied;
270 otherwise all password records are copied.
271 Any existing passwords in the destination database with the same labels
274 The destination need not use the same database backend
275 or cryptographic parameters as the source.
277 You will be prompted for the necessary master passwords.
280 Delete the password with the given
283 An error is reported if there is no such password.
285 You will be prompted for master password if necessary.
288 Write the password with the given label to standard output,
289 followed by a newline.
291 You will be prompted for master password if necessary.
293 This is the default operation:
308 isn't the same as any of
313 Write the labels of the passwords in the database,
316 (If labels contain newline characters,
317 you will end up with a mess.)
321 then only labels which match the pattern are written.
323 You will be prompted for master password if necessary.
326 Store a password, associating it with the given
331 is supplied on the command line,
332 then it is used as the password value.
333 (Note that command-line arguments can be seen
334 by other users of the system,
335 and may be recorded by the shell.
336 This is usually a bad idea.)
338 As a special case, if the
342 then the password is read from the first line of standard input;
343 the trailing newline is removed.
344 The author commonly writes
346 .BI "gorp -fbase64 | pwsafe store " label " \-"
348 to set random passwords.
355 will prompt twice for the password.
357 You will be prompted for the master password if necessary
359 the new password value is fetched.
361 If there is an existing password with the same
363 then it is overwritten.
369 of the passwords in the database in the pixie,
370 with correspondingly named tags.
371 This is probably a bad idea.
375 store only the labelled password in the pixie.
382 You will be prompted for the master password if necessary.
385 Create a new database containing all of the records of an existing one.
387 This works at the storage-backend level.
388 The new database contains exactly the same metadata and passwords
392 necessary to enter a password:
393 the blobs are simply copied over without being decrypted.
395 The following options are accepted.
397 .BI "\-d, \-\-database=" db-type
401 See above for a list of the supported backends.
406 depend on external modules, and may not be available.
410 .\"--------------------------------------------------------------------------
411 .SH TECHNICAL DETAILS
413 The password database contains two kinds of records:
415 hold important information about the database itself,
416 and particularly the various cryptographic options
417 chosen when the database was created,
418 and the various internal keys used to secure the database;
421 actually store your encrypted passwords.
422 The various backends store these kinds records in different ways;
423 see below for the gory details.
426 The metadata records are as follows.
429 The symmetric cipher used to encrypt data.
430 This names a Catacomb
435 The hash function used in various places.
436 This names a Catacomb
447 secrecy and integrity keys.
448 The blob payload consists of the main secrecy and integrity keys,
449 each prefixed by its 16-bit length (in network byte order)
453 The message authentication code used to protect integrity.
454 This names a Catacomb
459 A blob containing a string
460 used to construct the database keys for password records;
462 The magic string is chosen at random
463 when the database is created,
465 it is the same length as the chosen hash function's output.
466 The blob is protected by the
472 mixed into the key derivation process.
476 used to identify the master password
481 The following keys are used.
483 The \fImaster password\fP
484 Remembered (hopefully) by the user;
489 The \fIderived\fP keys
490 A secrecy and integrity pair,
494 salt using a hash function.
497 A secrecy and integrity pair,
498 kept in a blob in the database
505 The main keys are generated at random
506 when the database is created
507 and they never change;
508 the Catacomb default key lengths are used.
510 .SS Deriving keys from the master password
511 The keys used for protecting the
513 secrecy and integrity keys
514 are derived by hashing strings of the form
515 .IB purpose : password \e0 salt \fR,
522 to derive the secrecy and integrity keys, respectively.
525 string is the value of the
527 metadata item described below.
529 No attempt is made to make the key derivation slow;
531 takes the view that you are have been specifically targetted for attack
532 by a well-resourced adversary,
535 lose if your password is guessable.
542 protecting its secrecy and integrity.
543 A blob is constructed using a pair of secrecy and integrity keys;
544 most blobs are protected with the
547 the main keys themselves are protected with the
551 The steps to construct a blob are as follows.
553 Choose a random IV of the appropriate length for the chosen
556 Encrypt the blob payload
560 and the IV from step 1,
561 to form a ciphertext.
562 Prefix the ciphertext with the IV
563 to form an augmented ciphertext.
565 Compute a tag over the augmented ciphertext from step 2
568 with the integrity key.
569 Prefix the augmented ciphertext with the tag
572 (It seems more usual to put the tag on the end of the ciphertext,
573 but that turned out to be pointlessly harder to implement.)
577 password records are indexed with a textual
580 But users may want to not only keep their passwords secret,
581 but also information about
586 program attempts to maintain the privacy of password record labels,
587 but it isn't completely successful, as we shall see.
589 the database backends tend to leak information about
592 in which records were added into the database.
594 At the database backend,
595 the key used for looking up a password record is a hash,
597 specifically, it's a hash of
601 string which is the payload of the blob stored in the
605 The value of the password record is a blob,
609 whose payload consists of
611 the 16-bit network-byte-order length of the record label;
613 the record label itself;
615 the 16-bit network-byte-order length of the password;
617 the password itself; and
619 zero or more zero-valued octets,
620 so as to make the payload a multiple of 256 octets long.
622 The padding serves to conceal the length of the label and password
623 from an adversary who has obtained a copy of the database.
626 The various password-database backends
627 represent the records described above as follows.
630 A GDBM-backed database is stored in a single file.
631 A metadata record with key
635 is stored in a GDBM record also named
639 a password record with hash
643 is stored in a GDBM record named
650 A SQLite-backed database is stored in a single file.
651 It contains two tables,
658 table has a primary key
662 a metadata record with key
675 additionally, there is a record with
680 is the schema version;
681 this is currently always 0.
684 table has a primary key
688 a password record with hash
703 A flat-file-backed database is stored in a single file,
704 with one record per line.
705 The first line must be exactly
708 .B "### pwsafe password database"
710 Blank lines and lines beginning with a
714 A metadata record named
718 is stored as a line of the form
719 .IB r\fR\(fm = v\fR\(fm
724 are encodings of the strings
731 consists only of letters, digits,
732 and the punctuation characters
745 is formed by (simultaneously) replacing
746 each space character in
750 and each other character
751 which is not a letter, digit, or
752 one of the punctuation characters listed above
755 followed by that character's ASCII code in hex,
756 and prefixing the whole lot by
761 consists of letters, digits,
762 and the punctuation characters listed above,
771 followed by the base64 encoding of
777 A password record with hash
781 is stored as a line of the form
782 .BI $ h\fR\(fm = b\fR\(fm
787 are the base64 encodings of
796 The records may appear in any order.
797 The file is completely rewritten when any change is made;
800 then this is done by writing the new contents to
809 A directory-backed database is stored as a directory,
813 The directory must contain a file
818 .B "### pwsafe password directory metadata"
825 Metadata records are stored in file
827 with one record per line,
830 backend described above.
832 A password record with hash
836 is stored as file named
840 is the base64 encodings of
855 is used in an unspecified manner
856 when creating new password-record files.
861 files are updated by creating a new temporary file and renaming.
864 .\"--------------------------------------------------------------------------
867 This is quite an old program,
868 though the manpage is new.
869 It provides more footguns than is ideal.
876 Mark Wooding, <mdw@distorted.org.uk>
878 .\"----- That's all, folks --------------------------------------------------