From f41fd18afb5838735d249c0cc1fda8f6a130ee05 Mon Sep 17 00:00:00 2001 From: ryan Date: Wed, 1 Nov 2023 21:21:26 -0500 Subject: [PATCH] keyfork: add docs, clean help output --- Cargo.lock | 48 ++++++++++++++++++++++++++++++++++--- keyfork/Cargo.toml | 2 +- keyfork/src/cli/mnemonic.rs | 7 ++++++ keyfork/src/cli/mod.rs | 4 ++-- keyfork/src/cli/shard.rs | 14 +++++++++-- 5 files changed, 67 insertions(+), 8 deletions(-) diff --git a/Cargo.lock b/Cargo.lock index 83f9db2..cb47f5e 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -327,6 +327,7 @@ dependencies = [ "anstyle", "clap_lex", "strsim", + "terminal_size", ] [[package]] @@ -828,6 +829,17 @@ dependencies = [ "yaml-rust", ] +[[package]] +name = "io-lifetimes" +version = "1.0.11" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "eae7b9aee968036d54dce06cebaefd919e4472e753296daccd6d344e3e2df0c2" +dependencies = [ + "hermit-abi", + "libc", + "windows-sys 0.48.0", +] + [[package]] name = "is-terminal" version = "0.4.9" @@ -835,7 +847,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "cb0889898416213fab133e1d33a0e5858a48177452750691bde3666d0fdbaf8b" dependencies = [ "hermit-abi", - "rustix", + "rustix 0.38.13", "windows-sys 0.48.0", ] @@ -1080,6 +1092,12 @@ version = "0.5.6" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "0717cef1bc8b636c6e1c1bbdefc09e6322da8a9321966e8928ef80d20f7f770f" +[[package]] +name = "linux-raw-sys" +version = "0.3.8" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ef53942eb7bf7ff43a617b3e2c1c4a5ecf5944a7c1bc12d7ee39bbb15e5c1519" + [[package]] name = "linux-raw-sys" version = "0.4.7" @@ -1604,6 +1622,20 @@ dependencies = [ "semver", ] +[[package]] +name = "rustix" +version = "0.37.25" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d4eb579851244c2c03e7c24f501c3432bed80b8f720af1d6e5b0e0f01555a035" +dependencies = [ + "bitflags 1.3.2", + "errno", + "io-lifetimes", + "libc", + "linux-raw-sys 0.3.8", + "windows-sys 0.48.0", +] + [[package]] name = "rustix" version = "0.38.13" @@ -1613,7 +1645,7 @@ dependencies = [ "bitflags 2.4.0", "errno", "libc", - "linux-raw-sys", + "linux-raw-sys 0.4.7", "windows-sys 0.48.0", ] @@ -1896,7 +1928,7 @@ dependencies = [ "cfg-if", "fastrand", "redox_syscall 0.3.5", - "rustix", + "rustix 0.38.13", "windows-sys 0.48.0", ] @@ -1911,6 +1943,16 @@ dependencies = [ "winapi", ] +[[package]] +name = "terminal_size" +version = "0.2.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8e6bf6f19e9f8ed8d4048dc22981458ebcf406d67e94cd422e5ecd73d63b3237" +dependencies = [ + "rustix 0.37.25", + "windows-sys 0.48.0", +] + [[package]] name = "thiserror" version = "1.0.49" diff --git a/keyfork/Cargo.toml b/keyfork/Cargo.toml index b415787..145881a 100644 --- a/keyfork/Cargo.toml +++ b/keyfork/Cargo.toml @@ -7,7 +7,7 @@ edition = "2021" [dependencies] keyfork-mnemonic-util = { version = "0.1.0", path = "../keyfork-mnemonic-util" } -clap = { version = "4.4.2", features = ["derive", "env"] } +clap = { version = "4.4.2", features = ["derive", "env", "wrap_help"] } thiserror = "1.0.48" smex = { version = "0.1.0", path = "../smex" } keyfork-plumbing = { version = "0.1.0", path = "../keyfork-plumbing" } diff --git a/keyfork/src/cli/mnemonic.rs b/keyfork/src/cli/mnemonic.rs index 685e3a2..7fd566e 100644 --- a/keyfork/src/cli/mnemonic.rs +++ b/keyfork/src/cli/mnemonic.rs @@ -118,6 +118,13 @@ impl MnemonicSeedSource { #[derive(Subcommand, Clone, Debug)] pub enum MnemonicSubcommands { /// Generate a mnemonic using a given entropy source. + /// + /// Mnemonics are a form of encoding a given form of entropy and are used to create a master + /// seed for BIP-0032 hierarchial derivation. The mnemonic is like the "password" for all of + /// Keyfork's derivations, and should be treated securely. This command provides a secure + /// method of generating a seed using system entropy, as well as various forms of loading + /// physicalized entropy into a mnemonic. The mnemonic should be stored in a safe location + /// (such as a Trezor "recovery seed card") and never persisted digitally. Generate { /// The source from where a seed is created. #[arg(long, value_enum, default_value_t = Default::default())] diff --git a/keyfork/src/cli/mod.rs b/keyfork/src/cli/mod.rs index 1c3ea6f..11134eb 100644 --- a/keyfork/src/cli/mod.rs +++ b/keyfork/src/cli/mod.rs @@ -17,10 +17,10 @@ pub enum KeyforkCommands { /// Mnemonic generation and persistence utilities. Mnemonic(mnemonic::Mnemonic), - /// Secret sharing utilities. + /// Splitting and combining secrets using Shamir's Secret Sharing. Shard(shard::Shard), - /// Keyforkd background daemon to manage seed creation. + /// Keyforkd background daemon to manage derivation. Daemon, } diff --git a/keyfork/src/cli/shard.rs b/keyfork/src/cli/shard.rs index cea6e9c..9337082 100644 --- a/keyfork/src/cli/shard.rs +++ b/keyfork/src/cli/shard.rs @@ -105,7 +105,12 @@ struct P256; #[derive(Subcommand, Clone, Debug)] pub enum ShardSubcommands { - /// Split a secret into multiple shares, using Shamir's Secret Sharing. + /// Split a hex-encoded secret from input into multiple shares, using Shamir's Secret Sharing. + /// + /// The shares are encrypted once per key, with keys discovered either on-system or by + /// prompting for hardware interactions. Metadata about decrypting keys is then stored and + /// encrypted to all keys, to ensure any key that holds a share can then be used to begin the + /// process of combining keys. Split { /// The amount of shares required to recombine a secret. #[arg(long)] @@ -119,7 +124,12 @@ pub enum ShardSubcommands { key_discovery: PathBuf, }, - /// Combine multiple shares into a secret + /// Combine multiple encrypted shares into a hex-encoded secret, printed to stdout. + /// + /// This command only accepts input from `keyfork shard split`, and is dependent on the format + /// used when splitting. Metadata is encrypted to all keys that may hold a share, so when using + /// hardware metadata discovery, any hardware key used to split may be used to decrypt metadata + /// used to combine. Combine { /// The amount of sharesr equired to recombine a secret. #[arg(long)]