From 077d845405416c974895718c04a78a97e09419ff Mon Sep 17 00:00:00 2001 From: ryan Date: Wed, 27 Dec 2023 14:05:34 -0500 Subject: [PATCH] README, keyfork-user-guide: improve docs on keyfork-shard --- README.md | 4 ++++ .../src/bin/keyfork-shard/openpgp/combine.md | 16 +++++++++---- .../src/bin/keyfork-shard/openpgp/split.md | 10 ++++++++ .../src/bin/keyfork/shard/index.md | 23 +++++++++++++++++-- 4 files changed, 47 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 940ba40..a84bcb8 100644 --- a/README.md +++ b/README.md @@ -108,6 +108,9 @@ To follow these steps please install [git-lfs][gl] and [git-sig][gs]. ## Usage +Usage instructions can be found in the `keyfork-user-guide` mdBook. + + diff --git a/keyfork-user-guide/src/bin/keyfork-shard/openpgp/combine.md b/keyfork-user-guide/src/bin/keyfork-shard/openpgp/combine.md index 2395413..7c5d66e 100644 --- a/keyfork-user-guide/src/bin/keyfork-shard/openpgp/combine.md +++ b/keyfork-user-guide/src/bin/keyfork-shard/openpgp/combine.md @@ -4,12 +4,10 @@ Combine `threshold` shares into a previously [`split`] secret. ## Arguments -`keyfork-shard-combine-openpgp threshold key_discovery` +`keyfork-shard-combine-openpgp [key_discovery]` -* `threshold`: Minimum number of operators present to recover the secret, as - previously configured when creating the secret * `key_discovery`: A directory containing OpenPGP keys. - If the amount of keys found is less than `threshold`, an OpenPGP Card + If the number of keys found is less than `threshold`, an OpenPGP Card fallback will be used to decrypt the rest of the messages. ## Pinentry @@ -27,4 +25,14 @@ OpenPGP messages from [`split`]. Hex-encoded secret. +## Example + +```sh +# Decrypt using only smartcards +keyfork-shard-combine-openpgp < shard.pgp + +# Decrypt using on-disk private keys +keyfork-shard-combine-openpgp key_discovery.pgp < shard.pgp +``` + [`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 index 9770cc1..037a8ab 100644 --- a/keyfork-user-guide/src/bin/keyfork-shard/openpgp/split.md +++ b/keyfork-user-guide/src/bin/keyfork-shard/openpgp/split.md @@ -31,3 +31,13 @@ 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. + +## Example + +```sh +# Export PGP keys to key discovery file +gpg --export 88823A75ECAA786B0FF38B148E401478A3FBEF72 F4BF5C81EC78A5DD341C91EEDC4B7D1F52E0BA4D > key_discovery.pgp + +# Generate a secret and split +keyfork-entropy | keyfork-shard-split-openpgp 1 2 key_discovery.pgp > shard.pgp +``` diff --git a/keyfork-user-guide/src/bin/keyfork/shard/index.md b/keyfork-user-guide/src/bin/keyfork/shard/index.md index cc13522..e38dd89 100644 --- a/keyfork-user-guide/src/bin/keyfork/shard/index.md +++ b/keyfork-user-guide/src/bin/keyfork/shard/index.md @@ -50,15 +50,24 @@ key. The output of the command is dependent on the format. +### Example + +```sh +# Export PGP keys of shard holders to key discovery file +gpg --export 88823A75ECAA786B0FF38B148E401478A3FBEF72 F4BF5C81EC78A5DD341C91EEDC4B7D1F52E0BA4D > key_discovery.pgp + +# Generate and split a secret +keyfork-entropy | keyfork shard split --format openpgp --threshold 1 --max 2 key_discovery.pgp > shard.pgp +``` + ## `keyfork shard combine` Combine `threshold` shares into a secret. ### Arguments -`keyfork shard combine --threshold=threshold [key_discovery]` +`keyfork shard combine [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 @@ -74,3 +83,13 @@ same as the output from the `split` command previously used. ### Output Hex-encoded secret. + +### Example + +```sh +# Decrypt using only smartcards +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 +```