From 09c3e1bda8fbce3d2b3016fbb9a3ffb62de17ede Mon Sep 17 00:00:00 2001
From: ryan <ryan@distrust.co>
Date: Wed, 10 Jan 2024 13:42:48 -0500
Subject: [PATCH] keyfork-user-guide: tidy up more docs

---
 .../src/dev-guide/provisioners.md             | 22 ++++++++++++++
 keyfork-user-guide/src/shard.md               | 29 +++++++++++++------
 2 files changed, 42 insertions(+), 9 deletions(-)

diff --git a/keyfork-user-guide/src/dev-guide/provisioners.md b/keyfork-user-guide/src/dev-guide/provisioners.md
index cac0c7a..60b5297 100644
--- a/keyfork-user-guide/src/dev-guide/provisioners.md
+++ b/keyfork-user-guide/src/dev-guide/provisioners.md
@@ -37,6 +37,28 @@ provisioned to, avoiding ambiguities when (for example) multiple devices are
 plugged into a host. A plumbing crate may provide a binary to list identifiers
 for potential targets, if possible.
 
+### Deriving Data
+
+A quick example is provided to show how data can be requested from the Keyfork
+server. The response contains the bytes representing the private key; the chain
+code, depth, and algorithm are also included in the response, and can be used
+for further derivation if required.
+
+```rs
+use keyfork_derive_util::{
+    request::{DerivationAlgorithm, DerivationRequest, DerivationResponse},
+    DerivationIndex, DerivationPath,
+};
+use keyforkd_client::Client;
+
+let path = DerivationPath::from_str("m/44'/0'/0'")?;
+let request = DerivationRequest::new(DerivationAlgorithm::Secp256k1, &path);
+let response: DerivationResponse = Client::discover_socket()?
+    .request(&request.into())?
+    .try_into()?;
+let derived_key = response.data;
+```
+
 ## Porcelain
 
 Once the plumbing crates have been written, porcelain subcommands should be
diff --git a/keyfork-user-guide/src/shard.md b/keyfork-user-guide/src/shard.md
index 5f56230..547738c 100644
--- a/keyfork-user-guide/src/shard.md
+++ b/keyfork-user-guide/src/shard.md
@@ -1,4 +1,11 @@
-# Creating a Seed and Shard File
+# Keyfork Shard Commands
+
+Sharding a seed allows "M-of-N" recovery of the seed, which is useful for
+disaster recovery situations, avoiding the case where a single person may be
+left in charge of the seed. Keyfork provides utilities to help with the
+management of seeds through sharding.
+
+## 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
@@ -13,7 +20,7 @@ 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
+## Starting Keyfork using a single system
 
 If all shardholders are present, the following command can be run to start the
 Keyfork server process:
@@ -25,7 +32,7 @@ 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
+## 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
@@ -47,17 +54,21 @@ 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.
+## Example: Deriving an OpenPGP key for Encryption
 
 Once the Keyfork server has started, Keyfork can be used to derive an OpenPGP
-key:
+key, and [Sequoia] can be used to extract the public portions:
 
 ```sh
-keyfork derive openpgp "Cold Storage Key" > cold_storage.pgp
+keyfork derive openpgp "Storage Key" | sq key extract-cert > 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.
+
+The key, including the secret portions, can be retrieved by running the command
+without the `sq` portion, but should not be run on a system with a persistent
+filesystem, to avoid keeping the key on written memory for longer than
+necessary.
+
+[Sequoia]: https://sequoia-pgp.org