diff options
Diffstat (limited to 'keysafe.1')
| -rw-r--r-- | keysafe.1 | 166 |
1 files changed, 166 insertions, 0 deletions
diff --git a/keysafe.1 b/keysafe.1 new file mode 100644 index 0000000..73d0b4d --- /dev/null +++ b/keysafe.1 @@ -0,0 +1,166 @@ +.\" -*- 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 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: 80) +.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://joeyh.name/code/keysafe/> +.SH AUTHOR +Joey Hess <id@joeyh.name> |