keyforkd, keyfork-shard: add README.md

This commit is contained in:
Ryan Heywood 2024-01-20 01:17:32 -05:00
parent 2e3c387ae1
commit 019e390b94
Signed by: ryan
GPG Key ID: 8E401478A3FBEF72
4 changed files with 78 additions and 17 deletions

View File

@ -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.

View File

@ -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,

View File

@ -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-<format>` and
`keyfork-shard-combine-<format>`. 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
```

View File

@ -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};