commit 436d55854c3265822e462e39dabd3ab949354026
parent d69bd374691ad3e9d3438002cbf189e7dfb63d97
Author: Martin Schanzenbach <schanzen@gnunet.org>
Date: Wed, 23 Oct 2024 18:08:24 +0200
prettify
Diffstat:
1 file changed, 64 insertions(+), 67 deletions(-)
diff --git a/developers/apis/cong.rst b/developers/apis/cong.rst
@@ -82,103 +82,100 @@ We assume that the initiator knows pk\ :sub:`R` (pre-distributed through HELLO,
* (ss\ :sub:`R`,c\ :sub:`R`) <- *Encaps*\ (pk\ :sub:`R`)
* **ES** <- *HKDF-Extract*\ (ss\ :sub:`R`, 0)
* **ETS** <- *HKDF-Expand*\ (**ES**, ``"early data"``, ``InitiatorHello``)
+* ``InitiatorCert`` <- *Enc*\ (**ETS**, cert [pk\ :sub:`I`])
+* ``InitiatorHello`` <- (pk\ :sub:`e`, c\ :sub:`R`, H(pk\ :sub:`R`), r\ :sub:`I`, ``InitiatorCert``, [SupportedAlgs,Services,Version])
-``I`` sends to ``R`` (0.5 RTT):
+.. admonition:: ``I`` sends to ``R``
-* ``InitiatorHello``:
+ ``InitiatorHello``
- * pk\ :sub:`e`
- * c\ :sub:`R`
- * H(pk\ :sub:`R`) ?
- * Supported algs/services?
- * r\ :sub:`I`?
+.. note:: We may encode capabilities/supported class in ``InitiatorCert``'s cert. We do not want to use X.509 here, probably.
-.. note:: Unclear to me if the need the nonce r or the hash of the receiver pk
+``R`` calculates:
+* Decrypt ``InitiatorCert``:
-* ``InitiatorCert``:
+ * (ss\ :sub:`R`) <- Decaps(sk\ :sub:`R`, c\ :sub:`R`)
+ * **ES** <- *HKDF-Extract*\ (ss\ :sub:`R`, 0)
+ * **ETS** <- *HKDF-Expand*\ (**ES**, "early data", ``InitiatorHello``)
+ * cert [pk\ :sub:`I`] <- *Dec*\ (**ETS**, ``InitiatorCert``)
- * *Enc*\ (**ETS**, cert [pk\ :sub:`I`])
-.. note:: We may encode capabilities/supported class in the *cert*
+* Setup Master Secret:
-``R`` calculates:
+ * **dES** <- *HKDF-Expand*\ (**ES**, "derived", ``NULL``)
+ * (ss\ :sub:`e`,c\ :sub:`e`) <- *Encaps*\ (pk\ :sub:`e`)
+ * **HS** <- *HKDF-Extract*\ (ss\ :sub:`e`, **dES**)
+ * **dHS** <- *HKDF-Expand*\ (**HS**, "derived", ``NULL``)
+ * (ss\ :sub:`I`,c\ :sub:`I`) <- ``Encaps``\ (pk\ :sub:`I`)
+ * **MS** <- *HKDF-Extract*\ (ss\ :sub:`I`, **dHS**)
-* (ss\ :sub:`R`) <- Decaps(sk\ :sub:`R`, c\ :sub:`R`)
-* **ES** <- *HKDF-Extract*\ (ss\ :sub:`R`, 0)
-* **ETS** <- *HKDF-Expand*\ (**ES**, "early data", ``InitiatorHello``)
-* **dES** <- *HKDF-Expand*\ (**ES**, "derived", ``NULL``)
-* (ss\ :sub:`e`,c\ :sub:`e`) <- *Encaps*\ (pk\ :sub:`e`)
-* **HS** <- *HKDF-Extract*\ (ss\ :sub:`e`, **dES**)
-* **IHTS** <- *HKDF-Expand*\ (**HS**, "i hs traffic", ``InitiatorHello...ReceiverHello``)
-* **RHTS** <- *HKDF-Expand*\ (**HS**, "r hs traffic", ``InitiatorHello...ReceiverHello``)
-* **dHS** <- *HKDF-Expand*\ (**HS**, "derived", ``NULL``)
-* cert [pk\ :sub:`I`] <- *Dec*\ (**ETS**, ``InitiatorCert``)
-* (ss\ :sub:`I`,c\ :sub:`I`) <- ``Encaps``\ (pk\ :sub:`I`)
-* **MS** <- *HKDF-Extract*\ (ss\ :sub:`I`, **dHS**)
-* fk\ :sub:`I` <- *HKDF-Expand*\ (**MS**, "i finished", ``NULL``)
-* fk\ :sub:`R` <- *HKDF-Expand*\ (**MS**, "r finished", ``NULL``)
-* ``RF`` <- *HMAC*\ (fk\ :sub:`R`, ``InitiatorHello...ReceiverKemCiphertext``)
-* **RATS** <- *HKDF-Expand*\ (**MS**, "r ap traffic", ``InitiatorHello...ReceiverFinished``)
-* ``IF`` <- *HMAC*\ (fk\ :sub:`I`, ``InitiatorHello...ReceiverFinished``)
+* Build ``ReceiverFinished`` and ``InitiatorFinished`` plain texts:
-``R`` sends to ``I`` (0.5 RTT):
+ * fk\ :sub:`I` <- *HKDF-Expand*\ (**MS**, "i finished", ``NULL``)
+ * fk\ :sub:`R` <- *HKDF-Expand*\ (**MS**, "r finished", ``NULL``)
+ * ``RF`` <- *HMAC*\ (fk\ :sub:`R`, ``InitiatorHello...ReceiverKemCiphertext``)
+ * ``IF`` <- *HMAC*\ (fk\ :sub:`I`, ``InitiatorHello...ReceiverFinished``)
-* ``ReceiverHello``
+* Derive Traffic Encryption Keys:
- * c\ :sub:`e` to ``I``
- * r\ :sub:`R`?
- * Selected algs here?
-* EncryptedExtensions
+ * **IHTS** <- *HKDF-Expand*\ (**HS**, "i hs traffic", ``InitiatorHello...ReceiverHello``)
+ * **RHTS** <- *HKDF-Expand*\ (**HS**, "r hs traffic", ``InitiatorHello...ReceiverHello``)
+ * **RATS** <- *HKDF-Expand*\ (**MS**, "r ap traffic", ``InitiatorHello...ReceiverFinished``)
- * *Enc*\ (**SHTS**, SupportedAlgs/Services?)
-* ``ReceiverKemCiphertext``
+* Encrypt messages:
- * *Enc*\ (**SHTS**, c\ :sub:`I`)
-* ``ReceiverFinished``
+ * ``ReceiverHello`` <- (c\ :sub:`e`, r\ :sub:`R`, [SelectedAlgs])
+ * (Optional) ``EncryptedExtensions`` <- Enc*\ (**SHTS**, SupportedAlgs/Services?)
+ * ``ReceiverKemCiphertext`` <- *Enc*\ (**SHTS**, c\ :sub:`I`)
+ * ``ReceiverFinished`` <- *Enc*\ (**RHTS**, ``RF``) (TLS1.3-style explicit authentication of receiver after 1RTT!)
- * *Enc*\ (**RHTS**, ``RF``) (TLS1.3-style explicit authentication of receiver after 1RTT!)
-* Payload:
+.. admonition:: ``R`` sends to ``I`` (0.5 RTT):
- * Payload can be sent encrypted using **RATS**.
+ ``ReceiverHello``, ``EncryptedExtensions``, ``ReceiverKemCiphertext``, ``ReceiverFinished``
+.. note:: From now on, application payload can be sent encrypted using **RATS**.
``I`` computes:
-* (ss\ :sub:`e`) <- *Decaps*\ (sk\ :sub:`e`, c\ :sub:`e`)
-* **dES** <- *HKDF-Expand*\ (**ES**, ``"derived"``, ``NULL``)
-* **HS** <- *HKDF-Extract*\ (ss\ :sub:`e`, dES)
-* **IHTS** <- *HKDF-Expand*\ (**HS**, "i hs traffic", ``InitiatorHello...ReceiverHello``)
-* **RHTS** <- *HKDF-Expand*\ (**HS**, "r hs traffic", ``InitiatorHello...ReceiverHello``)
-* **dHS** <- *HKDF-Expand*\ (**HS**, "derived", ``NULL``)
-* (ss\ :sub:`I`) <- *Decaps*\ (sk\ :sub:`I`, c\ :sub:`I`)
-* **MS** <- *HKDF-Extract*\ (ss\ :sub:`I`, **dHS**)
-* fk\ :sub:`I` <- *HKDF-Expand*\ (**MS**, "i finished", NULL)
-* fk\ :sub:`R` <- *HKDF-Expand*\ (**MS**, "r finished", NULL)
-* ``RF`` <- *Dec*\ (RHTS, ``ReceiverFinished``)
-* assert *HMAC*\ (fk\ :sub:`R`, ``InitiatorHello...ReceiverKemCiphertext``) == ``RF``
-* **RATS** <- *HKDF-Expand*\ (**MS**, "r ap traffic", ``InitiatorHello...ReceiverFinished``)
-* ``IF`` <- *HMAC*\ (fk\ :sub:`I`, ``InitiatorHello...ReceiverFinished``)
-* **IATS** <- *HKDF-Expand*\ (**MS**, "i ap traffic", ``InitiatorHello...InitiatorFinished``)
+* Setup Master Secret:
-``I`` sends to ``R`` (1.5 RTT):
+ * (ss\ :sub:`e`) <- *Decaps*\ (sk\ :sub:`e`, c\ :sub:`e`)
+ * **dES** <- *HKDF-Expand*\ (**ES**, ``"derived"``, ``NULL``)
+ * **HS** <- *HKDF-Extract*\ (ss\ :sub:`e`, dES)
+ * **dHS** <- *HKDF-Expand*\ (**HS**, "derived", ``NULL``)
+ * (ss\ :sub:`I`) <- *Decaps*\ (sk\ :sub:`I`, c\ :sub:`I`)
+ * **MS** <- *HKDF-Extract*\ (ss\ :sub:`I`, **dHS**)
-* ``InitiatorFinished``
-
- * *Enc*\ (**IHTS**, ``IF``)
+* Derive Traffic Encryption Keys:
+
+ * **IHTS** <- *HKDF-Expand*\ (**HS**, "i hs traffic", ``InitiatorHello...ReceiverHello``)
+ * **RHTS** <- *HKDF-Expand*\ (**HS**, "r hs traffic", ``InitiatorHello...ReceiverHello``)
+ * **IATS** <- *HKDF-Expand*\ (**MS**, "i ap traffic", ``InitiatorHello...InitiatorFinished``)
+ * **RATS** <- *HKDF-Expand*\ (**MS**, "r ap traffic", ``InitiatorHello...ReceiverFinished``)
-* Payload
+* Build ``ReceiverFinished`` and ``InitiatorFinished`` plain texts:
- * Payload can be sent encrypted using **IATS**.
- * Received payload can be decrypted using **RATS**.
+ * fk\ :sub:`I` <- *HKDF-Expand*\ (**MS**, "i finished", NULL)
+ * ``IF`` <- *HMAC*\ (fk\ :sub:`I`, ``InitiatorHello...ReceiverFinished``)
+ * fk\ :sub:`R` <- *HKDF-Expand*\ (**MS**, "r finished", NULL)
+ * ``RF`` <- *Dec*\ (RHTS, ``ReceiverFinished``)
+ * assert *HMAC*\ (fk\ :sub:`R`, ``InitiatorHello...ReceiverKemCiphertext``) == ``RF``
+
+* ``InitiatorFinished`` <- *Enc*\ (**IHTS**, ``IF``)
+
+.. admonition:: ``I`` sends to ``R`` (1.5 RTT):
+
+ ``InitiatorFinished``
+
+.. attention:: From now on, application payload can be sent encrypted using **IATS**. Received payload can be decrypted using **RATS**.
``R`` computes:
-* IATS <- *HKDF-Expand*\ (**MS**, "i ap traffic", ``InitiatorHello...InitiatorFinished``)
-* Payload
+* **IATS** <- *HKDF-Expand*\ (**MS**, "i ap traffic", ``InitiatorHello...InitiatorFinished``)
- * Received payload can be decrypted using **IATS**.
+.. attention:: From now on, application payload can be decrypted using **IATS**.
Glossary:
