From 4e64c73f2183ffe0134c46d6eb3226f2f6c7551e Mon Sep 17 00:00:00 2001 From: ryan Date: Thu, 19 Oct 2023 19:20:26 -0500 Subject: [PATCH] keyfork-user-guide: docs for `keyfork shard` --- keyfork-user-guide/src/SUMMARY.md | 4 + .../src/bin/keyfork-shard/index.md | 19 +++++ .../src/bin/keyfork-shard/openpgp/combine.md | 26 +++++++ .../src/bin/keyfork-shard/openpgp/split.md | 33 ++++++++ keyfork-user-guide/src/bin/keyfork/index.md | 10 +++ .../src/bin/keyfork/shard/index.md | 76 +++++++++++++++++++ 6 files changed, 168 insertions(+) create mode 100644 keyfork-user-guide/src/bin/keyfork-shard/index.md create mode 100644 keyfork-user-guide/src/bin/keyfork-shard/openpgp/combine.md create mode 100644 keyfork-user-guide/src/bin/keyfork-shard/openpgp/split.md create mode 100644 keyfork-user-guide/src/bin/keyfork/shard/index.md diff --git a/keyfork-user-guide/src/SUMMARY.md b/keyfork-user-guide/src/SUMMARY.md index 7a544b4..f5a48f5 100644 --- a/keyfork-user-guide/src/SUMMARY.md +++ b/keyfork-user-guide/src/SUMMARY.md @@ -8,7 +8,11 @@ - [Binaries](./bin/index.md) - [keyfork](./bin/keyfork/index.md) - [mnemonic](./bin/keyfork/mnemonic/index.md) + - [shard](./bin/keyfork/shard/index.md) - [keyforkd](./bin/keyforkd.md) + - [keyfork-shard](./bin/keyfork-shard/index.md) + - [keyfork-shard-split-openpgp](./bin/keyfork-shard/openpgp/split.md) + - [keyfork-shard-combine-openpgp](./bin/keyfork-shard/openpgp/combine.md) - [keyfork-entropy](./bin/keyfork-plumbing/entropy.md) - [keyfork-mnemonic-from-seed](./bin/keyfork-plumbing/mnemonic-from-seed.md) - [keyfork-derive-key](./bin/keyfork-derive-key.md) diff --git a/keyfork-user-guide/src/bin/keyfork-shard/index.md b/keyfork-user-guide/src/bin/keyfork-shard/index.md new file mode 100644 index 0000000..c9d025f --- /dev/null +++ b/keyfork-user-guide/src/bin/keyfork-shard/index.md @@ -0,0 +1,19 @@ +# keyfork-shard + + + +The `keyfork-shard` crate contains some binaries to enable M-of-N sharing of +data. All binaries use Shamir's Secret Sharing through the [`sharks`] crate. + +## OpenPGP + +Keyfork provides OpenPGP compatible [`split`][openpgp-split] and +[`combine`][openpgp-combine] versions of Shard binaries. These binaries use +Sequoia OpenPGP and while they require all the necessary certificates for the +splitting stage, the certificates are included in the payload, and once Keyfork +supports decrypting using OpenPGP smartcards, certificates will not be required +to decrypt the shares. + +[`sharks`]: https://docs.rs/sharks/latest/sharks/ +[openpgp-split]: ./openpgp/split.md +[openpgp-combine]: ./openpgp/combine.md diff --git a/keyfork-user-guide/src/bin/keyfork-shard/openpgp/combine.md b/keyfork-user-guide/src/bin/keyfork-shard/openpgp/combine.md new file mode 100644 index 0000000..5c12274 --- /dev/null +++ b/keyfork-user-guide/src/bin/keyfork-shard/openpgp/combine.md @@ -0,0 +1,26 @@ +# keyfork-shard-combine-openpgp + +Combine `threshold` shares into a previously [`split`] secret. + +## Arguments + +`keyfork-shard-combine-openpgp threshold key_discovery` + +* `threshold`: Minimum number of operators present to recover the secret, as + previously configured when creating the secret +* `key_discovery`: Either a file or a directory containing OpenPGP keys. + If a file, load all keys from the file. + If a directory, for every file in the directory (non-recursively), load + keys from the file. + If the amount of keys found is less than `threshold`, an OpenPGP Card + fallback will be used to decrypt the rest of the messages. + +## Input + +OpenPGP Messages from [`split`]. + +## Output + +Hex-encoded secret. + +[`split`]: ./split.md diff --git a/keyfork-user-guide/src/bin/keyfork-shard/openpgp/split.md b/keyfork-user-guide/src/bin/keyfork-shard/openpgp/split.md new file mode 100644 index 0000000..9770cc1 --- /dev/null +++ b/keyfork-user-guide/src/bin/keyfork-shard/openpgp/split.md @@ -0,0 +1,33 @@ +# keyfork-shard-split-openpgp + + + +Split a secret into threshold-of-max shares, encrypting each share to an +OpenPGP certificate. The resulting file may be kept by any share operator, but +requires at least `threshold` operators to be present to combine into the +original secret. + +## Arguments + +`keyfork-shard-split-openpgp threshold max key_discovery` + +* `threshold`: Minimum number of operators present to recover the secret +* `max`: Maximum number of operators; this many OpenPGP certs must be available +* `key_discovery`: Either a file or a directory containing OpenPGP certs. + If a file, load all certificates from the file. + If a directory, for every file in the directory (non-recursively), load + certificates from the file. + +## Input + +Hex-encoded secret, ideally up to 2048 characters. For larger secrets, encrypt +beforehand using a symmetric key (AES256, for example), and split the symmetric +key. + +## Output + +OpenPGP ASCII armored message containing several sequential encrypted messages. + +**Note:** While it is possible to decrypt some of the messages using a tool +like GnuPG or Sequoia, it is not recommended to handle these messages using +tooling outside of Keyfork Shard. diff --git a/keyfork-user-guide/src/bin/keyfork/index.md b/keyfork-user-guide/src/bin/keyfork/index.md index c8c0ee6..67801e0 100644 --- a/keyfork-user-guide/src/bin/keyfork/index.md +++ b/keyfork-user-guide/src/bin/keyfork/index.md @@ -1 +1,11 @@ # keyfork + +The primary interface for interacting with the Keyfork utilities. + +## `shard` + +Utilities for splitting and combining secrets using various formats. + +## `mnemonic` + +Utilities pertaining to the creation and management of mnemonics. diff --git a/keyfork-user-guide/src/bin/keyfork/shard/index.md b/keyfork-user-guide/src/bin/keyfork/shard/index.md new file mode 100644 index 0000000..cc13522 --- /dev/null +++ b/keyfork-user-guide/src/bin/keyfork/shard/index.md @@ -0,0 +1,76 @@ +# `keyfork shard` + + + +Utilities to enable M-of-N sharing of data, using Shamir's Secret Sharing, +supporting multiple formats. + +## Options + +* `--format`: Either `openpgp` or `p256`, provided anywhere after `split` + +### Format: OpenPGP + +The secret is split and shares are automatically encrypted to provided OpenPGP +certificates. The resulting output is an OpenPGP ASCII armored message +containing several sequential encrypted messages. + +When decrypting, for any missing keys that do not meet the threshold, the +command will prompt for a Yubikey to provide smartcard-based decryption of +shares. + +### Format: p256 + +This section is incomplete as the functionality for p256 keys is not yet +implemented. + +## `keyfork shard split` + +Split a secret into threshold-of-max shares. + +### Arguments + +`keyfork shard split --threshold=threshold --max=max key_discovery` + +* `threshold`: Minimum number of operators present to recover the secret +* `max`: Maximum number of operators, must equal the amount of keys in + `key_discovery` +* `key_discovery`: Either a file or a directory containing public keys. + If a file, load all public keys from a file. + If a directory, for every file in the directory (non-recursively), load + public keys from the file. + +### Input + +Hex-encoded secret, ideally up to 2048 characters. For larger secrets, encrypt +beforehand using a symmetric key (AES256, for example), and split the symmetric +key. + +### Output + +The output of the command is dependent on the format. + +## `keyfork shard combine` + +Combine `threshold` shares into a secret. + +### Arguments + +`keyfork shard combine --threshold=threshold [key_discovery]` + +* `threshold`: Mini mum number of operators present to recover the secret +* `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. + +### Output + +Hex-encoded secret.