From e36bbe5bbb9b51e7d79bf75ecb366421448726f7 Mon Sep 17 00:00:00 2001 From: ryan Date: Thu, 18 Jan 2024 00:04:11 -0500 Subject: [PATCH] docs: add chain of cryptographic operations to keyfork wizard docs --- docs/src/bin/keyfork/wizard/index.md | 36 ++++++++++++++++++++++++++-- 1 file changed, 34 insertions(+), 2 deletions(-) diff --git a/docs/src/bin/keyfork/wizard/index.md b/docs/src/bin/keyfork/wizard/index.md index 7596a12..68fc6e8 100644 --- a/docs/src/bin/keyfork/wizard/index.md +++ b/docs/src/bin/keyfork/wizard/index.md @@ -12,9 +12,40 @@ This command will factory-reset any smart cards plugged into the system. It is recommended to use smart cards dedicated to the purpose of seed recovery. +### Cryptography Usage + +This command makes use of the following cryptographic concepts at the following +steps: + +1. 256 bits of entropy are loaded from the system's secure entropy source. +2. The entropy is then converted to a [BIP-0032] seed by applying the + HmacSha512 function to the entropy. This creates 512 bits of data, where the + first 256 bits are considered the "seed" and the last 256 bits are + considered the root key's "chain code". +3. The seed is then derived using BIP-0032 along the path `m / pgp' / shrd' / + index'`, where the values "pgp" and "shrd" converted to bytes and cast to a + 32 bit integer, and the "index" is a numeric iterator `0..max`. BIP-0032 + uses HmacSha512 with the "chain code" of the previous depth, the private-key + bytes of the current extended private key, and the index, to derive a new + extended private key and a new chain code. +4. For each seed, four subkeys are also derived using the above mechanism, and + converted to an OpenPGP certificate using Ed25519 for signing keys and + Curve25519 for encryption keys - this transformation is done without any + modification of the underlying key data, it is a transformation of their + encoding. +5. The original entropy is then split using Shamir's Secret Sharing configured + with the values `threshold` and `max`. The share are referred to in + documentation as "shards". +6. The shards are each concatenated with some metadata (two bytes: the metadata + version and the `threshold` value) and encrypted to the previously-generated + Curve25519 OpenPGP key. +7. The OpenPGP certificates are serialized to a vector of bytes and encrypted + to every shardholder's Curve25519 OpenPGP encryption key. +8. All shards are written to the output file or standard output. + ### Arguments -`keyfork wizard generate-shard-secret --threshold=1 --max=3 --keys-per-shard=1` +`keyfork wizard generate-shard-secret --threshold=1 --max=3 --keys-per-shard=1 --output=shards.pgp` * `threshold`: The minimum amount of shardholders needed to recover the secret. @@ -30,4 +61,5 @@ shardholder. ### Output -An OpenPGP-encrypted Shard file. +An OpenPGP-encrypted Shard file, if not previously configured to be written to +a file using `--output`.