commit 205389a1a4cfb0fd3b4c2d7af1dec42b04bfdabe
parent e2b781cee663d9d538e2dceb08716bad1346a7f0
Author: Martin Schanzenbach <schanzen@gnunet.org>
Date: Fri, 14 Jul 2023 18:36:46 +0200
some UDP communicator doc
Diffstat:
1 file changed, 31 insertions(+), 3 deletions(-)
diff --git a/developers/subsystems/transport-ng/transport-ng.rst b/developers/subsystems/transport-ng/transport-ng.rst
@@ -222,9 +222,9 @@ TRANSPORT service has to ask the communicator explicitly to retry.
If a communicator succeeds in establishing an outgoing connection for
transmission, or if a communicator receives an incoming bi-directional
connection, the communicator must inform the TRANSPORT service that a
-message queue (MQ) for transmission is now available. For that MQ, the
-communicator must provide the peer identity claimed by the other end, a
-human-readable address (for debugging) and a maximum transfer unit
+message queue (MQ) for transmission is now available.
+For that MQ, the communicator must provide the peer identity claimed by the other end.
+It must also provide a human-readable address (for debugging) and a maximum transfer unit
(MTU). A MTU of zero means sending is not supported, SIZE_MAX should be
used for no MTU. The communicator should also tell TRANSPORT what
network type is used for the queue. The communicator may tell TRANSPORT
@@ -256,3 +256,31 @@ transmitting backchannel messages, and TRANSPORT will not attempt to
retransmit them.
+UDP communicator
+^^^^^^^^^^^^^^^^
+
+The UDP communicator implements a basic encryption layer to protect from
+metadata leakage.
+The layer tries to establish a shared secret using an Elliptic-Curve Diffie-Hellman
+key exchange in which the initiator of a packet creates an ephemeral key pair
+to encrypt a message for the target peer identity.
+The communicator always offers this kind of transmission queue to a (reachable)
+peer in which messages are encrypted with dedicated keys.
+The performance of this queue is not suitable for high volume data transfer.
+
+If the UDP connection is bi-directional, or the TRANSPORT is able to offer a
+backchannel connection, the resulting key can be re-used if the recieving peer
+is able to ACK the reception.
+This will cause the communicator to offer a new queue (with a higher priority
+than the default queue) to TRANSPORT with a limited capacity.
+The capacity is increased whenever the communicator receives an ACK for a
+transmission.
+This queue is suitable for high-volume data transfer and TRANSPORT will likely
+prioritize this queue (if available).
+
+Communicators that try to establish a connection to a target peer authenticate
+their peer ID (public key) in the first packets by signing a monotonic time
+stamp, its peer ID, and the target peerID and send this data as well as the signature
+in one of the first packets.
+Receivers should keep track (persist) of the monotonic time stamps for each
+peer ID to reject possible replay attacks.
