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 [\fICOMMAND\fR] [\fIOPTION\fR ...] [\fIARG\fR ...]


.SH DESCRIPTION
.PP
.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.
.PP
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 versioning the encrypted files to a Git repository as binary
blobs.  (Modification of the stored forms are then automatically
committed to said repository.)  File paths are of the form
\(lq.../\fIscheme\fR/\fIhostname\fR/\fIidentity\fR\(rq 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.
.PP
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
If \fICOMMAND\fR is omitted, \fBfill\fR is assumed.

.TP
.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.  The HTML form selection
algorithm is described in the \fBHTML FORM SELECTION\fR section.
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.
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.

.TP
.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.

.TP
.B cp\fR [\fB-f\fR, \fB--force\fR] \fIscheme\fR://\fIhostname\fR/\fIidentity1\fR \fIscheme\fR://\fIhostname\fR/\fIidentity2\fR
Copy \fIscheme\fR://\fIhostname\fR/\fIidentity1\fR to
\fIscheme\fR://\fIhostname\fR/\fIidentity2\fR.  The destination is
reencrypted on the fly.  If \fB-f\fR is set, don't ask before overriding
an existing destination identity.

.TP
.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.

.TP
.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.

.TP
.B git\fR \fIGIT-COMMAND\fR [\fIGIT-ARG\fR...]
Pass \fIGIT-COMMAND\fR [\fIGIT-ARG\fR...] as arguments to \fIgit\fR(1)
using the configuration value for \fIstore\fR and that for \fIgit-dir\fR
as the Git working tree and Git repository, respectively.
\fIstore\fR is automatically created if it is not an existing directory.

.RS
It is recommended to initialize the repository as follows:

.nf
.RS
\fBicevault git\fR init
echo '*.gpg diff=gpg' >"${XDG_DATA_HOME:-$HOME/.local/share}/icevault/.gitattributes"
\fBicevault git\fR add .gitattributes
\fBicevault git\fR commit \-m 'Add an attribute for .gpg binary files.'
\fBicevault git\fR config diff.gpg.binary true
\fBicevault git\fR config diff.gpg.textconv 'gpg \-qo \- \-\-decrypt \-\-'
.RE
.fi

The textconv config option enable on-the-fly decryption prior to Git
operations such as \fIdiff\fR or \fIgrep\fR, see \fIgitattributes\fR(5).
For instance, grep'ing through the cleartext becomes trivial:

.nf
.RS
\fBicevault git\fR grep \-\-textconv \fIpattern\fR
.RE
.fi

Signing each commit can be achieved as follows, see \fIgit-config\fR(1):

.nf
.RS
\fBicevault git\fR config commit.gpgsign true
\fBicevault git\fR config user.signingkey 0x39278DA8109E6244
.RE
.fi
.RE

.TP
.B import\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.  The HTML form selection algorithm is described in
the \fBHTML FORM SELECTION\fR section.  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.
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).

.TP
.B ls\fR [\fB-0\fR, \fB--zero\fR] [\fB-r\fR, \fB--recursive\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.  If the flag \fB-r\fR is set and
\fIidentity\fR (resp. \fIhostname\fR/\fIidentity\fR) is omitted, list
recursively all identities under \fIscheme\fR://\fIhostname\fR/ (resp.
\fIscheme\fR://).

.TP
.B mv\fR [\fB-f\fR, \fB--force\fR] \fIscheme\fR://\fIhostname\fR/\fIidentity1\fR \fIscheme\fR://\fIhostname\fR/\fIidentity2\fR
Rename \fIscheme\fR://\fIhostname\fR/\fIidentity1\fR as
\fIscheme\fR://\fIhostname\fR/\fIidentity2\fR.  The destination is
reencrypted on the fly.  If \fB-f\fR is set, don't ask before overriding
an existing destination identity.

.TP
.B reencrypt\fR [\fIscheme\fR://[\fIhostname\fR/[\fIidentity\fR]] ...]
Reencrypt each given identity prefix(es) with the \fIkeyid\fR(s) found in
the configuration file as recpient(s).  If no argument is given,
reencrypt the entire store.  If \fIidentity\fR (resp.
\fIidentity\fR/\fIhostname\fR) is omitted, reencrypt all identities
found under \fIscheme\fR://\fIhostname\fR/ (resp. \fIscheme\fR://).

.TP
.B rm\fR [\fB-f\fR, \fB--force\fR] [\fB-r\fR, \fB--recursive\fR] [\fIscheme\fR://[\fIhostname\fR/[\fIidentity\fR]] ...]
Delete the given identity prefix(es).  Croak if \fIidentity\fR is
omitted, unless \fB-r\fR is set.  If \fB-f\fR is set, don't prompt before
each deletion.


.SH GLOBAL OPTIONS
.TP
.B \-\-debug
Turn on debug mode.

.TP
.B \-h\fR, \fB\-\-help\fR
Output a brief help and exit.

.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
the XDG_CONFIG_HOME environment variable is unset.
Options given on the command line override those found in the
configuration file.
The syntax of the configuration file is a serie of
\fIOPTION\fR=\fIVALUE\fR lines;
everything after a \(oq#\(cq character is considered a comment and
ignored.  Valid options are:

.TP
.I git-dir
Path to the Git directory.  Can be an absolute path or a path relative
to the working directory (specified with the \fIstore\fR configuration
option).
(Default: \(lq.git\(rq)

.TP
.I gpg
The \fIgpg\fR(1) command to use.  Users of GnuPG 1.4.x will probably
want to add the \fB--use-agent\fR and possibly \fB--batch\fR options.
(Default: \(lqgpg \-\-quiet\(rq.)

.TP
.I keyid
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
fingerprint.
(Required.)

.TP
.I max-password-length
The maximum length for new passwords.  (Default: \(lq32\(rq.)

.TP
.I pwgen
The command to use to generate new random passwords.  May contain
\(oq%d\(cq, which expands to the password's \(oqmaxLength\(cq 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 as part of the password.
(Default: \(lqpwgen \-s \-cyn %d\(rq.)

.TP
.I socket
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
\(oq~/.mozilla/firefox\(cq directory.
The socket path and permissions can be configured on the
Iceweasel/Firefox side with the \(oqextensions.icevault.socketPath\(cq
and \(oqextensions.icevault.socketPerms\(cq preferences in
\(oqabout:config\(cq, respectively.
(Default: \(lqS.IceVault\(rq.)

.TP
.I store
The working directory.  Can be an absolute path or a path relative
to the XDG_DATA_HOME environment variable (or \fI~/.local/share\fR if
XDG_DATA_HOME is unset).
(Default: \(lqicevault\(rq.)

.TP
.I template
The template mapping \fIscheme\fR://\fIhostname\fR/\fIidentity\fR URIs
to (encrypted) files on disk.  Must contain \(oq%s\(cq, \(oq%h\(cq, and
\(oq%i\(cq, which respectively expand to the \fIscheme\fR,
\fIhostname\fR and \fIidentity\fR parts of the URI.
(Default: \(lq%s/%h/%i.gpg\(rq.)

.SH HTML FORM SELECTION
The HTML form selection for the \fBimport\fR and \fBfill\fR commands is
performed in the following order:

.nr step 1 1
.IP \n[step]. 3
Consider only the visible forms of the active tab of the active window.
.IP \n+[step].
If there is a matching identity in the store, consider only the forms
with matching action / base URI; and if there is a single match take it
(\fBfill\fR only).
.IP \n+[step].
If one of the considered forms has a password field and a (possibly
different) non-empty field, take the first one found.
.IP \n+[step].
Otherwise (if all forms with a password field are empty), and if there
is a form with a password field, take the first one found.
.IP \n+[step].
Otherwise (if no form has a password field), and if there
is a non-empty form, take the first one found.
.IP \n+[step].
Otherwise (if all forms are empty), take the first form in the list.

.SH AUTHOR
Guilhem Moulin <guilhem@fripost.org>
.SH SEE ALSO
\fBgpg\fR(1)