.\" Automatically generated by Pandoc 2.2.1
.\"
.TH "GOKEY" "1" "2018\-06\-06" "gokey" "Gokey's Manual"
.hy
.SH NAME
.PP
gokey \- A simple vaultless password manager in Go
.SH SYNOPSIS
.PP
\f[B]gokey\f[] [\f[B]OPTIONS\f[]]
.SH DESCRIPTION
.PP
\f[B]gokey\f[] is a password manager, which does not require a password
vault.
Instead of storing your passwords in a vault it derives your password on
the fly from your master password and supplied \f[I]realm\f[] string
(for example, resource URL).
This way you do not have to manage, backup or sync your password vault
(or trust its management to a third party) as your passwords are
available immediately anywhere.
.SH OPTIONS
.TP
.B \f[B]\-o\f[] \f[I]output_path\f[]
by default \f[B]gokey\f[] outputs generated data to \f[I]stdout\f[]
.RS
.RE
.TP
.B \f[B]\-P\f[] \f[I]/path/to/password\f[]
path to master password file which will be used to generate other
passwords/keys or to encrypt seed file (see \f[I]Modes of operation\f[]
below, if no master password or master password file is provided,
\f[B]gokey\f[] will ask for it interactively)
.RS
.RE
.TP
.B \f[B]\-p\f[] \f[I]master_password\f[]
master password which will be used to generate other passwords/keys or
to encrypt seed file (see \f[I]Modes of operation\f[] below, if no
master password or master password file is provided, \f[B]gokey\f[] will
ask for it interactively)
.RS
.RE
.TP
.B \f[B]\-r\f[] \f[I]password/key_realm\f[]
any string which identifies requested password/key, most likely key
usage or resource URL
.RS
.RE
.TP
.B \f[B]\-s\f[] \f[I]path_to_seed_file\f[]
needed, if you want to use seed file instead of master password as an
entropy source (see \f[I]Modes of operation\f[] below); can be generated
with \f[B]\-t\f[] \f[I]seed\f[] flag as described below
.RS
.RE
.TP
.B \f[B]\-skip\f[] \f[I]number_of_bytes\f[]
number of bytes to skip when reading seed file
.RS
.RE
.TP
.B \f[B]\-u\f[]
\f[B]UNSAFE\f[], allow generating keys without using a seed file (see
\f[I]Modes of operation\f[] below)
.RS
.RE
.TP
.B \f[B]\-t\f[] \f[I]password/key_type\f[]
requested password/key output type.
Supported password/key types:
.RS
.IP \[bu] 2
\f[I]pass\f[] \- default, generates a password
.IP \[bu] 2
\f[I]seed\f[] \- generates a seed file, which can be used with
\f[B]\-s\f[] option later
.IP \[bu] 2
\f[I]raw\f[] \- generates 32 random bytes (can be used as a symmetric
key)
.IP \[bu] 2
\f[I]ec256\f[] \- generates ECC P\-256 private key
.IP \[bu] 2
\f[I]ec521\f[] \- generates ECC P\-521 private key
.IP \[bu] 2
\f[I]rsa2048\f[] \- generates 2048\-bit RSA private key
.IP \[bu] 2
\f[I]rsa4096\f[] \- generates 4096\-bit RSA private key
.IP \[bu] 2
\f[I]x25519\f[] \- generates x25519 (also known as curve25519) ECC
private key
.IP \[bu] 2
\f[I]ed25519\f[] \- generates ed25519 ECC private key
.RE
.SH MODES OF OPERATION
.PP
\f[B]gokey\f[] can generate passwords and cryptographic private keys
(ECC and RSA keys are currently supported).
However, without any additional options specified it uses your master
password as a single source of entropy for generated data.
For passwords it is acceptable most of the time, but keys usually have
much higher entropy requirements.
.PP
For cases, where higher entropy is required for generated
passwords/keys, \f[B]gokey\f[] can use a seed file (a blob with random
data) instead of the master password as a source of entropy.
.SS Simple mode (without a seed file)
.PP
In simple mode passwords are derived directly from your master password
and the realm string.
That is each unique combination of a master password and a realm string
will produce a unique password.
.PP
For example, if your master password is
\f[I]super\-secret\-master\-password\f[] and you want to generate a
password for \f[I]example.com\f[], you would invoke \f[B]gokey\f[] like
.IP
.nf
\f[C]
gokey\ \-p\ super\-secret\-master\-password\ \-r\ example.com
\f[]
.fi
.PP
If you need a password for a different resource, \f[I]example2.com\f[],
you would change the real string
.IP
.nf
\f[C]
gokey\ \-p\ super\-secret\-master\-password\ \-r\ example2.com
\f[]
.fi
.PP
This way you need to remember only your master password and you can
always recreate passwords for your services/resources.
.PP
\f[I]NOTE\f[]: In this mode generated passwords are as strong as your
master password, so do have your master password strong enough.
You can also derive private keys from your master password, but keep in
mind, that these keys will have low entropy.
That is why it is considered unsafe, so \f[B]gokey\f[] does not allow it
by default.
If you're \f[B]\f[BI]really\f[B]\f[] know what you are doing, you can
override this default by supplying \f[B]\-u\f[] flag.
.SS Using a seed file
.PP
If you plan to generate not only passwords, but also private keys or you
want to have your passwords/keys with higher entropy, you can use a seed
file instead of the master password.
You still need to supply a master password, when invoking
\f[B]gokey\f[], but it will be used only to protect the seed file
itself; all generated passwords/keys will be derived from the data in
the seed file.
\f[B]gokey\f[] uses seed files protected (encrypted) with your master
password, so it is reasonably safe to store/backup seed files to a third
party location, such as Google Drive or Dropbox.
.PP
To generate an encrypted seed file, use
.IP
.nf
\f[C]
gokey\ \-p\ super\-secret\-master\-password\ \-t\ seed\ \-o\ seedfile
\f[]
.fi
.PP
This will create a seed file \f[I]seedfile\f[] with 256 bytes of random
data.
The data is encrypted using AES\-256\-GCM mode and
\f[I]super\-secret\-master\-password\f[] as a key.
.PP
Then, to generate EC\-256 private key for \f[I]example.com\f[], use
.IP
.nf
\f[C]
gokey\ \-p\ super\-secret\-master\-password\ \-s\ seedfile\ \-r\ example.com\ \-t\ ec256
\f[]
.fi
.SH AUTHOR
.PP
Ignat Korchagin <ignat@cloudflare.com>