diff --git a/keyfork-user-guide/src/SUMMARY.md b/keyfork-user-guide/src/SUMMARY.md index 2434a57..e9fa7f9 100644 --- a/keyfork-user-guide/src/SUMMARY.md +++ b/keyfork-user-guide/src/SUMMARY.md @@ -4,6 +4,7 @@ # User Guide - [Installing Keyfork](./INSTALL.md) +- [Shard Commands](./shard.md) - [Common Usage](./usage.md) - [Configuration File](./config-file.md) - [Binaries](./bin/index.md) diff --git a/keyfork-user-guide/src/chapter_1.md b/keyfork-user-guide/src/chapter_1.md deleted file mode 100644 index b743fda..0000000 --- a/keyfork-user-guide/src/chapter_1.md +++ /dev/null @@ -1 +0,0 @@ -# Chapter 1 diff --git a/keyfork-user-guide/src/shard.md b/keyfork-user-guide/src/shard.md new file mode 100644 index 0000000..5f56230 --- /dev/null +++ b/keyfork-user-guide/src/shard.md @@ -0,0 +1,63 @@ +# Creating a Seed and Shard File + +If using smartcards dedicated to this use case, Keyfork offers a wizard to +generate a seed and encrypt it to multiple factory-reset smartcards. Assuming +you want to use 2-of-4 shards to recreate the secret, run the following +command: + +```sh +keyfork wizard generate-shard-secret --threshold 2 --max 4 > shards.pgp +``` + +Keyfork will prompt for keys to be inserted and for PINs to be configured for +the smartcards. The shards file should be copied to every system intended to +decrypt shards. + +# Starting Keyfork using a single system + +If all shardholders are present, the following command can be run to start the +Keyfork server process: + +```sh +keyfork recover shard shards.pgp +``` + +Keyfork will prompt for keys to be inserted and for the User PINs for the keys +to be entered. Once the shard is decrypted, the Keyfork server will start. + +# Starting Keyfork using remote systems + +A line of communication should be established with the shardholders, but can be +public and/or insecure. On the system intended to run the Keyfork server, the +following command can be run: + +```sh +keyfork recover remote-shard +``` + +This command will continuously prompt 33 words followed by a QR code containing +the words, and read in 72 words until all necessary shards are recovered. + +Shardholders should run the following command to transport their shards: + +```sh +keyfork shard transport < shards.pgp +``` + +This command will read in 33 words, prompt for a smartcard PIN, and prompt 72 +words, followed by a QR code containing the words. + +# Deriving an OpenPGP key + +This command should be run on a system without persistent storage to avoid +persisting the cold storage key to disk. + +Once the Keyfork server has started, Keyfork can be used to derive an OpenPGP +key: + +```sh +keyfork derive openpgp "Cold Storage Key" > cold_storage.pgp +``` + +The final argument should be a descriptive name for the key, as that name will +likely be used by any program encrypting data to the public key.