keyfork-user-guide: document porcelain

keyfork-user-guide/src/SUMMARY.md

@@ -9,8 +9,11 @@
 - [Configuration File](./config-file.md)
 - [Binaries](./bin/index.md)
   - [keyfork](./bin/keyfork/index.md)
+    - [derive](./bin/keyfork/derive/index.md)
     - [mnemonic](./bin/keyfork/mnemonic/index.md)
     - [shard](./bin/keyfork/shard/index.md)
+    - [recover](./bin/keyfork/recover/index.md)
+    - [wizard](./bin/keyfork/wizard/index.md)
   - [keyforkd](./bin/keyforkd.md)
   - [keyfork-shard](./bin/keyfork-shard/index.md)
     - [keyfork-shard-split-openpgp](./bin/keyfork-shard/openpgp/split.md)

keyfork-user-guide/src/bin/keyfork/derive/index.md

@@ -0,0 +1,22 @@
+# `keyfork derive`
+
+Derive keys of various formats.
+
+## Common Arguments
+
+`keyfork derive <format> --account-id=0`
+
+* `--account-id=0`: The Account ID to append to the derivation request. This
+  allows multiple accounts to be derived per format. 
+
+## `keyfork derive openpgp`
+
+Generate an OpenPGP keychain with a Certify, Signing, Encryption, and
+Authentication key. The key is generated with a creation date of `1` to ensure
+the key fingerprint does not change. The key is set to expire in one day,
+encouraging users to establish the ability to renew their key when necessary.
+The primary User ID for the certificate is provided as the first argument to
+the derivation request, and must contain at least a real name, a username, or
+an email, but may contain any combination of the three.
+
+`keyfork derive openpgp "Your Name (Username) <your@email.local>"`

keyfork-user-guide/src/bin/keyfork/index.md

@@ -1,11 +1,37 @@
 # keyfork
 
-The primary interface for interacting with the Keyfork utilities.
+The primary interface for interacting with Keyfork utilities.
 
-## `shard`
+## `keyfork derive`
 
-Utilities for splitting and combining secrets using various formats.
+Derive keys of various formats. All commands accept an `--account-id` parameter
+and may accept additional arguments or optional flags depending on the format
+of the derived data. Each format will have its own first-level derivation path,
+such as [BIP-0044] or the numeric representation of a textual identifier, such
+as "pgp" for OpenPGP keys or "shrd" for Shard OpenPGP keys.
 
-## `mnemonic`
+## `keyfork mnemonic`
 
-Utilities pertaining to the creation and management of mnemonics.
+Utilities pertaining to the creation and management of mnemonics. Mnemonics can
+be generated from system entropy or physical entropy, such as a deck of cards
+or dice. Once generated, the mnemonic should be stored in a secure location.
+
+## `keyfork shard`
+
+Utilities for splitting secrets to, and combining secrets from, a Shard file.
+The Shard file is encrypted at rest, and can be recovered directly by Keyfork
+to avoid managing shards or seeds manually.
+
+## `keyfork recover`
+
+Recover a derivation seed and start the Keyfork server. Seeds can be recovered
+from mnemonics, a shard file, or any other supported format. Once the seed has
+been recovered, the Keyfork server starts, and derivation requests can begin.
+
+## `keyfork wizard`
+
+Utilities to automatically manage the setup of Keyfork. This includes
+generating a seed, splitting it into a Shard file, and provisioning smart cards
+with the capability to decrypt the shards.
+
+[BIP-0044]: https://github.com/bitcoin/bips/blob/master/bip-0044.mediawiki

keyfork-user-guide/src/bin/keyfork/mnemonic/index.md

@@ -2,7 +2,7 @@
 
 Utilities for managing mnemonics.
 
-# `keyfork mnemonic generate`
+## `keyfork mnemonic generate`
 
 Generate a mnemonic using various forms of entropy (default: system). Forms of
 entropy also include Tarot cards, playing cards, and dice rolls. Because
@@ -12,7 +12,7 @@ requires a system be both offline and running an up-to-date kernel before
 generating a mnemonic. However, the command may be run with the variable
 `INSECURE_HARDWARE_ALLOWED=1` to override system validation.
 
-## Arguments
+### Arguments
 
 `keyfork mnemonic generate --source=system --size=256`
 

keyfork-user-guide/src/bin/keyfork/recover/index.md

@@ -0,0 +1,42 @@
+# `keyfork recover`
+
+Recover a seed to memory from a mnemonic, shard, or other format, then launch
+the Keyfork server with the recovered seed.
+
+## `keyfork recover shard`
+
+Decrypt a shard file using keys available on the local system. This command
+should be run when all shardholders are present; otherwise, [`keyfork recover
+remote-shard`](#keyfork-recover-remote-shard) should be used instead.
+
+### Arguments
+
+`keyfork recover shard <shard_file> [key_discovery]`
+
+* `shard_file`: The file containing the encrypted shards.
+* `key_discovery`: The location to find OpenPGP Secret Keys, if not using
+  smartcards.
+
+### Prompts
+
+The recovery command will prompt several times during the process, to ensure a
+smart card is plugged in, and to request the PIN to unlock the card.
+
+## `keyfork recover remote-shard`
+
+Ensure the transport of transport-encrypted shards and combine them on the
+current system. This command should be run when a shardholder is not present;
+otherwise, [`keyfork recover shard`](#keyfork-recover-shard) should be used
+instead. The command does not take any arguments, as all necessary metadata is
+stored encrypted alongside the shard.
+
+The command pairs with [`keyfork shard transport`], which should be run by the
+shardholders.
+
+### Prompts
+
+For every shardholder, the recovery command will prompt 33 words to be sent to
+the shardholder, followed by an input prompt of 72 words to be received from
+the shardholder.
+
+[`keyfork shard transport`]: ../shard/index.md#keyfork-shard-transport

keyfork-user-guide/src/bin/keyfork/shard/index.md

@@ -7,7 +7,9 @@ supporting multiple formats.
 
 ## Options
 
-* `--format`: Either `openpgp` or `p256`, provided anywhere after `split`
+* `--format`: Either `openpgp` or `p256`, provided anywhere after `split`.
+  Keyfork will make a best-effort attempt to automatically guess the format,
+  and this flag should not be necessary.
 
 ### Format: OpenPGP
 
@@ -93,3 +95,46 @@ keyfork shard combine --format openpgp < shard.pgp | keyfork-mnemonic-from-seed
 # Decrypt using on-disk private keys
 keyfork shard combine --format openpgp key_discovery.pgp < shard.pgp | keyfork-mnemonic-from-seed
 ```
+
+## `keyfork shard transport`
+
+Ensure a public key for the shard recipient, decrypt a single shard on the
+current system, and prepare it for transport for remote shard recovery.
+
+This command pairs with [`keyfork recover remote-shard`], which should be run
+by a remote recovery operator.
+
+### Arguments
+
+`keyfork shard transport [key_discovery]`
+
+* `key_discovery`: Either a file or a directory containing public keys.
+  If a file, load all private keys from a file.
+  If a directory, for every file in the directory (non-recursively), load
+  private keys from the file.
+  If the amount of keys found is less than `threshold`, it is up to the format
+  to determine how to discover the keys.
+
+### Input
+
+The input of the command is dependent on the format, but should be the exact
+same as the output from the `split` command previously used.
+
+### Prompts
+
+The command will prompt for 33 words from the remote shard recovery operator,
+prompt for a smart card to be plugged in, prompt for the PIN for the smart
+card, and display a prompt of 72 words to be sent to the remote shard recovery
+operator.
+
+### Example
+
+```sh
+# Transport using a smart card
+keyfork shard transport < shard.pgp
+
+# Transport using on-disk private keys
+keyfork shard transport key_discovery.pgp < shard.pgp
+```
+
+[`keyfork recover remote-shard`]: ../recover/index.md#keyfork-recover-remote-shard

keyfork-user-guide/src/bin/keyfork/wizard/index.md

@@ -0,0 +1,32 @@
+# `keyfork wizard`
+
+Set up Keyfork using a guided setup process.
+
+## `keyfork wizard generate-shard-secret`
+
+Generate a 256-bit seed, derive OpenPGP keys using the seed, provision smart
+cards using the derived keys, and export a Shard file.
+
+<div class="warning">
+This command will <b>factory-reset</b> any smart cards plugged into the system.
+It is recommended to use smart cards dedicated to the purpose of seed recovery.
+</div>
+
+### Arguments
+
+`keyfork wizard generate-shard-secret --threshold=1 --max=3 --keys-per-shard=1`
+
+* `threshold`: The minimum amount of shardholders needed to recover the
+  secret.
+* `max`: The maximum amount of shardholders.
+* `keys-per-shard`: The amount of smart cardsz to provision per-shardholder.
+
+### Prompts
+
+The wizard will prompt for a User PIN and an Admin PIN for every shardholder,
+and will require `keys-per-shard` smartcards to be provisioned for every
+shardholder.
+
+### Output
+
+An OpenPGP-encrypted Shard file.