keyforkd, keyfork-shard: add README.md

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.

crates/daemon/keyforkd/src/lib.rs

@@ -1,17 +1,4 @@
-//! ## The Keyfork server.
+#![doc = include_str!("../README.md")]
-//!
-//! 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.
 
 use std::{
     collections::HashMap,

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

crates/keyfork-shard/src/lib.rs

@@ -1,6 +1,4 @@
-//! ## Keyfork Shard
+#![doc = include_str!("../README.md")]
-//!
-//! Utilities for securing secrets using Shamir's Secret Sharing.
 
 use std::io::{stdin, stdout, Write};