docs: import chunk from README into usage, create entropy dev guide

This commit is contained in:
Ryan Heywood 2024-01-16 00:05:18 -05:00
parent 701f5ca4e9
commit e643645fd5
Signed by: ryan
GPG Key ID: 8E401478A3FBEF72
3 changed files with 80 additions and 29 deletions

View File

@ -28,3 +28,4 @@
- [Writing Binaries](./dev-guide/index.md) - [Writing Binaries](./dev-guide/index.md)
- [Provisioners](./dev-guide/provisioners.md) - [Provisioners](./dev-guide/provisioners.md)
- [Auditing Dependencies](./dev-guide/auditing.md) - [Auditing Dependencies](./dev-guide/auditing.md)
- [Entropy Guide](./dev-guide/entropy.md)

View File

@ -0,0 +1,13 @@
# Entropy Guide
Keyfork provides a `keyfork-entropy` crate for generating entropy. The crate
exposes two functions, `ensure_safe` and `generate_entropy_of_size`. The former
function ensures the kernel is of a version with a safe CSPRNG and that no
network interfaces are listed as up, while the latter function reads `size`
bytes from `/dev/urandom` and returns it. This function is used for any crate
where (non-derived) entropy is needed.
Some crates will only accept a `rand::RngCore` type. For this, the `OsRng` RNG
must be used. It is listed as a `CryptoRng` and has been audited to confirm it
calls the `getrandom()` function in a secure manner, calling the function with
zero flags enabled (outside of validating the syscall is available).

View File

@ -2,41 +2,78 @@
Keyfork is a tool to help manage the creation and derivation of binary data Keyfork is a tool to help manage the creation and derivation of binary data
using [BIP-0039] mnemonics. A mnemonic is, in simple terms, a way of encoding a using [BIP-0039] mnemonics. A mnemonic is, in simple terms, a way of encoding a
random number between 128 and 256 bits large, as a list of 12 to 24 words that large number between 128 and 256 bits, as a list of 12 to 24 words that can be
can be easily stored or memorized. Once a user has a mnemonic, Keyfork utilizes easily stored or memorized. Once a user has a mnemonic, Keyfork utilizes
[BIP-0032] to derive cryptographic keys, which can be utilized by a variety of [BIP-0032] to derive cryptographic keys, which can be utilized by a variety of
applications. applications.
Once a user has generated a mnemonic with [`keyfork mnemonic generate`], the ### Personal Setup
mnemonic can be loaded to [`keyforkd`]. This is typically done automatically by
[`keyfork`], but plumbing binaries (commands that are not `keyfork`, such as
`keyfork-derive-key`) require the server to be started manually.
**NOTE:** Anything beyond this point should be considered Design by On an airgapped system, run the following command to generate a BIP-0039
Documentation, and while the commands are not likely to change between now and mnemonic encoding a generated seed:
when they are released, there is no current stable interface for these
commands, and they may change at any time.
Users can then "provision" keys, or automatically deploy generated keys to ```sh
specific endpoints. Running `keyfork provision` will automatically list all keyfork mnemonic generate
known provisioners, while running `keyfork provision help <provisioner>` will ```
include detailed information about the specific provisioner. For OpenPGP
smartcards (such as Yubikeys), `keyfork provision openpgp-card` will
automatically derive an OpenPGP key and provision it to a smartcard. As
previously mentioned, if `keyforkd` was not previously started, a prompt will
be provided by the provisioner for the mnemonic, and `keyforkd` will be started
in the background.
Any usage of `keyfork provision` or `keyfork derive` can also be given the Once generated, the mnemonic should be written down and stored in a secure
`--save` flag, to modify a `keyfork.toml` file and record when the key was location such as a safe.
derived, and for what purpose. This is useful, for instance, with OpenPGP,
where a key may be derived with certain capabilities that may not be remembered <!--
otherwise. Later, the command `keyfork recover` can be used to automatically The default format is to use system entropy, but playing cards, tarot cards, or
re-provision each previously invoked provisioner, and re-derive all previously dice can be used to generate physical entropy
invoked derivation, through an interactive prompt. -->
The Keyfork server can be started by running the following command:
```sh
keyfork recover mnemonic
```
### Group Setup
This guide assumes you are sharding to an `N`-of-`M` system with `I` smart
cards per shardholder. The variables will be used in the following commands as
`$N`, `$M`, and `$I`. The smart cards will be factory reset during the process.
On an airgapped system, run the following command to generate a file containing
encrypted shards of a generated seed:
```sh
keyfork wizard generate-shard-secret --threshold $N --max $M --keys-per-shard $I --output shards.pgp
```
Once generated, the shards file can be safely stored in any location, as the
only information that can be obtained from the shard file is the `$N` value.
If all shardholders are physically present, the Keyfork server can be started
by running the following command:
```sh
keyfork recover shard
```
Otherwise, the Keyfork server can be started by transporting the shards to the
machine using the following command:
```sh
keyfork recover remote-shard
```
Each shard can be transported by running the following command:
```sh
keyfork shard transport shard.pgp
```
### Deriving Keys
Keys can be derived from Keyfork using the `keyfork derive` command, such as
the following command for an OpenPGP certificate with one of each subkey:
```sh
keyfork derive openpgp "John Doe <jdoe@example.com>"
```
[BIP-0039]: https://github.com/bitcoin/bips/blob/master/bip-0039.mediawiki [BIP-0039]: https://github.com/bitcoin/bips/blob/master/bip-0039.mediawiki
[BIP-0032]: https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki [BIP-0032]: https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki
[`keyfork mnemonic generate`]: ./bin/keyfork/mnemonic/index.md#generate
[`keyforkd`]: ./bin/keyforkd.md
[`keyfork`]: ./bin/keyfork.md