first commit

README.md

@@ -0,0 +1,149 @@
+# 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.
+
+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
+    ```
+
+## Usage
+
+```
+keyfork generate [-c,--config=<file>]
+    Generate new mnemonic optionally public keys defined by config
+keyfork recover [-c,--config=<file>] [-a,--agent]
+    Recover keychain and optionally config defined pubkeys from mnemonic
+    Optionally run a daemon to supply keys to subcommands
+keyfork version
+	Show version information.
+keyfork help
+    Show this text.
+keyfork [command]
+    Commands receive bip32 root as stdin
+    Commands return output and config data as json over stdout back to keyfork
+keyfork [command] help
+    Show help for a particular sub-command
+```
+
+## Examples
+
+#### Generate a new mnemonic to write to paper
+
+```
+$ keyfork generate
+
+> milk sad wage cup reward umbrella raven visa give list decorate bulb gold raise twenty fly manual stand float super gentle climb fold park
+```
+
+#### Recover a mnemonic with a passphrase and spawn agent
+
+```
+$ keyfork recover --agent
+
+> mnemonic: ********
+> passphrase: ********
+
+```
+
+#### Derive deterministic PGP keychain from agent key in default "sq" path
+
+Requires ```keyfork-pgp``` binary in $PATH
+
+```
+$ keyfork pgp --format=sq
+$ sq decrypt secret.pgp
+```
+
+#### Install deterministic PGP subkeys from agent key to a smartcard
+
+Requires ```keyfork-pgp``` binary in $PATH
+
+```
+$ keyfork pgp install --device=nitrokey
+$ gpg --card-status
+```
+
+#### Install first deterministic PIV key from agent key to smartcard on slot 1
+
+Requires ```keyfork-piv``` binary in $PATH
+
+```
+$ keyfork piv install --device=yubikey --key=1 --slot=1
+
+> Management Key: ****
+> User Pin: ****
+> Admin Pin: ****
+
+$ ssh-keygen -D "$OPENSC_LIBS/opensc-pkcs11.so" -e
+```
+
+#### Derive first deterministic BIP44 address for Bitcoin Account 1
+
+Requires ```keyfork-bip44``` binary in $PATH
+
+```
+$ keyfork bip44 --path=bitcoin
+
+> m/44'/0'/0'/0/0: 12DefCMhYVv4sBQikyXKMciAoX2wgzhWqb
+```