| Internet-Draft | The GNUnet communicators | August 2024 |
| Schanzenbach, et al. | Expires 24 February 2025 | [Page] |
This document contains the GNUnet communicator specification.¶
This document defines the normative wire format of communicator protocols, cryptographic routines and security considerations for use by implementers.¶
This specification was developed outside the IETF and does not have IETF consensus. It is published here to inform readers about the function of GNUnet communicators, guide future communicator implementations, and ensure interoperability among implementations including with the pre-existing GNUnet implementation.¶
This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.¶
Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.¶
Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."¶
This Internet-Draft will expire on 24 February 2025.¶
Copyright (c) 2024 IETF Trust and the persons identified as the document authors. All rights reserved.¶
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document.¶
This document defines the normative wire format of resource records, resolution processes, cryptographic routines and security considerations for use by implementers.¶
This specification was developed outside the IETF and does not have IETF consensus. It is published here to guide GNS implementers and to ensure interoperability among implementations.¶
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.¶
We use the notation from [RFC9180] and [LSD0011]. In addition, we define:¶
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.¶
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.¶
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.¶
The communicator API also provides for flow control. First, communicators exhibit backpressure on TRANSPORT: the number of messages TRANSPORT may add to a queue for transmission will be limited. So, by not draining the transmission queue, backpressure is provided to TRANSPORT. In the other direction, communicators may allow TRANSPORT to give backpressure towards the communicator by providing a non-NULL GNUNET_TRANSPORT_MessageCompletedCallback argument to the GNUNET_TRANSPORT_communicator_receive 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; for example, UDP cannot support backpressure 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.¶
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 who use them. TRANSPORT may fail to transmit backchannel messages, and TRANSPORT will not attempt to retransmit them.¶
GNUnet communicators utilize en Elligator KEM for the encoding and decoding the ephemeral public keys. While standard Diffie-Hellman-based KEMs securely establish a secret between two parties, an observer can easily identify the encapsulation as a public key. In the presence of an active attacker, this could lead to packet dropping based on this information, preventing communication between peers. The UDP and TCP communicators use the Elligator KEM defined in [LSD0011]. This leaves the attacker with the option to either do nothing or intercept all random-looking packets, thereby potentially disrupting a large part of today's internet communication.¶
We use the KEMs and their notations as defined in [RFC9180] and [LSD0011].¶
We use a hash-based key derivation function (HKDF) as defined in [RFC5869], using SHA-256 [RFC6234] for the extraction phase and SHA-256 [RFC6234] for the expansion phase. We derive the master secret as a uniform symmetric key from the X25519 result "Z" and the ephemeral public key "A" in a "HKDF-Extract" step and then derive context-specific keys through "HKDF-Expand" as needed.¶
Peer IDs in GNUnet are Ed25519 public keys as defined [RFC8032]. In order to use such keys in our X25519-based KEMs (including the Elligator KEM), those keys must be converted to Curve25519 public keys, which is generally possible.¶
The UDP communicator implements an encryption layer that protects both the payload and the communicator's specific metadata (not to be confused with the UDP header). In particular, any message sent by the communicator is indistinguishable from random payload to an outside observer, with the exception of broadcast messages.¶
For any new connection to a target peer, the communicator attempts to establish a shared secret using the KEM defined in Section 5.1. The communicator initiating the connection sends the resulting Elligator representative, the authentication tag and the encrypted data to the receiving peer. Since the GCM authentication tag and the encrypted data in the key exchange message also appear random, the entire message is computationally indistinguishable from a random byte stream. Independent of the payload, each message includes the sender's peer identity, a monotonic timestamp, and a signature over the session metadata. Receivers MUST keep track of the monotonic timestamps of key exchanges with each peer to prevent replay attacks. For each subsequent message the same procedure is used with a new encapsulation. While the communicator may always fall back to this type of encryption, it is inefficient for high-volume data transfer because a new key exchange is required for every message. However, sometimes we may have no other choice, for example, if there is only bi-directional connectivity to the receiving peer.¶
If the target peer is able to acknowledge the reception of a message, the employed key can be reused. Such acknowledgments can be sent either via a bi-directional UDP connection or a backchannel connection provided by TRANSPORT. This acknowledgment prompts the communicator to offer a new queue to TRANSPORT, which has a higher priority than the default queue but starts with limited capacity. The capacity increases whenever the communicator receives an acknowledgment for a transmission. This queue is suitable for high-volume data transfer, and TRANSPORT will prioritize it if available.¶
There are three distinct message types that are sent and received by UDP communicators: KX, BOX and BROADCAST. For KX and BOX messages, their metadata is chosen such that they are indistinguishable from random. This property does not hold for BROADCAST messages and is not necessary, as they are only sent within a local area network.¶
Independent of the type of message queue, a key exchange is initiated at least once by the sending peer.
In cases where the receiving peer cannot acknowledge the reception of messages, a key exchange is performed for every message.
Two key pairs are needed for the KEM: An ephemeral key pair generated as part of the encapsulation procedure
Encap(pkR) -> (MSK,enc) and the peer identity of the receiving communciator.
The algorithm in use for the KEM is DHKEM(X25519+Elligator, HKDF-SHA256) [LSD0011].
The peer identity of the receiving communicator is an Ed25519 public key pkRed.
In order to use it compliantly with a X25519-based DHKEM as defined in [LSD0011] and [RFC9180], the
curve point must first be converted from Edwards into its birationally equivalent Montgomery form
pkR.
The encapsulation enc is transferred via a key exchange (KX) message, as defined in Figure 1.¶
0 8 16 24 +-----+-----+-----+-----+-----+-----+-----+-----+ | ENC | | | | | | | | | | | | | | | +-----+-----+-----+-----+-----+-----+-----+-----+ | GCM TAG | | | | | | | +-----+-----+-----+-----+-----+-----+-----+-----+ / ENCRYPTED DATA / +-----+-----+-----+-----+-----+-----+-----+-----+
enc of the KEM.¶
In order to prevent replay attacks for KX messages, the plaintext resulting from decryption of the encrypted data MUST must start with a session-specific Confirmation header as defined in Figure 2. It includes the sender's peer identity and a monotonic timestamp, which the receiving peer MUST keep track of each peer identity to reject possible replay attacks.¶
0 8 16 24 32 40 48 56 +-----+-----+-----+-----+-----+-----+-----+-----+ | | | SENDER PEER ID | | | | | +-----+-----+-----+-----+-----+-----+-----+-----+ | | | SIGNATURE | | | | | | | | | | | | | +-----+-----+-----+-----+-----+-----+-----+-----+ | MONOTONIC TIMESTAMP | | | | | | | | | | | | | | | +-----+-----+-----+-----+-----+-----+-----+-----+ / PAYLOAD / +-----+-----+-----+-----+-----+-----+-----+-----+
pkSed).¶
The confirmation header also includes a signature over the session's metadata, which is signed with the corresponding private key of the sender's peer identity. The data format over which the signature is computed is defined in Figure 3¶
0 8 16 24 32 40 48 56 +-----+-----+-----+-----+-----+-----+-----+-----+ | SIZE | PURPOSE (0x0X) | +-----+-----+-----+-----+-----+-----+-----+-----+ | SENDER PEER ID | | | | | | | +-----+-----+-----+-----+-----+-----+-----+-----+ | RECEIVER PEER ID | | | | | | | +-----+-----+-----+-----+-----+-----+-----+-----+ | ENC | | | | | | | +-----+-----+-----+-----+-----+-----+-----+-----+ | MONOTONIC TIMESTAMP | | | | | | | | | | | | | | | +-----+-----+-----+-----+-----+-----+-----+-----+
pkSed).¶
pkRed).¶
enc of the KEM.¶
Upon receiving a KX message, the receiving peer decapsulates the secret key MSK using
MSK <- Decap(skR,enc), where skR is the X25519 private key derived from
its Ed25519 counterpart skRed.
This Decap(skR, enc) procedure is defined in [LSD0011].
Note that the exchange of the receiver peer identity is not within the scope of the UDP communicator's key
exchange and is already assumed to be known to the sending peer.
One way to exchange peer identities is through the UDP BROADCAST messages as described in
Section 6.5.¶
The MSK is then used together with a sequence number SEQ to derive symmetric encryption key K and initialization vector IV using the "SetupCipher" procedure outlined below. Both the sending and the receiving peer SHOULD store the master shared secret MSK and attribute it to the corresponding peer. In case of an acknowledgment from the receiving peer, the established MSK can be reused by iteratively increasing the sequence number SEQ for SetupCipher(MSK, SEQ).¶
Additional data might be inserted after the confirmation header as part of the encrypted data of the KX message. Padding may be necessary due to the use of AES-GCM. Once a KX message is received and validated, the peer SHOULD try to acknowledge the established MSK to switch to a stable session. The details about the acknowledgment process and subsequent message exchange can be found in Section 6.3.¶
Once a shared secret MSK is established through the Elligator KEM, a symmetric key and initialization vector are derived. According to a key schedule from a 32-bit sequence number SEQ (in network byte order) and the MSK. The initial value of the sequence number is 0.¶
SetupCipher(MSK,SEQ): K := HKDF-Expand (MSK, "gnunet-communicator-udp-key"||SEQ, 32) IV := HKDF-Expand (MSK, "gnunet-communicator-udp-iv"||SEQ, 12) return K,IV¶
SetupCipher returns a 256-bit AES key "K" as well as a 96-bit "IV" for use in AES-GCM.¶
Each derived key is uniquely identified using a separately derived 256-bit key ID (KID) derived in a similar fashion:¶
DeriveKID(MSK,SEQ): KID := HKDF-Expand (MSK, "gnunet-communicator-udp-kid"||SEQ, 32) return KID¶
The sequence number SEQ for any shared secret is initially 0 and incremented on the sender side for each successive encryption and on the receiver side for each decryption.¶
KX messages, as presented in Section 6.1, are sufficient for transferring arbitrary amounts of data. This way of communicating is slow due to the establishment of a shared secret for each message using asymmetric cryptography. The UDP communicator offers a faster way of communicating by reusing a shared secret. For this purpose, the receiver of a message SHOULD acknowledge the reception to signal the sender that the same shared secret can be reused. The sender can then use the acknowledged shared secret and increment the utilized sequence number for each subsequent message to derive new symmetric key material. These messages are sent as BOX messages, which incorporate a KID as defined in Section 6.2 to identify both the master shared secret and sequence number. The wire format of a BOX message is depicted in Figure 4.¶
0 8 16 24 +-----+-----+-----+-----+-----+-----+-----+-----+ | KEY ID | | | | | | | | | | | | | | | +-----+-----+-----+-----+-----+-----+-----+-----+ | GCM TAG | | | | | | | +-----+-----+-----+-----+-----+-----+-----+-----+ / ENCRYPTED DATA / +-----+-----+-----+-----+-----+-----+-----+-----+
An acknowledgment can be sent in various ways is ultimately decided by TRANSPORT. If the target peer can also reach the sending peer via UDP messages, both KX messages or BOX messages could be utilized to send the acknowledgment as their payload. TRANSPORT could also choose to utilize another communicator type to send the acknowledgment (backchannel). Either way, acknowledgments are always sent in form of an ACK header. The wire format of the ACK header can be seen in Figure 5.¶
0 16 +-----+-----+-----+-----+-----+-----+-----+-----+ | SIZE | TYPE (0x0X) | +-----+-----+-----+-----+-----+-----+-----+-----+ | SEQ ACK | +-----+-----+-----+-----+-----+-----+-----+-----+ | MSK HASH (fromerly CMAC) | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | +-----+-----+-----+-----+-----+-----+-----+-----+
To avoid having to acknowledge every single message individually, the sender of an acknowledgment can specify the allowed sequence number for the sender in the ACK header. The receiver MUST precalculate all derived keys and corresponding KIDs for which it has already sent ACKs. Consequently, for valid sequence numbers below the current ACK limit, KID should match one of the precalculated keys in the key cache, and the encrypted data can be decrypted. Otherwise, the message MUST be rejected.¶
Multiple shared secrets can be used simultaneously between the sending peer and target peer. Should the sending peer use up all acknowledgments for all its shared secrets, messages are sent through KX messages again.¶
The amount of data that can be encrypted with a shared secret MUST be limited. Before
the capacity of a shared secret is used up, the sender initiates rekeying by sending a new ephemeral public key
for a key exchange. As multiple shared secrets can be used simultaneously, rekeying doesn't necessarily delete the old shared secret if its
capacity is not yet reached. The ephemeral public key is sent encrypted in a Rekey header as part of the payload of BOX message. Because the
ephemeral public key is encrypted, there is no need to use Elligator's encoding function and we use the normal, unobfuscated
DHKEM(X25519, HKDF-SHA256). The wire format of the Rekey header can
be seen in Figure 6.¶
0 16 +-----+-----+-----+-----+-----+-----+-----+-----+ | SIZE | TYPE (0x0X) | +-----+-----+-----+-----+-----+-----+-----+-----+ | ENC | | | | | | | | | | | | | | | +-----+-----+-----+-----+-----+-----+-----+-----+
enc of the KEM.¶
Additional data might be inserted after the Rekey header as part of the encrypted data of the BOX message. Padding may be necessary due to the use of AES-GCM.¶
BROADCAST messages are sent by peers to announce their presence. Those messages are only distributed in the LAN and sent in cleartext.¶
0 8 16 24 32 40 48 56 +-----+-----+-----+-----+-----+-----+-----+-----+ | | | SENDER PEER ID | | | | | +-----+-----+-----+-----+-----+-----+-----+-----+ | | | SIGNATURE | | | | | | | | | | | | | +-----+-----+-----+-----+-----+-----+-----+-----+
pkSed).¶
0 8 16 24 32 40 48 56 +-----+-----+-----+-----+-----+-----+-----+-----+ | SIZE | PURPOSE (0x0X) | +-----+-----+-----+-----+-----+-----+-----+-----+ | SENDER PEER ID | | | | | | | +-----+-----+-----+-----+-----+-----+-----+-----+ | ADDRESS HASH | | | | | | | +-----+-----+-----+-----+-----+-----+-----+-----+
pkSed).¶
TCP communicators always establish an encrypted and bi-directional communication channel. For each direction of communication, a dedicated shared secret is used to both encrypt and authenticate messages. These shared secrets are exchanged during the initial handshake. After a certain amount of data has been transmitted, rekeying occurs to renew the key material. Note that the rekeying process is triggered individually for each communication direction.¶
To achieve a zero-plaintext design, we MUST use the mac-then-encrypt approach to hide the message size on the wire. Extra caution needs to be taken due to the vulnerability of the mac-then-encrypt design to padding oracle attacks. To mitigate this issue, the TCP communicator uses AES-CTR for encryption, which does not require padding. Additionally, the use of ephemeral keys combined with monotonic timestamps limits an attacker's ability to exploit the oracle, as replay attacks are prevented.¶
The main purpose of the handshake is to establish shared key material for each direction of the communication channel. The initiating TCP Communicator starts the handshake by sending an encapsulation from the Elligator KEM defined in Section 5.1.¶
The encapsulation MUST be directly followed by an encrypted TCP handshake message, as shown in Figure 9. In addition to the peer identity of the sender and a timestamp, it contains a nonce as a challenge for the receiving TCP communicator. All data is authenticated with a signature.¶
0 8 16 24 32 40 48 56 +-----+-----+-----+-----+-----+-----+-----+-----+ | SENDER PEER ID | | | | | | | +-----+-----+-----+-----+-----+-----+-----+-----+ | SIGNATURE | | | | | | | | | | | | | | | +-----+-----+-----+-----+-----+-----+-----+-----+ | MONOTONIC TIMESTAMP | +-----+-----+-----+-----+-----+-----+-----+-----+ | NONCE | | | | | | | +-----+-----+-----+-----+-----+-----+-----+-----+
pkSed).¶
The data scheme used for computing the signature is depicted in Figure 10.¶
0 8 16 24 32 40 48 56 +-----+-----+-----+-----+-----+-----+-----+-----+ | SIZE | PURPOSE (0x0X) | +-----+-----+-----+-----+-----+-----+-----+-----+ | SENDER PEER ID | | | | | | | +-----+-----+-----+-----+-----+-----+-----+-----+ | RECEIVER PEER ID | | | | | | | +-----+-----+-----+-----+-----+-----+-----+-----+ | REPRESENTATIVE | | | | | | | +-----+-----+-----+-----+-----+-----+-----+-----+ | MONOTONIC TIMESTAMP | | | | | | | | | | | | | | | +-----+-----+-----+-----+-----+-----+-----+-----+ | NONCE | | | | | | | +-----+-----+-----+-----+-----+-----+-----+-----+
Upon reception of the ephemeral public key, the receiving TCP communicator carries out the decapsulation step of the key exchange and retrieves the shared key material. The subsequently received TCP handshake message is then decrypted and verified. If the signature is invalid, the connection is dropped. In the case of a valid signature, the receiving TCP communicator sends its own TCP handshake message to establish shared key material for outgoing messages and also replies with an encrypted TCP handshake acknowledgment message as defined in Figure 11.¶
0 8 16 24 +-----+-----+-----+-----+-----+-----+-----+-----+ | SIZE | TYPE (0x0X) | +-----+-----+-----+-----+-----+-----+-----+-----+ | SENDER PEER ID | | | | | | | | | | | | | | | +-----+-----+-----+-----+-----+-----+-----+-----+ | RECEIVER PEER ID | | | | | | | | | | | | | | | +-----+-----+-----+-----+-----+-----+-----+-----+ | SIGNATURE | | | | | | | | | | | | | | | +-----+-----+-----+-----+-----+-----+-----+-----+ | MONOTONIC TIMESTAMP | | | +-----+-----+-----+-----+-----+-----+-----+-----+ | NONCE | | | | | | | | | | | | | | | +-----+-----+-----+-----+-----+-----+-----+-----+
The data scheme used for computing the signature for the acknowledgment message is depicted in Figure 12.¶
0 8 16 24 +-----+-----+-----+-----+-----+-----+-----+-----+ | SIZE | TYPE (0x0X) | +-----+-----+-----+-----+-----+-----+-----+-----+ | SENDER PEER ID | | | | | | | | | | | | | | | +-----+-----+-----+-----+-----+-----+-----+-----+ | RECEIVER PEER ID | | | | | | | | | | | | | | | +-----+-----+-----+-----+-----+-----+-----+-----+ | MONOTONIC TIMESTAMP | | | +-----+-----+-----+-----+-----+-----+-----+-----+ | NONCE | | | / / / / | | +-----+-----+-----+-----+-----+-----+-----+-----+
The initiating TCP communicator also replies with a TCP handshake acknowledgment message after receiving a valid TCP handshake message. Lastly, each party verifies both the signature and the challenge within the received TCP handshake acknowledgment message, thus completing the handshake.¶
During the initial handshake, each communication channel performs the Elligator KEM defined in Section 5.1. The resulting shared secret us used in an AES-CTR encryption with HMAC-SHA512. Subsequent key exchanges are performed with each rekeying. More about the initial handshake and rekeying can be found in Section 7.1 and Section 7.4, respectively.¶
Let (REC_SK, REC_ID) be the receiver peer's EdDSA key pair. The sender peer initiates the key exchange using the Elligator KEM from Section 5.1 resulting in an encapsulation and initial master secret key MSK. MSK is used to derive a symmetric encryption and HMAC key as well as an initialization vector using the procedure "SetupCipher":¶
SetupCipher(REC_ID, MSK): K := HKDF-Expand (MSK, "gnunet-communicator-tcp-key", 32) IV := HKDF-Expand (MSK, "gnunet-communicator-tcp-ctr, 16) K_mac := HKDF-Expand (MSK, "gnunet-communicator-tcp-hmac, 64) return K,IV,K_mac¶
Note that the initiating TCP communicator can immediately encrypt the first TCP handshake message when sending it. As soon as the receiving TCP communicator receives and decapsulates the representative, it can decrypt the following TCP handshake message. The same applies to the TCP handshake message sent by the receiving TCP communicator.¶
Once the handshake is completed, actual payloads can be exchanged bi-directionally using TCP BOX messages. A TCP Box message consists of a TCP BOX message, as defined in Figure 13, followed by the payload. Both parts are encrypted before being sent to the receiving peer.¶
TCP Box messages follow the mac-then-encrypt approach to hide the size of the payload and achieve a zero-plaintext design. The HMAC utilizes SHA512 as the underlying hash function and is ratcheted after each operation. Given the mac-then-encrypt approach, additional safeguards are needed to protect against Oracle padding attacks. Therefore, we MUST use a padding-free encryption scheme such as AES-CTR for encryption. Additionally, we restrict the attacker's ability to replay attacks by exchanging new key material after a randomly chosen amount of transferred data, as described in Section 7.4. The necessary key exchanges to establish the new key material are protected using monotonic timestamps.¶
0 8 16 24 +-----+-----+-----+-----+-----+-----+-----+-----+ | SIZE | TYPE (0x0X) | +-----+-----+-----+-----+-----+-----+-----+-----+ | HASHCODE | | | | | | | | | | | | | | | +-----+-----+-----+-----+-----+-----+-----+-----+
After each key exchange, up to 400 MB of data is transferred until rekeying is triggered by the sender of the communication direction. The actual amount of transferred data SHOULD be chosen randomly. If the chosen byte quantity is not reached after one day, rekeying is set off anyway.¶
The receiving communicator is signaled about a rekeying through the dispatch of a TCP Rekey message, as defined in Figure 14. The message MUST be encrypted with the current key. Due to the encryption of the message, the encoding of the new ephemeral public key with Elligator is not needed. Similarly to the initial handshake, the ephemeral public key is used to perform a key exchange from which new key material for the encryption and authentication code scheme is derived. For further details, please refer to Section 7.2. Note that the rekeying process doesn't involve an acknowledgment by the receiver of a TCP Rekey message. So the sender might send new payload encrypted by the new key right after sending the TCP Rekey message.¶
0 8 16 24 +-----+-----+-----+-----+-----+-----+-----+-----+ | SIZE | TYPE (0x0X) | +-----+-----+-----+-----+-----+-----+-----+-----+ | HASHCODE | | | | | | | | | | | | | | | +-----+-----+-----+-----+-----+-----+-----+-----+ | ENC | | | | | | | | | | | | | | | +-----+-----+-----+-----+-----+-----+-----+-----+ | SIGNATURE | | | | | | | | | | | | | | | +-----+-----+-----+-----+-----+-----+-----+-----+ | MONOTONIC TIMESTAMP | | | +-----+-----+-----+-----+-----+-----+-----+-----+
enc of the KEM.¶
0 8 16 24 32 40 48 56 +-----+-----+-----+-----+-----+-----+-----+-----+ | SIZE | PURPOSE (0x0X) | +-----+-----+-----+-----+-----+-----+-----+-----+ | SENDER PEER ID | | | | | | | +-----+-----+-----+-----+-----+-----+-----+-----+ | RECEIVER PEER ID | | | | | | | +-----+-----+-----+-----+-----+-----+-----+-----+ | ENC | | | | | | | +-----+-----+-----+-----+-----+-----+-----+-----+ | MONOTONIC TIMESTAMP | | | | | | | | | | | | | | | +-----+-----+-----+-----+-----+-----+-----+-----+
pkSed).¶
pkRed).¶
enc of the KEM.¶
The HTTP/3 [RFC9114] communicator operates over a bidirectional communication channel, with the client initiating the connection and the server on the receiving end. Once the connection is successfully established, messages are transmitted via POST and GET requests, and all communication is secured using TLS.¶
Upon successfully establishing an HTTP/3 connection, the client MUST immediately transmit
its PeerIdentity in a POST.
The server will store this PeerIdentity to identify the client.
Following this exchange, data exchange between the client and server can proceed.¶
When the client needs to send a message, it uses a POST request to transmit the data to the server. While the server cannot initiate messages independently, it can include data in its response to a client's POST request.¶
To enable the server to proactively send data when the client has no data to transmit, long polling is used. The client sends GET requests to the server, which MAY not immediately respond but instead sets a timer for each request. The server responds either when the timer expires or when there is data to send. Upon receiving a response, the client immediately sends a new GET request to maintain an adequate number of long polling requests with the server.¶
0 8 16 24 32 40 48 56 +-----+-----+-----+-----+-----+-----+-----+-----+ | SIZE | TYPE (0x0X) | +-----+-----+-----+-----+-----+-----+-----+-----+ | MESSAGE | | | | | | | +-----+-----+-----+-----+-----+-----+-----+-----+
Example POST:¶
:method: POST :scheme: https :authority: PEER'S IP ADDRESS :path: / content-type: application/octet-stream content-length: LENGTH OF MESSAGE¶
If server no data to send it will respond with HTTP status OK (200).
If server has data to send it will respond with HTTP status OK and
a response body with a message (Figure 16) and
content type application/octet-stream¶
GET request example (long polling):¶
:method: GET :scheme: https :authority: PEER'S IP ADDRESS :path: /¶
If server no data to send and the long poll times out it will
respond with status 204.
If server has data to send it will respond with HTTP status OK (200)
a response body with a message (Figure 16) and
content type application/octet-stream.¶
The public keys in the certificates in use as part of the TLS handshake are not verified or evaluated against a trust store. The initial message by the initiating peer (the HTTP/3 client) will contain the peer identity. In the future, the peer identity should be part of the TLS handshake instead.¶
Communicators use a modified version of the standard X25519 key exchange described in section 6.1 of [RFC7748]. It deviates in that we use the Ed25519 key pair "x","X = x*G" of the peer identity as X25519 scalars and curve points, respectively. The safety of this use of a KEM has been investigated by [T21].¶
TRANSPORT API: GNUNET_TRANSPORT_MessageCompletedCallback, GNUNET_TRANSPORT_communicator_receive, and GNUNET_TRANSPORT_MessageCompletedCallback should follow a generic API for all communicator types.¶
UDP Communicator: RTT (Round-Trip Time) measurement is missing. Values such as the number of shared secrets could be adapted based on the RTT.¶
TCP Communicator: Currently, the only sanity check for a valid TCP handshake message is the verification of the signature. Additional checks, such as verifying the sender's peer identity, are needed. The use of the mac-then-encrypt approach within the TCP BOX messages should be analyzed further, specifically regarding padding-oracle attacks.¶