.\" -*-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 --------------------------------------------------