# keyfork # 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. 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. ## Dependency Policy Dependencies must not be added to core utilities such as seed generation and path derivation without a _really_ good reason we can't implement it ourselves, such as cryptography libraries. For instance, `keyfork-derive-util` _only_ utilizes cryptography libraries, `serde`, and `thiserror`, with the latter two being audited dependencies. Utilities such as forklets (applications that use derived data, such as an OpenPGP keychain generator) and the kitchen-sink `keyfork` utility may pull in additional dependencies _as needed_, but should strive to use the standard library as much as possible. To avoid code reuse, additional crates (such as the `smex` crate) may be used to share functionality 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. --- Note: The following document is all proposed, and not yet implemented. ## Features * Modular * Standalone binaries can derive/manage keys/config from bip32 root * 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 * Unpredictable * Generate a BIP39 phrase from OS entropy * Take BIP39 passphrase from user supplied entropy * Read up on [https://milksad.info](milksad) to understand why this matters! * Offline * Will exit if network access is detected to force you to keep keys offline * Helps limit the risk of supply chain attacks * Intended for use with QubesOS Vault VM, AirgapOS, etc * Private keys are installed to HSMs/TEEs for use by online machines ## Install These steps will allow you to prove that at least two Distrust engineers signed off on the produced binaries, signaling that they reproduced them from source code and got identical results, in addition to our usual two-party code review processes. This minimizes a single point of trust (and failure) in our binary release process. See the [Reproducible Builds](https://reproducible-builds.org/) project for more information on these practices. We use git for all development, releases, and signing. Unfortunately git has no native method for large file storage or multi-signature workflows so some git add-ons are required. To follow these steps please install [git-lfs][gl] and [git-sig][gs]. [gs]: https://git.distrust.co/public/git-sig [gl]: https://git-lfs.com 1. Clone repo ```sh git clone https://git.distrust.co/public/keyfork cd keyfork ``` 2. Review binary signatures ```sh git sig verify ``` Note: See Trust section below for expected keys/signers 3. Install binary ``` make install ``` ## Basic Usage ### Personal Setup On an airgapped system, run the following command to generate a BIP-0039 mnemonic encoding a generated seed: ```sh keyfork mnemonic generate ``` 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 > shards.pgp ``` 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 "Ryan Heywood (RyanSquared) " ``` ## Usage Detailed usage instructions can be found in the `keyfork-user-guide` mdBook, which can be opened in-browser by running `mdbook serve --open keyfork-user-guide`.