README, keyfork-user-guide: improve docs on keyfork-shard

This commit is contained in:
Ryan Heywood 2023-12-27 14:05:34 -05:00
parent 5e62d8909d
commit 077d845405
Signed by: ryan
GPG Key ID: 8E401478A3FBEF72
4 changed files with 47 additions and 6 deletions

View File

@ -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.
<!--
```
keyfork generate [-c,--config=<file>]
Generate new mnemonic optionally public keys defined by config
@ -186,3 +189,4 @@ $ keyfork bip44 --path=bitcoin
> m/44'/0'/0'/0/0: 12DefCMhYVv4sBQikyXKMciAoX2wgzhWqb
```
-->

View File

@ -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

View File

@ -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
```

View File

@ -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
```