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)
|
- [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)
|
||||||
|
|
|
@ -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
|
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
|
|
||||||
|
|
Loading…
Reference in New Issue