commit 628bdd422dc5a99b63f610d23d2c160b56c7488a
parent 4fe187d4df863dcf3107330e0221353d08eea662
Author: Martin Schanzenbach <schanzen@gnunet.org>
Date: Thu, 27 Jul 2023 15:25:44 +0200
convert some existing texts
Diffstat:
1 file changed, 97 insertions(+), 2 deletions(-)
diff --git a/draft-gnunet-communicators.xml b/draft-gnunet-communicators.xml
@@ -131,7 +131,72 @@
<section anchor="overview" numbered="true" toc="default">
<name>Overview</name>
<t>
- FIXME
+ Each communicator must specify its (global) communication characteristics,
+ which for now only say whether the communication is reliable (e.g. TCP, HTTPS)
+ or unreliable (e.g. UDP, WLAN).
+ Each communicator must specify a unique address prex, or NULL if the
+ communicator cannot establish outgoing connections (for example because
+ it is only acting as a TCP server).
+ A communicator must tell TRANSPORT which addresses it is reachable under.
+ Addresses may be added or removed at any time.
+ A communicator may have zero addresses (transmission only).
+ Addresses do not have to match the address prefix.
+ </t>
+ <t>
+ TRANSPORT may ask a communicator to try to connect to another address.
+ TRANSPORT will only ask for connections where the address matches the
+ communicator’s address prefix that was provided when the connection was
+ established.
+ Communicators should then attempt to establish a connection.
+ No response is provided to TRANSPORT service on failure.
+ The TRANSPORT service has to ask the communicator explicitly to retry.
+ </t>
+ <t>
+ 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.
+ 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 anytime that the queue was deleted
+ and is no longer available.
+ </t>
+ <t>
+ The communicator API also provides for flow control.
+ First, communicators exhibit back-pressure on TRANSPORT:
+ the number of messages TRANSPORT may add to a queue for transmission will
+ be limited.
+ So by not draining the transmission queue, back-pressure is provided to
+ TRANSPORT.
+ In the other direction, communicators may allow TRANSPORT to give
+ back-pressure towards the communicator by providing a non-NULL
+ GNUNET_TRANSPORT_MessageCompletedCallback (FIXME generic API) argument to the
+ GNUNET_TRANSPORT_communicator_receive (FIXME generic API) function.
+ In this case, TRANSPORT will only invoke this function once it has
+ processed the message and is ready to receive more.
+ Communicators should then limit how much traffic they receive based on
+ this backpressure.
+ Note that communicators do not have to provide a
+ GNUNET_TRANSPORT_MessageCompletedCallback (FIXME generic API);
+ for example, UDP cannot support back-pressure due to the nature of the
+ UDP protocol.
+ In this case, TRANSPORT will implement its own TRANSPORT-to-TRANSPORT
+ flow control to reduce the sender’s data rate to acceptable levels.
+ </t>
+ <t>
+ TRANSPORT may notify a communicator about backchannel messages TRANSPORT
+ received from other peers for this communicator.
+ Similarly, communicators can ask TRANSPORT to try to send a backchannel
+ message to other communicators of other peers.
+ The semantics of the backchannel message are up to the communicators
+ which use them.
+ TRANSPORT may fail transmitting backchannel messages, and TRANSPORT will
+ not attempt to retransmit them.
</t>
</section>
<section anchor="base_comms" numbered="true" toc="default">
@@ -142,7 +207,37 @@
<section anchor="udp_comm" numbered="true" toc="default">
<name>UDP communicator</name>
<t>
- FIXME
+ 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.
+ </t>
+ <t>
+ 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).
+ </t>
+ <t>
+ 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.
+ </t>
+ <t>
+ FIXME: Handshake wire format, KX, Flow.
</t>
</section>
<section anchor="tcp_comm" numbered="true" toc="default">
