first commit
This commit is contained in:
commit
96bcc189f1
GPG Key ID:
8E47A1EC35A1551D
|
|
@ -0,0 +1,161 @@
|
|||
# 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
|
||||
|
||||
### Blind Trust
|
||||
|
||||
> :warning: Before you copy/paste, note that these are /low/ security options
|
||||
|
||||
If you are on an untrusted machine and are only evaluating our tools, we offer
|
||||
easy low security install paths common in the industry.
|
||||
|
||||
Do note that any time you run an unverified binary off the internet you are
|
||||
giving a third party full permission to execute any code they want on your
|
||||
system. Github accounts, CDNs, and package repository accounts get compromised
|
||||
all the time.
|
||||
|
||||
## 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
|
||||
```
|
||||
Loading…
Reference in New Issue