ICEVAULT

NAME

IceVault − IceVault client user interface

SYNOPSIS

icevault [COMMAND] [OPTION ...] [ARG ...]

DESCRIPTION

icevault 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 icevault client, and the filling is done by manual request. Communication between the icevault 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 icevault client.

Each form is stored in a separate file, encrypted separately with gpg(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 “.../scheme/hostname/identity” where identity 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 pwgen(1).

COMMANDS

If COMMAND is omitted, fill is assumed.
fill
[-f, --force] [-p, --show-passwords] [-s, --socket=PATH]
scheme
://hostname/identity

If the scheme (resp. hostname) of the active tab of the active window is not scheme (resp. hostname) the program assumes a phishing attempt and aborts. Otherwise, the identity file is decrypted and used to fill a visible form on the browser. The HTML form selection algorithm is described in the HTML FORM SELECTION section. Changes to the identity are detected and can be saved on demand. If identity 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 pwgen(1) if the fields are left blank. Use --socket=PATH to specify the path to the IceVault socket. If -f is set, existing values on the browser are ignored. Passwords are redacted unless the flag -p is set.

clip scheme://hostname/identity

Decrypt the identity file and copy its first password to the clipboard using xclip(1), with a maximum number of pastes of 1.

cp [-f, --force] scheme://hostname/identity1
scheme
://hostname/identity2

Copy scheme://hostname/identity1 to scheme://hostname/identity2. The destination is reencrypted on the fly. If -f is set, don’t ask before overriding an existing destination identity.

dump [-p, --show-passwords] scheme://hostname/identity

Decrypt the identity 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 -p is set.

edit scheme://hostname/identity

Decrypt the identity file to a temporary file and open it using the editor specified by the EDITOR environment variable (or editor 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 identity file.

git GIT-COMMAND [GIT-ARG...]

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

It is recommended to initialize the repository as follows:

icevault git init
echo ’*.gpg diff=gpg’ >"${XDG_DATA_HOME:-$HOME/.local/share}/icevault/.gitattributes"
icevault git
add .gitattributes
icevault git
commit −m ’Add an attribute for .gpg binary files.’
icevault git
config diff.gpg.binary true
icevault git
config diff.gpg.textconv ’gpg −qo − −−decrypt −−’

The textconv config option enable on-the-fly decryption prior to Git operations such as diff or grep, see gitattributes(5). For instance, grep’ing through the cleartext becomes trivial:

icevault git grep −−textconv pattern

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

icevault git config commit.gpgsign true
icevault git
config user.signingkey 0x39278DA8109E6244

import [-f, --force] [-s, --socket=PATH] [identity]

Create a new scheme://hostname/identity URI available for further commands. The HTML form selection algorithm is described in the HTML FORM SELECTION section. If identity 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 pwgen(1) if the fields are left blank. Use --socket=PATH to specify the path to the IceVault socket. If the flag -f is set, override the identity file if it already exists (the default is to abort).

ls [-0, --zero] [-r, --recursive] [scheme://[hostname/[identity]] ...]

List content of the given identity prefix. If the flag -0 is set, use NUL as line separator. If the flag -r is set and identity (resp. hostname/identity) is omitted, list recursively all identities under scheme://hostname/ (resp. scheme://).

mv [-f, --force] scheme://hostname/identity1
scheme
://hostname/identity2

Rename scheme://hostname/identity1 as scheme://hostname/identity2. The destination is reencrypted on the fly. If -f is set, don’t ask before overriding an existing destination identity.

reencrypt [scheme://[hostname/[identity]] ...]

Reencrypt each given identity prefix(es) with the keyid(s) found in the configuration file as recpient(s). If no argument is given, reencrypt the entire store. If identity (resp. identity/hostname) is omitted, reencrypt all identities found under scheme://hostname/ (resp. scheme://).

rm [-f, --force] [-r, --recursive] [scheme://[hostname/[identity]] ...]

Delete the given identity prefix(es). Croak if identity is omitted, unless -r is set. If -f is set, don’t prompt before each deletion.

GLOBAL OPTIONS

−−debug

Turn on debug mode.

−h, −−help

Output a brief help and exit.

−−version

Show the version number and exit.

CONFIGURATION FILE

icevault reads its configuration from $XDG_CONFIG_HOME/icevault, or ~/.config/icevault 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 OPTION=VALUE lines; everything after a ’#’ character is considered a comment and ignored. Valid options are:
git-dir

Path to the Git directory. Can be an absolute path or a path relative to the working directory (specified with the store configuration option). (Default: “.git”)

gpg

The gpg(1) command to use. Users of GnuPG 1.4.x will probably want to add the --use-agent and possibly --batch options. (Default: “gpg −−quiet”.)

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

max-password-length

The maximum length for new passwords. (Default: “32”.)

pwgen

The command to use to generate new random passwords. May contain ’%d’, which expands to the password’s ’maxLength’ attribute (capped with the max-password-length 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: “pwgen −s −cyn %d”.)

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

store

The working directory. Can be an absolute path or a path relative to the XDG_DATA_HOME environment variable (or ~/.local/share if XDG_DATA_HOME is unset). (Default: “icevault”.)

template

The template mapping scheme://hostname/identity URIs to (encrypted) files on disk. Must contain ’%s’, ’%h’, and ’%i’, which respectively expand to the scheme, hostname and identity parts of the URI. (Default: “%s/%h/%i.gpg”.)

HTML FORM SELECTION

The HTML form selection for the import and fill commands is performed in the following order:

1.

Consider only the visible forms of the active tab of the active window.

2.

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 (fill only).

3.

If one of the considered forms has a password field and a (possibly different) non-empty field, take the first one found.

4.

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.

5.

Otherwise (if no form has a password field), and if there is a non-empty form, take the first one found.

6.

Otherwise (if all forms are empty), take the first form in the list.

SEE ALSO

gpg(1)

AUTHOR

Written by Guilhem Moulin.