commit 02885526b4353ecd96ee7990a2f0dedc7612ebca
parent 3971fd19d6add50b8d695b00c0e4186cf4ca096d
Author: Martin Schanzenbach <schanzen@gnunet.org>
Date: Sun, 30 Jul 2023 23:33:31 +0200
Some more documentation on UDP communicator
Diffstat:
1 file changed, 65 insertions(+), 18 deletions(-)
diff --git a/draft-gnunet-communicators.xml b/draft-gnunet-communicators.xml
@@ -200,11 +200,6 @@
not attempt to retransmit them.
</t>
</section>
- <section anchor="base_comms" numbered="true" toc="default">
- <name>Base communicators</name>
- <t>
- FIXME
- </t>
<section anchor="udp_comm" numbered="true" toc="default">
<name>UDP communicator</name>
<t>
@@ -244,11 +239,53 @@
This method of sending messages to a peer can be used indefinitely, but is ineffienct since for every
message, a new symmetric key must be established.
</t>
+ <section anchor="udp_key_schedule" numbered="true" toc="default">
+ <name>Key schedule</name>
+ <t>
+ Once a shared secret MSK is established through the Diffie-Hellman KEM,
+ symmetric keys are derived according to a key schedule from a 32-bit
+ sequence number seq (in network byte order).
+ </t>
+ <t>
+ The KID derivation uses a hash-based key derivation function (HKDF) as defined in
+ <xref target="RFC5869" />, using SHA-512 <xref target="RFC6234"/> for the extraction
+ phase and SHA-256 <xref target="RFC6234"/> for the expansion phase.
+ PRK_h is key material retrieved using an HKDF using the byte string
+ seq as salt and k as initial keying material.
+ key and initialization vector are the 256 + 96-bit HKDF expansion result.
+ The expansion information input is the string "UDP-IV-KEY":
+ </t>
+ <artwork name="" type="" align="left" alt=""><![CDATA[
+SetupCipher(MSK,SEQ):
+ PRK_h := HKDF-Extract (SEQ, MSK)
+ K,IV := HKDF-Expand (PRK_h, "UDP-IV-KEY", (256 + 96) / 8)
+ return K,IV
+ ]]></artwork>
<t>
+ With SetupCipher, a 256-bit AES key as well as a 96-bit IV for use in AES-GCM
+ are derived from the MSK and SEQ.
+ </t>
+ <t>
+ Each derived key is uniquely identified using a separately derived
+ 256-bit key ID (KID) derived in a similar fashion:
+ </t>
+ <artwork name="" type="" align="left" alt=""><![CDATA[
+DeriveKID(MSK,SEQ):
+ PRK_h := HKDF-Extract (SEQ, MSK)
+ KID := HKDF-Expand (PRK_h, "UDP-KID", 256 / 8)
+ return KID
+ ]]></artwork>
+ <t>
+ The sequence number SEQ for any shared secret is initially 0 and incremented
+ with each successive encryption (sent/received message).
+ </t>
+ </section>
+ <section anchor="udp_messages" numbered="true" toc="default">
+ <name>Message formats</name><t>
All metadata for headers is chosen such that they are indistinguishable from random.
For the use of (ephemeral) ECC public key material, this probably requires the use of additional randomization
techniques such as Elligator (TODO).
- There are three distinct message types that are sent and received by UDP communciators: KX, BOX, REKEY and BROADCAST.
+ There are three distinct message types that are sent and received by UDP communciators: KX, BOX, BROADCAST.
In any case, the common header is 32 + 16 bytes in length.
</t>
<figure anchor="figure_udp_initialkx" title="The binary representation of the initial key exchange packet.">
@@ -284,10 +321,6 @@
<dd>
A 128-bit GCM tag used to authenticate the ciphertext immediately following this KX.
</dd>
- <dt>REKEY</dt>
- <dd>
- A 128-bit rekey flag. If any bit is set, this indicates a rekey.
- </dd>
<dt>ENCRYPTED DATA</dt>
<dd>
The remaining data (as indicated by SIZE) is AES-GCM encrypted using the current session key and authenticated
@@ -296,9 +329,6 @@
</dd>
</dl>
<t>
- FIXME: Explain key schedule/KEM.
- </t>
- <t>
In order to prevent replay attacks for KX messages, the plaintext resulting from decryption of the ENCRYPTED DATA
in the KX message starts with a session-specific confirmation header:
</t>
@@ -425,6 +455,13 @@
A 256-bit random value.
</dd>
</dl>
+ <t>
+ Once a KX message is received and validated, the peer <bcp14>SHOULD</bcp14>
+ try to acknowledge (ACK) the established shared secret.
+ </t>
+ <t>
+ TODO UDPAck payload. TODO UDPRekey payload.
+ </t>
<figure anchor="figure_udp_box" title="The binary representation of the UDP Box.">
<artwork name="" type="" align="left" alt=""><