add man page

This seems to install, but stack is not copying it out to the home
directory. Hmm.

1 files changed, 93 insertions, 0 deletions

diff --git a/keysafe.1 b/keysafe.1
new file mode 100644
index 0000000..4f3bf3e
--- /dev/null
+++ b/keysafe.1
@@ -0,0 +1,93 @@
+.\" -*- 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 truely 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 --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 --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 --store-local
+Store data locally, in ~/.keysafe/objects/local/. 
+(The default is to store data in the cloud.)
+The local data storage consists of 3 (--totalshares) subdirectories,
+which hold the shares of the encrypted secret key. So, you can each
+subdirectory to a separate storage location, and then to restore the key,
+copy 2 (--neededshares) of them back into place.
+.PP
+.IP --gui
+Enable graphical user interface. This is the default unless keysafe
+was run from a terminal. The GUI currently is implemented using zenity(1).
+.PP
+.IP --benchmark
+Benchmark speed of keysafe's cryptographic primitives.
+.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>