keyforkd, keyfork-shard: add README.md
This commit is contained in:
parent
2e3c387ae1
commit
019e390b94
|
@ -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.
|
|
@ -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,
|
||||
|
|
|
@ -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
|
||||
```
|
|
@ -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};
|
||||
|
||||
|
|
Loading…
Reference in New Issue