Scroll to navigation

keysafe(1) General Commands Manual keysafe(1)


keysafe - securely back up secret keys


keysafe [options]


keysafe securely backs up a gpg secret key or other short secret to the cloud.

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.

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.

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.

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.

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.

Whether it's safe to store your gpg secret key in the cloud is your own decision. Keysafe comes with no warranty.


Force backup mode. This is the default if you have a gpg secret key.
Force restore mode. This is the default if you do not have a gpg secret key.
Upload any data to servers that was queued by a previous keysafe run. This is designed to be put in a cron job.
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.
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.
--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.
--restore-server BACKUPDIR
Restore all objects present in the gpg-encrypted backups in the specified directory.
--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.
--chaff-max-delay SECONDS
Specify a delay between chaff uploads. Will delay a random amount between 0 and this many seconds.
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.
Benchmark speed of keysafe's cryptographic primitives.
Run test suite.
--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.
--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.
--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/)
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).
--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.
--name N
Specify name used for key backup/restore, avoiding the usual prompt.
--othername N
Specify other name used for key backup/restore, avoiding the usual prompt.
--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.
--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.
--port P
Port for server to listen on. (default: 4242)
--address A
Address for server to bind to. (Use "*" to bind to all addresses.) (default: "")
--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)
--motd MESSAGE
The server's Message Of The Day.
Avoid using expensive cryptographic operations to secure data. Use for testing only, not with real secret keys.




Joey Hess <>