keyfork-user-guide: docs for `keyfork shard`
This commit is contained in:
parent
7da9738d52
commit
4e64c73f21
|
@ -8,7 +8,11 @@
|
||||||
- [Binaries](./bin/index.md)
|
- [Binaries](./bin/index.md)
|
||||||
- [keyfork](./bin/keyfork/index.md)
|
- [keyfork](./bin/keyfork/index.md)
|
||||||
- [mnemonic](./bin/keyfork/mnemonic/index.md)
|
- [mnemonic](./bin/keyfork/mnemonic/index.md)
|
||||||
|
- [shard](./bin/keyfork/shard/index.md)
|
||||||
- [keyforkd](./bin/keyforkd.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-entropy](./bin/keyfork-plumbing/entropy.md)
|
||||||
- [keyfork-mnemonic-from-seed](./bin/keyfork-plumbing/mnemonic-from-seed.md)
|
- [keyfork-mnemonic-from-seed](./bin/keyfork-plumbing/mnemonic-from-seed.md)
|
||||||
- [keyfork-derive-key](./bin/keyfork-derive-key.md)
|
- [keyfork-derive-key](./bin/keyfork-derive-key.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
|
|
@ -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
|
|
@ -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.
|
|
@ -1 +1,11 @@
|
||||||
# keyfork
|
# 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.
|
||||||
|
|
|
@ -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.
|
Loading…
Reference in New Issue