From 80438cd2af17083d85bb12da6756961abfedecbb Mon Sep 17 00:00:00 2001 From: Guilhem Moulin Date: Sat, 21 Mar 2015 17:13:32 +0100 Subject: Move the CLI part to a dedicated dir, with a separate Makefile. --- cli/icevault.1 | 183 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 183 insertions(+) create mode 100644 cli/icevault.1 (limited to 'cli/icevault.1') diff --git a/cli/icevault.1 b/cli/icevault.1 new file mode 100644 index 0000000..1413382 --- /dev/null +++ b/cli/icevault.1 @@ -0,0 +1,183 @@ +.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. + +.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. +(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 +.SH SEE ALSO +\fBgpg\fR(1) -- cgit v1.2.3