path: root/cli/icevault.1

.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
.br
.B icevault\fR [\fIOPTIONS\fR] \fBclip\fR \fIscheme\fR://\fIhostname\fR/\fIidentity\fR
.br
.B icevault\fR [\fIOPTIONS\fR] \fBedit\fR \fIscheme\fR://\fIhostname\fR/\fIidentity\fR
.br
.B icevault\fR [\fIOPTIONS\fR] \fBls\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.

.TP
.B clip\fR \fIscheme\fR://\fIhostname\fR/\fIidentity\fR
Decrypt the \fIidentity\fR file and copy the first password to the
clipboard using \fIxclip\fR(1), with a maximum number of pastes of 1.

.TP
.B edit\fR \fIscheme\fR://\fIhostname\fR/\fIidentity\fR
Decrypt the \fIidentity\fR file to a temporary file and opens it using
the editor specified by the EDITOR environment variable.  When the
editor exits, the file is reencrypted if the SHA-256 digest of its
content differs.  Note that formatting and comments may not be preserved
by subsequent updates of the \fIidentity\fR file.

.TP
.B ls\fR [\fIscheme\fR://[\fIhostname\fR/[\fIidentity\fR]]]
List content of the given identity prefix.


.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.
The socket path and permissions can be configured on the
Iceweasel/Firefox side with the "extensions.icevault.socketPath" and
"extensions.icevault.socketPerms" preferences in "about:config",
respectively.

.TP
.B \-\-version
Show the version number and exit.

.TP
.B \-0\fR, \fB\-\-zero
With the \fBls\fR command, use NUL instead of newline as line delimiter.


.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.
The socket path and permissions can be configured on the
Iceweasel/Firefox side with the "extensions.icevault.socketPath" and
"extensions.icevault.socketPerms" preferences in "about:config",
respectively.
(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)