docs: import chunk from README into usage, create entropy dev guide
This commit is contained in:
parent
701f5ca4e9
commit
e643645fd5
|
@ -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)
|
||||
|
|
|
@ -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).
|
|
@ -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 <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.
|
||||
```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 default format is to use system entropy, but playing cards, tarot cards, or
|
||||
dice can be used to generate physical entropy
|
||||
-->
|
||||
|
||||
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-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
|
||||
|
|
Loading…
Reference in New Issue