public
/
keyfork
5
0
Fork 0
Code Issues 16 Pull Requests 1 Packages Projects Releases Wiki Activity

docs: add chain of cryptographic operations to keyfork wizard docs

This commit is contained in:
Ryan Heywood 2024-01-18 00:04:11 -05:00
parent 0cc47c7e93
commit e36bbe5bbb
Signed by: ryan
GPG Key ID: 8E401478A3FBEF72
1 changed files with 34 additions and 2 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

36
docs/src/bin/keyfork/wizard/index.md
View File

@ -12,9 +12,40 @@ This command will <b>factory-reset</b> any smart cards plugged into the system.
It is recommended to use smart cards dedicated to the purpose of seed recovery.
</div>
### 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`.