README: cleanup wordings

This commit is contained in:
Ryan Heywood 2024-01-10 13:21:21 -05:00
parent 535fccc64f
commit 155de0ce31
Signed by: ryan
GPG Key ID: 8E401478A3FBEF72
1 changed files with 25 additions and 21 deletions

View File

@ -4,9 +4,13 @@ An opinionated and modular toolchain for generating and managing a wide range
of cryptographic keys offline and on smartcards from a shared bip39 mnemonic of cryptographic keys offline and on smartcards from a shared bip39 mnemonic
phrase. phrase.
This toolchain uses a bip32 seed loaded into an agent to generate deterministic Keyfork can be used by organizations and solo users, for the purposes of
and unique keypairs. This ensures only the agent has control over the mnemonic disaster recovery, cold storage, and reproducibility of private keys and secret
itself, and other components can simply request deterministic data. data. Keyfork achieves this by using a bip32 seed loaded into an agent to
generate deterministic and unique keypairs. This ensures only the agent has
control over the mnemonic itself, and other components can request
deterministic data. The seed can be split using the Keyfork Shard mechanism,
which utilizes Shamir's Secret Sharing to allow "M-of-N" recovery of the seed.
This repository must not be managed by `cargo-hakari`, to ensure each plumbing This repository must not be managed by `cargo-hakari`, to ensure each plumbing
binary can be built with as few dependencies and SLOC to review as possible. binary can be built with as few dependencies and SLOC to review as possible.
@ -27,36 +31,36 @@ across several crates.
## Keyfork Top-Level Binary ## Keyfork Top-Level Binary
The `keyfork` binary is the most user-friendly interface for interacting with The `keyfork` binary is the most user-friendly interface for interacting with
the Keyfork toolchain. It offers commands that should not take any scriptable the Keyfork toolchain. It offers commands that are intended to accept
input and should not produce any script-readable output. Such operations that human-readable input and produce human-readable output, and can be described as
require script compatibility should be made into their own utilities, with the a "Terminal User Interface" rather than a "Command Line Interface". An example
higher level interface of interacting with them left solely to `keyfork`. of a `keyfork` command would be `keyfork wizard generate-shard-secret`, which
will generate a secret, provision smart cards, and export the newly-generated
For instance, the program to generate system entropy is `keyfork-entropy`. It Shard file. Processes included in the `keyfork` binary should not accept
accepts an arbitrary length and spits out a hex-encoded chunk of data. The arbitrary strings or numbers, such as manual derivation paths, and instead
program to convert that entropy into a seed is `keyfork-mnemonic-from-seed`. It should ask for values like "account index" and generate their own magic values
takes entropy from input and converts it into a seed. The combination of the if necessary.
two, generating entropy and converting it to a mnemonic, is managed through
Keyfork: `keyfork mnemonic generate`, which can also be used to offer more
options down the line, such as generating a mnemonic from tarot or playing
cards, or dice.
--- ---
Note: The following document is all proposed, and not yet implemented. Note: The following features are proposed, and may not yet be implemented.
## Features ## Features
* Modular * Modular
* Standalone binaries can derive/manage keys/config from bip32 root * Standalone binaries can derive/manage keys/config
* Modules handle use cases like ssh, pgp, webauthn, crypto-assets, etc * Modules handle use cases like ssh, pgp, webauthn, crypto-assets, etc
* Module contract is dead simple and can be written in any language * Module contract is dead simple and can be written in any language
* Recoverable * Recoverable
* Config file and 24 word mnemonic phrase to recover -all- keys * Config file and 24 word mnemonic phrase to recover *every* key
* Shard mechanism allows for "M-of-N" recovery of seed if lost
* Unpredictable * Unpredictable
* Generate a BIP39 phrase from OS entropy * Generate a BIP39 phrase from OS or physicalized entropy
* Take BIP39 passphrase from user supplied entropy * Provide and use BIP39 passphrase from user supplied entropy
* Read up on [https://milksad.info](milksad) to understand why this matters! * Read up on [https://milksad.info](milksad) to understand why this matters!
* Deterministic
* Given the same seed, repeated derivation requests will be reproducible
* Any secret data can be derived again at any point in the future
* Offline * Offline
* Will exit if network access is detected to force you to keep keys offline * Will exit if network access is detected to force you to keep keys offline
* Helps limit the risk of supply chain attacks * Helps limit the risk of supply chain attacks