.TH ICEVAULT "1" "March 2015" "icevault" "User Commands"
IceVault \- IceVault client user interface
.B icevault\fR [\fICOMMAND\fR] [\fIOPTION\fR ...] [\fIARG\fR ...]
.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
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
If \fICOMMAND\fR is omitted, \fBfill\fR is assumed.
.B fill\fR [\fB-f\fR, \fB--force\fR] [\fB-p\fR, \fB--show-passwords\fR] [\fB-s\fR, \fB--socket=\fR\fIPATH\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
Use \fB--socket=\fR\fIPATH\fR to specify the path to the IceVault
socket. If \fB-f\fR is set, existing values on the browser are ignored.
Passwords are redacted unless the flag \fB-p\fR is set.
.B clip\fR \fIscheme\fR://\fIhostname\fR/\fIidentity\fR
Decrypt the \fIidentity\fR file and copy its first password to the
clipboard using \fIxclip\fR(1), with a maximum number of pastes of 1.
.B dump\fR [\fB-p\fR, \fB--show-passwords\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. Passwords are redacted unless the flag \fB-p\fR is set.
.B edit\fR \fIscheme\fR://\fIhostname\fR/\fIidentity\fR
Decrypt the \fIidentity\fR file to a temporary file and open it using
the editor specified by the EDITOR environment variable (or \fIeditor\fR
if EDITOR is unset). Upon exit, 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.
.B insert\fR [\fB-f\fR, \fB--force\fR] [\fB-s\fR, \fB--socket=\fR\fIPATH\fR] [\fIidentity\fR]
Create a new \fIscheme\fR://\fIhostname\fR/\fIidentity\fR URI available
for further 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
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.
Use \fB--socket=\fR\fIPATH\fR to specify the path to the IceVault
socket. If the flag \fB-f\fR is set, override the \fIidentity\fR file
if it already exists (the default is to abort).
.B ls\fR [\fB-0\fR, \fB--zero\fR] [\fIscheme\fR://[\fIhostname\fR/[\fIidentity\fR]]]
List content of the given identity prefix. If the flag \fB-0\fR is set,
use NUL as line separator.
.SH GLOBAL OPTIONS
Turn on debug mode.
.B \-h\fR, \fB\-\-help\fR
Output a brief help and exit.
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:
The \fIgpg\fR(1) command to use. Note that users of GnuPG 1.4.x will
probably want to add the \fB--use-agent\fR option. (Default: "gpg".)
A comma-separated list of OpenPGP key ID(s) used as encryption
recipient(s). Each component must be given as 64-bits keyid or full
The maximum length for new passwords. (Default: "32".)
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".)
The path of the UNIX socket used to communicate with the browser. Can
be an absolute path or a path relative to the default Firefox profile
(or first profile found if there is no default profile) in the
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",
The working directory. Can be an absolute path or a path relative
to \fI$XDG_CONFIG_HOME\fR (or \fI~/.local/share\fR if XDG_CONFIG_HOME is
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.
Guilhem Moulin <email@example.com>
.SH SEE ALSO