path: root/keysafe.1

.\" -*- nroff -*-
.TH keysafe 1 "Commands"
.SH NAME
keysafe \- securely back up secret keys
.SH SYNOPSIS
.B keysafe [options]
.SH DESCRIPTION
.I keysafe
securely backs up a gpg secret key or other short secret to the cloud.
.PP
This is not intended for storing Debian Developer keys that yield root on
ten million systems. It's about making it possible for users to use gpg who
currently don't, and who would find it too hard to use paperkey(1) to back
up and restore their key as they reinstall their laptop.
.PP
To get started with keysafe, you can run it without any options. If your
account has a gpg secret key, keysafe will prompt you for a password to
protect it with, and a name to store it under, and will back it up securely
to the cloud. 
.PP
To restore from the backup, just run keysafe from an account that does not
have a gpg secret key (or use the --restore option to force restore mode).
Keysafe will prompt for the same name and password, and restore the key.
.PP
Note that the backup operation takes half an hour or so,
and the restore operation takes an hour or so. Keysafe encrypts
the secret key with the password in a way that takes a lot of computation
to decrypt. This makes it hard for an attacker to crack your password,
because each guess they make costs them.
.PP
Keysafe is designed so that it should take millions of dollars (US)
of computer time to crack any fairly good password. With a truly good
password, such as four random words, the cracking cost should be many
trillions of dollars. Keysafe checks your password strength (using the
zxcvbn library), and shows an estimate of the cost to crack your password,
before backing up the key.
.PP
Whether it's safe to store your gpg secret key in the cloud is your
own decision. Keysafe comes with no warranty.
.SH OPTIONS
.PP
.IP --backup
Force backup mode. This is the default if you have a gpg secret key.
.PP
.IP --restore
Force restore mode. This is the default if you do not have a gpg secret
key.
.PP
.IP --uploadqueued
Upload any data to servers that was queued by a previous keysafe run.
This is designed to be put in a cron job.
.PP
.IP --autostart
This is run automatically on desktop login by the desktop autostart
file included with keysafe. It checks for any new gpg keys that have
not been backed up, and prompts to see if the user wants to back them up
with keysafe. Also uploads any queued data, and in the future may perform
other checks for problems.
.PP
.IP --server
Runs keysafe in server mode, accepting objects and storing them.
Use --store-directory to configure where the server stores objects,
and --port and --address to configure how the server listens to
connections. It's recommended to only expose keysafe servers over a tor
hidden service.
.PP
.IP "--backup-server BACKUPDIR"
Run on a server, populates the BACKUPDIR with a gpg encrypted backup
of all the objects stored in the --store-directory. This is designed
to be rsynced offsite (with --delete) to back up a keysafe server with
minimal information leakage.
.PP
.IP "--restore-server BACKUPDIR"
Restore all objects present in the gpg-encrypted
backups in the specified directory.
.PP
.IP "--chaff HOSTNAME"
Upload random data to a keysafe server. --port can be used to specify
the server's port. Continues uploading data until interrupted with ctrl-c.
.PP
.IP "--chaff-max-delay SECONDS"
Specify a delay between chaff uploads. Will delay a
random amount between 0 and this many seconds.
.PP
.IP --check-servers
Tries to connect to each server in the server list.
Displays the server's MOTD, and the amount of data
stored on it. Prints message to stderr and exits
nonzero if any of the servers are not accessible.
.PP
.IP --benchmark
Benchmark speed of keysafe's cryptographic primitives.
.PP
.IP --test
Run test suite.
.PP
.IP "--gpgkeyid KEYID"
Specify keyid of gpg key to back up or restore. This is useful if you
have multiple gpg keys. But, when this option is used to back up a key,
you have to also provide it to restore that key.
.PP
.IP "--keyfile FILE"
To back up anything other than a gpg secret key, use this option.
To restore from the backup, you must use this same option, and pass the
exact same filename.
.PP
.IP "--store-directory dir"
Where to store data locally. For the client, data is
stored here before it is uploaded to the server. For
the server, this is where it stores its data.
(default: ~/.keysafe/objects/)
.PP
.IP --gui
Use GUI interface for interaction. Default is to use
readline interface when run in a terminal, and GUI otherwise.
The GUI currently is implemented using zenity(1).
.PP
.IP "--totalshares M --neededshares N"
These options have to be specified together.
The default values are --totalshares 3 --neededshares 2.
Keysafe uses Shamir secret sharing to create M shares of the encrypted
secret key, and each share is stored in a different server.
To restore the data, only N of the shares are needed. If you specify
these options when backing up a secret key, you also must specify them
with the same values to restore that secret key.
.PP
.IP "--name N"
Specify name used for key backup/restore, avoiding the usual prompt.
.PP
.IP "--othername N"
Specify other name used for key backup/restore, avoiding the usual prompt.
.PP
.IP "--add-storage-directory DIR"
Add the directory to the list of locations keysafe
will use for backup/restore of keys. Keysafe will use
the directory first, before any of its built-in servers.
.PP
.IP "--add-server HOST[:PORT]"
Add the server to the server list which keysafe will
use for backup/restore of keys. Keysafe will use the
server first before any of its built-in servers.
.PP
.IP "--port P"
Port for server to listen on. (default: 4242)
.PP
.IP "--address A"
Address for server to bind to. (Use "*" to bind to
all addresses.) (default: "127.0.0.1")
.PP
.IP "--months-to-fill-half-disk N"
Server rate-limits requests and requires proof of
work, to avoid too many objects being stored. This is
an lower bound on how long it could possibly take for
half of the current disk space to be
filled. (default: 12)
.PP
.IP "--motd MESSAGE"
The server's Message Of The Day.
.PP
.IP --testmode
Avoid using expensive cryptographic operations to secure data.
Use for testing only, not with real secret keys.
.SH SEE ALSO
<https://keysafe.branchable.com/>
.SH AUTHOR 
Joey Hess <id@joeyh.name>