Manpage

2 files changed, 159 insertions, 2 deletions

diff --git a/icevault b/icevault
index 3ec9acb..445c3aa 100755
--- a/icevault
+++ b/icevault
@@ -371,7 +371,7 @@ sub pwgen(@) {
     my $pwgen = $CONFIG{pwgen};
 
     # see how long the password is allowed to be
-    my $l = $CONFIG{'pw-maxlength'};
+    my $l = $CONFIG{'max-password-length'};
     $l = min (map { my $x = $1 if defined $_->{maxLength} and $_->{maxLength} =~ /^(\d+)$/;
                     (defined $x and $x > 0 and $x < $l) ?  $x : $l } @fields);
     $pwgen =~ s/%d/$l/g;
@@ -445,8 +445,10 @@ $CONFIG{gpg} //= 'gpg';
 $CONFIG{socket} //= 'S.IceVault';
 $CONFIG{store} //= "$XDG_DATA_HOME/icevault/%s/%h/%i.gpg";
 $CONFIG{pwgen} //= 'pwgen -s -cyn %d';
-$CONFIG{'pw-maxlength'} //= 32;
+$CONFIG{'max-password-length'} //= 32;
 $CONFIG{keyid} // error "Missing keyid in configuration file";
+error "C<%s> is not a 64-bits key ID or fingerprint", $CONFIG{keyid}
+    unless $CONFIG{keyid} =~ /^(?:(?:0x)?\p{AHex}{16}|\p{AHex}{40})$/;
 
 usage(1) unless @ARGV;
 @ARGV = map { $LOCALE->decode($_) } @ARGV;
diff --git a/icevault.1 b/icevault.1
new file mode 100644
index 0000000..4b18121
--- /dev/null
+++ b/icevault.1
@@ -0,0 +1,155 @@
+.TH ICEVAULT "1" "March 2015" "icevault" "User Commands"
+
+.SH NAME
+IceVault \- IceVault client user interface
+
+.SH SYNOPSIS
+.B icevault\fR [\fIOPTIONS\fR] [\fBfill\fR] \fIscheme\fR://\fIhostname\fR/\fIidentity\fR
+.br
+.B icevault\fR [\fIOPTIONS\fR] \fBinsert\fR [\fIidentity\fR]
+.br
+.B icevault\fR [\fIOPTIONS\fR] \fBdump\fR \fIscheme\fR://\fIhostname\fR/\fIidentity\fR
+
+
+.SH DESCRIPTION
+.B icevault\fR is an external password/login manager for Firefox.  Its
+threat model is arguably more secure than the builtin manager's, as the
+browser is not granted direct access to the list of known HTML forms nor
+their content: instead, managing forms is delegated to a separate
+process, the \fBicevault\fR client, and the filling is done by manual
+request.
+Communication between the \fBicevault\fR client and the browser is done
+via a UNIX socket, which the browser creates upon startup; usual UNIX
+permissions can (and should) be used to restrict access to the socket.
+Further isolation can be achieved by using different UIDs for the
+browser and the \fBicevault\fR client.
+
+Each form is stored in a separate file, encrypted separately with
+\fIgpg\fR(1); cleartext are never stored on disk.  Form history can be kept
+track of by adding the encrypted files to a VCS as binary blobs.  File
+paths are of the form ".../\fIscheme\fR/\fIhostname\fR/\fIidentity\fR"
+where \fIidentity\fR is an arbitrary user-chosen value (allowing
+multiple identities for a given site); since the URI of the active tab
+can be retrieved from the socket and since the URI of a stored form can
+be recovered from its file path, phishing attacks are easily detected.
+
+Like Firefox's builtin password manager, IceVault has some heuristics to
+detect signup and password changing pages.  In these cases, and if the
+password fields are left blank, the (new) password is randomly chosen
+using \fIpwgen\fR(1).
+
+
+.SH COMMANDS
+.TP
+.B fill\fR \fIscheme\fR://\fIhostname\fR/\fIidentity\fR
+If the scheme (resp. hostname) of the active tab of the active window is
+not \fIscheme\fR (resp. \fIhostname\fR) the program assumes a phishing
+attempt and aborts.  Otherwise, the \fIidentity\fR file is decrypted and
+used to fill a visible form on the browser.
+Form selection is done by matching on the base URI; it fallbacks to the
+first form containing a password; and further fallbacks to the first
+form with a non-empty field.
+Changes to the \fIidentity\fR are detected and can be saved on demand.
+If \fIidentity\fR has a single password whereas the webpage has 2 (resp.
+3), a signup (resp. password changing) page is assumed, and a new
+password is randomly generated using \fIpwgen\fR(1) if the fields are
+left blank.
+
+.TP
+.B insert\fR [\fIidentity\fR]
+Create a new \fIscheme\fR://\fIhostname\fR/\fIidentity\fR URI available
+for further \fBfill\fR and other commands.
+Store the first visible form on the active tab of the active window which
+contains a password (or the first visible form with a non-empty field if
+no visible form has a password).  If \fIidentity\fR is omitted, it
+defaults to the value of the last textual value before the first
+password (or the first textual value if the selected form has no
+password).
+If the webpage has 2 (resp. 3), a signup (resp. password changing) page
+is assumed, and a new password is randomly generated using
+\fIpwgen\fR(1) if the fields are left blank.
+
+.TP
+.B dump\fR \fIscheme\fR://\fIhostname\fR/\fIidentity\fR
+Decrypt the \fIidentity\fR file and dump its content on the standard
+output.  Note that while the output is a valid YAML document, original
+formatting may not be preserved; in particular, comments and empty lines
+are stripped.
+
+
+.SH OPTIONS
+.TP
+.B \-\-debug
+Turn on debug mode.
+
+.TP
+.B \-h\fR, \fB\-\-help\fR
+Output a brief help and exit.
+
+.TP
+.B \-p\fR, \fB\-\-show\-passwords\fR
+By default passwords are redacted when printing forms to the standard
+output.  This flags turns off this behavior.
+
+.TP
+.B \-s\fR \fIsockpath\fR, \fB\-\-socket=\fR\fIsockpath\fR
+Specify the path of the UNIX socket used to communicate with the
+browser.  If the path does not start with a slash "/", it is assumed to
+be relative to the default Firefox profile (or first profile found if
+there is no default profile) in the "~/.mozilla/firefox" directory.
+
+.TP
+.B \-\-version
+Show the version number and exit.
+
+.SH CONFIGURATION FILE
+
+\fBicevault\fR reads it configuration from
+\fI$XDG_CONFIG_HOME/icevault\fR, or \fI~/.config/icevault\fR if
+XDG_CONFIG_HOME is unset.
+Empty lines and comments (starting with a "#" characters are ignored).
+Valid options are:
+
+.TP
+.I gpg
+The \fIgpg\fR(1) binary to use.  (Default: "gpg".)
+
+.TP
+.I keyid
+The OpenPGP key ID used as encryption recipient.  Must be given a
+64-bits keyid or full fingerprint.
+
+.TP
+.I max-password-length
+The maximum length for new passwords.  (Default: "32".)
+
+.TP
+.I pwgen
+The command to use to generate new random passwords.  May contain "%d",
+which expands to the password's "maxLength" attribute (capped with the
+\fImax-password-length\fR option).  The command is expected to output to
+the standard output, and may add a newline character afterwards, which
+is not considered part of the password.
+(Default: "pwgen -s -cyn %d".)
+
+.TP
+.I socket
+The path of the UNIX socket used to communicate with the browser.  If
+the path does not start with a slash "/", it is assumed to be relative
+to the default Firefox profile (or first profile found if there is no
+default profile) in the "~/.mozilla/firefox" directory.
+(Default: "S.IceVault".)
+
+.TP
+.I store
+The template mapping \fIscheme\fR://\fIhostname\fR/\fIidentity\fR URIs
+to (encrypted) files on disk.  Must contain "%s", "%h", and "%i", which
+respectively expand to the \fIscheme\fR, \fIhostname\fR and
+\fIidentity\fR parts of the URI.
+(Default: "$XDG_DATA_HOME/icevault/%s/%h/%i.gpg", or
+"~/.data/icevault/%s/%h/%i.gpg" if $XDG_DATA_HOME is unset.)
+
+.SH AUTHOR
+Guilhem Moulin <guilhem@fripost.org>
+.SH SEE ALSO
+\fBgpg\fR(1)