docs: add basic documentation on shard remote-decrypt protocol

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)

docs/src/dev-guide/shard-protocol.md

@@ -0,0 +1,39 @@
+# 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.
+
+```
+[12-byte nonce | 32-byte public key]
+```
+
+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-padded encrypted "hunk". The hunk contains a version byte, a threshold
+byte, and the encrypted shard. The last byte of the 64-byte sequence is the
+total length of the encrypted hunk.
+
+```
+Handshake:
+[32-byte public key | 63-byte-padded encrypted hunk | 1-byte hunk length ]
+
+Hunk:
+[1-byte version | 1-byte threshold | variable-length shard ]
+```
+
+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.