From 535fccc64fec8c45a78c71e956158d7ca7328d70 Mon Sep 17 00:00:00 2001 From: ryan Date: Wed, 10 Jan 2024 13:01:59 -0500 Subject: [PATCH] keyfork-user-guide: document porcelain --- keyfork-user-guide/src/SUMMARY.md | 3 ++ .../src/bin/keyfork/derive/index.md | 22 +++++++++ keyfork-user-guide/src/bin/keyfork/index.md | 36 ++++++++++++-- .../src/bin/keyfork/mnemonic/index.md | 4 +- .../src/bin/keyfork/recover/index.md | 42 +++++++++++++++++ .../src/bin/keyfork/shard/index.md | 47 ++++++++++++++++++- .../src/bin/keyfork/wizard/index.md | 32 +++++++++++++ 7 files changed, 178 insertions(+), 8 deletions(-) create mode 100644 keyfork-user-guide/src/bin/keyfork/derive/index.md create mode 100644 keyfork-user-guide/src/bin/keyfork/recover/index.md create mode 100644 keyfork-user-guide/src/bin/keyfork/wizard/index.md diff --git a/keyfork-user-guide/src/SUMMARY.md b/keyfork-user-guide/src/SUMMARY.md index e9fa7f9..771ec27 100644 --- a/keyfork-user-guide/src/SUMMARY.md +++ b/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) diff --git a/keyfork-user-guide/src/bin/keyfork/derive/index.md b/keyfork-user-guide/src/bin/keyfork/derive/index.md new file mode 100644 index 0000000..ab6ad17 --- /dev/null +++ b/keyfork-user-guide/src/bin/keyfork/derive/index.md @@ -0,0 +1,22 @@ +# `keyfork derive` + +Derive keys of various formats. + +## Common Arguments + +`keyfork derive --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) "` diff --git a/keyfork-user-guide/src/bin/keyfork/index.md b/keyfork-user-guide/src/bin/keyfork/index.md index 67801e0..65cdc5e 100644 --- a/keyfork-user-guide/src/bin/keyfork/index.md +++ b/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 diff --git a/keyfork-user-guide/src/bin/keyfork/mnemonic/index.md b/keyfork-user-guide/src/bin/keyfork/mnemonic/index.md index 6f0794a..3b24903 100644 --- a/keyfork-user-guide/src/bin/keyfork/mnemonic/index.md +++ b/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` diff --git a/keyfork-user-guide/src/bin/keyfork/recover/index.md b/keyfork-user-guide/src/bin/keyfork/recover/index.md new file mode 100644 index 0000000..740e0a4 --- /dev/null +++ b/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 [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 diff --git a/keyfork-user-guide/src/bin/keyfork/shard/index.md b/keyfork-user-guide/src/bin/keyfork/shard/index.md index e38dd89..72b1a49 100644 --- a/keyfork-user-guide/src/bin/keyfork/shard/index.md +++ b/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 diff --git a/keyfork-user-guide/src/bin/keyfork/wizard/index.md b/keyfork-user-guide/src/bin/keyfork/wizard/index.md new file mode 100644 index 0000000..178e3f5 --- /dev/null +++ b/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. + +
+This command will factory-reset any smart cards plugged into the system. +It is recommended to use smart cards dedicated to the purpose of seed recovery. +
+ +### 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.