aboutsummaryrefslogtreecommitdiffstats
path: root/cli/icevault.1
blob: 906cc8dc21fe26b7f1aec1a89a806f0d3aa62d76 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
.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
.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 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
".../\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
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.
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.
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 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.

It is recommended to initialize the repository as follows:

    \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 Git attributes for .gpg binary files.'
    \fBicevault git\fR config diff.gpg.binary true
    \fBicevault git\fR config diff.gpg.textconv 'gpg2 \-o \- \-\-decrypt'

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:

    \fBicevault git\fR grep \-\-textconv \fIpattern\fR

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

    \fBicevault git\fR config commit.gpgsign true
    \fBicevault git\fR config user.signingkey 0x39278DA8109E6244

.TP
.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
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] [\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
.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
XDG_CONFIG_HOME is unset.
Empty lines and comments (starting with a "#" characters are 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 \fIstore\fR).
(Default: ".git")

.TP
.I gpg
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".)

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

.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.  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
"~/.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 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
unset).
(Default: "icevault".)

.TP
.I template
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: "%s/%h/%i.gpg".)

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