From 37d2f09c6b70d8f41c576f723b88be629a7b8e7d Mon Sep 17 00:00:00 2001
From: ryan <ryan@distrust.co>
Date: Mon, 8 Jan 2024 19:17:49 -0500
Subject: [PATCH] keyfork-user-guide: add shard commands guide

---
 keyfork-user-guide/src/SUMMARY.md   |  1 +
 keyfork-user-guide/src/chapter_1.md |  1 -
 keyfork-user-guide/src/shard.md     | 63 +++++++++++++++++++++++++++++
 3 files changed, 64 insertions(+), 1 deletion(-)
 delete mode 100644 keyfork-user-guide/src/chapter_1.md
 create mode 100644 keyfork-user-guide/src/shard.md

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.