docs: add basic documentation on shard remote-decrypt protocol

This commit is contained in:
Ryan Heywood 2024-04-08 14:34:41 -04:00
parent 089021a302
commit 539027e335
Signed by: ryan
GPG Key ID: 8E401478A3FBEF72
2 changed files with 27 additions and 0 deletions

View File

@ -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)

View File

@ -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.