# 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
```