keyfork-user-guide: docs for `keyfork shard`

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)

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

@@ -0,0 +1,19 @@
+# keyfork-shard
+
+<!-- Linked to: keyfork-user-guide/src/bin/keyfork/shard/index.md -->
+
+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

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

keyfork-user-guide/src/bin/keyfork-shard/openpgp/split.md

@@ -0,0 +1,33 @@
+# keyfork-shard-split-openpgp
+
+<!-- Linked to: keyfork-user-guide/src/bin/keyfork-shard/index.md -->
+
+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.

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.

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

@@ -0,0 +1,76 @@
+# `keyfork shard`
+
+<!-- Linked to: keyfork-user-guide/src/bin/keyfork-shard/index.md -->
+
+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.