From e643645fd55b0478356d7928ffc17919a2bff7ab Mon Sep 17 00:00:00 2001 From: ryan Date: Tue, 16 Jan 2024 00:05:18 -0500 Subject: [PATCH] docs: import chunk from README into usage, create entropy dev guide --- docs/src/SUMMARY.md | 1 + docs/src/dev-guide/entropy.md | 13 +++++ docs/src/usage.md | 95 ++++++++++++++++++++++++----------- 3 files changed, 80 insertions(+), 29 deletions(-) create mode 100644 docs/src/dev-guide/entropy.md diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md index 8bfde2b..b5b38c2 100644 --- a/docs/src/SUMMARY.md +++ b/docs/src/SUMMARY.md @@ -28,3 +28,4 @@ - [Writing Binaries](./dev-guide/index.md) - [Provisioners](./dev-guide/provisioners.md) - [Auditing Dependencies](./dev-guide/auditing.md) +- [Entropy Guide](./dev-guide/entropy.md) diff --git a/docs/src/dev-guide/entropy.md b/docs/src/dev-guide/entropy.md new file mode 100644 index 0000000..1e29863 --- /dev/null +++ b/docs/src/dev-guide/entropy.md @@ -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). diff --git a/docs/src/usage.md b/docs/src/usage.md index 205da0e..be84693 100644 --- a/docs/src/usage.md +++ b/docs/src/usage.md @@ -2,41 +2,78 @@ 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 -random number between 128 and 256 bits large, as a list of 12 to 24 words that -can be easily stored or memorized. Once a user has a mnemonic, Keyfork utilizes +large number between 128 and 256 bits, as a list of 12 to 24 words that can be +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 applications. -Once a user has generated a mnemonic with [`keyfork mnemonic generate`], the -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. +### Personal Setup -**NOTE:** Anything beyond this point should be considered Design by -Documentation, and while the commands are not likely to change between now and -when they are released, there is no current stable interface for these -commands, and they may change at any time. +On an airgapped system, run the following command to generate a BIP-0039 +mnemonic encoding a generated seed: -Users can then "provision" keys, or automatically deploy generated keys to -specific endpoints. Running `keyfork provision` will automatically list all -known provisioners, while running `keyfork provision help ` 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. +```sh +keyfork mnemonic generate +``` -Any usage of `keyfork provision` or `keyfork derive` can also be given the -`--save` flag, to modify a `keyfork.toml` file and record when the key was -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 -re-provision each previously invoked provisioner, and re-derive all previously -invoked derivation, through an interactive prompt. +Once generated, the mnemonic should be written down and stored in a secure +location such as a safe. + + + +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 " +``` [BIP-0039]: https://github.com/bitcoin/bips/blob/master/bip-0039.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