From 155de0ce31900c8ff9e0d90873ba544acf72d2fd Mon Sep 17 00:00:00 2001 From: ryan Date: Wed, 10 Jan 2024 13:21:21 -0500 Subject: [PATCH] README: cleanup wordings --- README.md | 46 +++++++++++++++++++++++++--------------------- 1 file changed, 25 insertions(+), 21 deletions(-) diff --git a/README.md b/README.md index 3639596..f0ef6f5 100644 --- a/README.md +++ b/README.md @@ -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 phrase. -This toolchain uses 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 simply request deterministic data. +Keyfork can be used by organizations and solo users, for the purposes of +disaster recovery, cold storage, and reproducibility of private keys and secret +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 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 The `keyfork` binary is the most user-friendly interface for interacting with -the Keyfork toolchain. It offers commands that should not take any scriptable -input and should not produce any script-readable output. Such operations that -require script compatibility should be made into their own utilities, with the -higher level interface of interacting with them left solely to `keyfork`. - -For instance, the program to generate system entropy is `keyfork-entropy`. It -accepts an arbitrary length and spits out a hex-encoded chunk of data. The -program to convert that entropy into a seed is `keyfork-mnemonic-from-seed`. It -takes entropy from input and converts it into a seed. The combination of the -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. +the Keyfork toolchain. It offers commands that are intended to accept +human-readable input and produce human-readable output, and can be described as +a "Terminal User Interface" rather than a "Command Line Interface". An example +of a `keyfork` command would be `keyfork wizard generate-shard-secret`, which +will generate a secret, provision smart cards, and export the newly-generated +Shard file. Processes included in the `keyfork` binary should not accept +arbitrary strings or numbers, such as manual derivation paths, and instead +should ask for values like "account index" and generate their own magic values +if necessary. --- -Note: The following document is all proposed, and not yet implemented. +Note: The following features are proposed, and may not yet be implemented. ## Features * 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 * Module contract is dead simple and can be written in any language * 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 - * Generate a BIP39 phrase from OS entropy - * Take BIP39 passphrase from user supplied entropy + * Generate a BIP39 phrase from OS or physicalized entropy + * Provide and use BIP39 passphrase from user supplied entropy * 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 * Will exit if network access is detected to force you to keep keys offline * Helps limit the risk of supply chain attacks