From 019e390b941c87763eebd562349473ced471b9ef Mon Sep 17 00:00:00 2001 From: ryan Date: Sat, 20 Jan 2024 01:17:32 -0500 Subject: [PATCH] keyforkd, keyfork-shard: add README.md --- crates/daemon/keyforkd/README.md | 36 ++++++++++++++++++++++++++++ crates/daemon/keyforkd/src/lib.rs | 15 +----------- crates/keyfork-shard/README.md | 40 +++++++++++++++++++++++++++++++ crates/keyfork-shard/src/lib.rs | 4 +--- 4 files changed, 78 insertions(+), 17 deletions(-) create mode 100644 crates/daemon/keyforkd/README.md create mode 100644 crates/keyfork-shard/README.md diff --git a/crates/daemon/keyforkd/README.md b/crates/daemon/keyforkd/README.md new file mode 100644 index 0000000..8d139fa --- /dev/null +++ b/crates/daemon/keyforkd/README.md @@ -0,0 +1,36 @@ +# The Keyfork Server + +The server uses a `keyfork_frame`'d `bincode`'d request+response format and can +be interacted with by using the `keyforkd_client` crate. + +All requests made to Keyfork are required to list at least two derivation +paths. This helps prevent cases where the master seed or the general protocol +seed are leaked by a client. An example is BIP-0044, where the path used is +`m/44'/0'` for Bitcoin, and often `m/44'/60'` is used for Ethereum. To prevent +an Ethereum wallet from deriving the Bitcoin coin seed, and to prevent leaking +the master seed in general, all requests must contain at least two paths. + +Additionally, this ensures that keys are not reused across separate purposes. +Because keys are required to have at least two indexes, they are drawn to the +pattern of using the first index as the key's purpose, such as `m/ pgp'` for +OpenPGP. + +## Usage + +The Keyfork server can be started by running the `keyfork recover` porcelain +binary or by running `keyforkd` directly and entering a mnemonic. Once started, +the Keyfork server will bind to a socket in `XDG_RUNTIME_DIR` by default, or +`KEYFORK_SOCKET_PATH` pointing directly to where a socket will be bound. Upon +the server's termination, the socket will be removed. The socket will not be +removed by default when the server is starting. + +Once started, the Keyfork server can be interacted with using the `keyfork +derive` subcommand or individual `keyfork-derive` commands, such as +`keyfork-derive-openpgp`. The former offers a more intuitive interface, but the +latter may offer a lower dependency surface. These clients will connect to the +server, typically using the `keyforkd-client` crate, and request a derived key. +Once the server has received the derivation request, the server will log the +request, as well as its best-effort guess on what path is being derived (using +the `keyfork-derive-path-data` crate), to inform the user of what keys are +requested. Once the server sends the client the new extended private key, the +client can then choose to use the key as-is, or derive further keys. diff --git a/crates/daemon/keyforkd/src/lib.rs b/crates/daemon/keyforkd/src/lib.rs index e17d5ce..4ea3a45 100644 --- a/crates/daemon/keyforkd/src/lib.rs +++ b/crates/daemon/keyforkd/src/lib.rs @@ -1,17 +1,4 @@ -//! ## The Keyfork server. -//! -//! The server uses a [`keyfork_frame`]'d [`bincode`]'d request+response format and can be -//! interacted with by using the `keyforkd_client` crate. -//! -//! All requests made to Keyfork are required to list at least two derivation paths. This helps -//! prevent cases where the master seed or the general protocol seed are leaked by a client. An -//! example is BIP-0044, where the path used is `m/44'/0'` for Bitcoin, and often `m/44'/60'` is -//! used for Ethereum. To prevent an Ethereum wallet from deriving the Bitcoin coin seed, and to -//! prevent leaking the master seed in general, all requests must contain at least two paths. -//! -//! Additionally, this ensures that keys are not reused across separate purposes. Because keys are -//! required to have at least two indexes, they are drawn to the pattern of using the first index -//! as the key's purpose, such as `m/ pgp'` for OpenPGP. +#![doc = include_str!("../README.md")] use std::{ collections::HashMap, diff --git a/crates/keyfork-shard/README.md b/crates/keyfork-shard/README.md new file mode 100644 index 0000000..e63faf7 --- /dev/null +++ b/crates/keyfork-shard/README.md @@ -0,0 +1,40 @@ +# Keyfork Shard + +Securing secrets using Shamir's Secret Sharing, an "M-of-N" secret recovery +mechanism used to split a secret into `n` encrypted parts, with `m` parts +required to restore the secret. + +## Shardfile Formats + +Currently, OpenPGP is the only supported format. Any mix of smartcards and +OpenPGP key files are supported. + +## Metadata + +Keyfork Shard stores some additional metadata inside the Shardfile to make +recombining secrets easier. This metadata currently includes the metadata +version (1) and the threshold required to recreate the secret (meaning you +don't need to remember the threshold!). + +## Command Line Usage + +The command to run to split and combine a secret is format-dependent, but will +often follow the format `keyfork-shard-split-` and +`keyfork-shard-combine-`. For this example, OpenPGP will be used, but +the flow will be similar for any format. Keyfork Shard expects the input to be +a hex-encoded secret. + +```sh +# Read our secret into a shell variable. +read secret + +# Shard our secret. +echo $secret | keyfork-shard-split-openpgp 3 5 keyring.pgp > shards.pgp + +# Forget our secret. +unset secret + +# Recreate our secret. Without specifying a keyring, we are prompted to use +# smartcards. +keyfork-shard-combine-openpgp shards.pgp +``` diff --git a/crates/keyfork-shard/src/lib.rs b/crates/keyfork-shard/src/lib.rs index 1ea977d..67f309c 100644 --- a/crates/keyfork-shard/src/lib.rs +++ b/crates/keyfork-shard/src/lib.rs @@ -1,6 +1,4 @@ -//! ## Keyfork Shard -//! -//! Utilities for securing secrets using Shamir's Secret Sharing. +#![doc = include_str!("../README.md")] use std::io::{stdin, stdout, Write};