From 539027e3358231979a9ee7f64e9213f5d4df7f3b Mon Sep 17 00:00:00 2001 From: ryan Date: Mon, 8 Apr 2024 14:34:41 -0400 Subject: [PATCH] docs: add basic documentation on shard remote-decrypt protocol --- docs/src/SUMMARY.md | 1 + docs/src/dev-guide/shard-protocol.md | 26 ++++++++++++++++++++++++++ 2 files changed, 27 insertions(+) create mode 100644 docs/src/dev-guide/shard-protocol.md diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md index 06e7437..fc6ec56 100644 --- a/docs/src/SUMMARY.md +++ b/docs/src/SUMMARY.md @@ -33,3 +33,4 @@ - [Provisioners](./dev-guide/provisioners.md) - [Auditing Dependencies](./dev-guide/auditing.md) - [Entropy Guide](./dev-guide/entropy.md) +- [The Shard Protocol](./dev-guide/shard-protocol.md) diff --git a/docs/src/dev-guide/shard-protocol.md b/docs/src/dev-guide/shard-protocol.md new file mode 100644 index 0000000..0805640 --- /dev/null +++ b/docs/src/dev-guide/shard-protocol.md @@ -0,0 +1,26 @@ +# The Shard Protocol + +Keyfork Shard uses a single-handshake protocol to transfer encrypted shards. +The initial payload is generated by the program combining the shards, while the +response is generated by the program transport-encrypting the shards. + +## Combiner Payload + +The combiner payload consists of a 12-byte nonce and a 32-byte x25519 public +key. The payload is then either encoded to hex and displayed as a QR code, and +encoded as a mnemonic and printed on-screen. + +The transporter receives the 12-byte nonce and 32-byte x25519 key and generates +their own x25519 key. Using HKDF-Sha256 with no salt on the resulting key +generates the AES-256-GCM key used to encrypt the now-decrypted shard, along +with the received nonce. + +## Transporter Payload + +The transporter payload consists of a 32-byte x25519 public key and a 64-byte +"hunk". The hunk consists of the hunk version byte, a "threshold" byte, the +encrypted shard, and padding bytes. + +The combiner receives the 32-byte x25519 key and the 64-byte hunk, and uses the +same key derivation scheme as above to generate the decryption key. The +threshold byte is used to determine how many shares (in total) are needed.