From 459e20dad92e1ce276286aa7821c7bef3c4743fd Mon Sep 17 00:00:00 2001 From: Guilhem Moulin Date: Tue, 17 Mar 2015 02:20:19 +0100 Subject: Manpage --- icevault | 6 ++- icevault.1 | 155 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 159 insertions(+), 2 deletions(-) create mode 100644 icevault.1 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 +.SH SEE ALSO +\fBgpg\fR(1) -- cgit v1.2.3