commit 53d8452733d86cd12d20ca17168f612251fa0e74
parent 6fc60f4d1356139c36955681d291b88bf1cd94e9
Author: Martin Schanzenbach <schanzen@gnunet.org>
Date: Thu, 24 Oct 2024 09:59:25 +0200
Attempt some current protocol writeup
Diffstat:
1 file changed, 75 insertions(+), 6 deletions(-)
diff --git a/developers/apis/cong.rst b/developers/apis/cong.rst
@@ -63,18 +63,87 @@ Proposal:
We will have to replace the use of ``GNUNET_CRYPTO_symmetric_encrypt`` and
HMAC use in ``gnunet-service-core_kx.c`` including the respective keys and IVs.
-Handshake Protocol (Draft)
+Handshake Protocol (Current)
^^^^^^^^^^^^^^^^^^^^^^^^^^
-.. todo:: Discuss role selection
-
-This protocol is derived from `KEMTLS <https://thomwiggers.nl/publication/thesis/thesis.pdf>`_ (page 81ff).
+.. warning:: This is incomplete as the protocol is very messy and has around 6 RTTs
We assume that the peers have semi-*static* (as opposed to ephemeral) key pairs.
-Let (pk\ :sub:`I`,sk\ :sub:`I`) be the key pair of the initiator ``I`` and (pk\ :sub:`R`,sk\ :sub:`R`) the
-key pair of the receiver ``R``.
+Let (pk\ :sub:`A`,sk\ :sub:`A`) be the key pair of peer PID\ :sub:`A` and (pk\ :sub:`B`,sk\ :sub:`B`) the
+key pair of peer PID\ :sub:`B`.
+
+For any secure handshake protocol, we have to dermine an initiator and a receiver in the protocol.
+We use `GNUNET_CRYPTO_hash_cmp` to determine which peer is the receiver `R` and which peer the initiator `I`:
+
+.. code-block:: c
+
+ if (GNUNET_CRYPTO_hash_cmp (pk_A, pk_B))
+ {
+ pk_I = pk_A
+ pk_R = pk_B
+ }
+ else
+ {
+ pk_I = pk_B
+ pk_R = pk_A
+ }
+
+It is possible that the designated initiator does not initiate the handshake. After a pre-determined timeout,
+the respective other peer may initiate.
+
We assume that the initiator knows pk\ :sub:`R` (pre-distributed through HELLO, for example).
+``I`` and ``R`` calculate *before any connection attempt is made*:
+
+* (pk\ :sub:`e`,sk\ :sub:`e`) <- *KeyGen*\ ()
+
+.. danger:: Yes, both peers calculate *ephemeral* keys that are used for a set period of time in **all** handshakes.
+
+``I`` calculates:
+
+* ``EphemeralKeyMessage`` <- (pk\ :sub:`I`, pk\ :sub:`e`, creation_time, ...)
+* sig\ :sub:`e` <- *Sign*\ (sk\ :sub:`I`, ``EphemeralKeyMessage``)
+
+.. admonition:: ``I`` sends to ``R``
+
+ ``EphemeralKeyMessage``, sig\ :sub:`e`
+
+``R`` calculates:
+
+* assert *Verify*\ (pk\ :sub:`R`, ``EphemeralKeyMessage``, sig\ :sub:`e`)
+* Establish session keys through ECDH with *ephemeral* keys.
+* ``EphemeralKeyMessage`` <- (pk\ :sub:`R`, pk\ :sub:`e`, creation_time, ...)
+* sig\ :sub:`e` <- *Sign*\ (sk\ :sub:`R`, ``EphemeralKeyMessage``)
+
+.. admonition:: ``R`` sends to ``I``
+
+ ``EphemeralKeyMessage``, sig\ :sub:`e`
+
+``I`` calculates:
+
+* assert *Verify*\ (pk\ :sub:`R`, ``EphemeralKeyMessage``, sig\ :sub:`e`)
+* Establish session keys through ECDH with *ephemeral* keys.
+
+.. admonition:: ``I`` sends to ``R``
+
+ ``PingMessage``
+
+``R`` calculates:
+
+* Pong message
+
+.. admonition:: ``R`` sends to ``I``
+
+ ``PongMessage``
+
+
+Handshake Protocol (Draft)
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. info:: This protocol is derived from `KEMTLS <https://thomwiggers.nl/publication/thesis/thesis.pdf>`_ (page 81ff).
+
+
+The initiator selection remains unchanged from the above protocol.
``I`` calculates:
