Internet-Draft The GNUnet communicators July 2024
Schanzenbach, et al. Expires 11 January 2025 [Page]
Workgroup:
Independent Stream
Internet-Draft:
draft-gnunet-communicators-00
Published:
Intended Status:
Informational
Expires:
Authors:
M. Schanzenbach
Fraunhofer AISEC
C. Grothoff
Berner Fachhochschule
P. Fardzadeh
Technischen Universität München

The GNUnet communicators

Abstract

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.

Status of This Memo

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 11 January 2025.

Table of Contents

1. Introduction

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 implementers of GNS and to ensure interoperability among implementations.

1.1. Requirements Notation

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.

2. Terminology

Communicator
What is a communicator?

3. Overview

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 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.

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.

4. Cryptographic primitives

4.1. Key generation

Let "KeyGenEd25519() -> (x,X)" denote a function that produces an Ed25519 key pair as defined in [RFC8032]. Let "KeyGenElligator() -> (x,X)" denote a function that produces a Curve25519 key pair suitable for Elligator obfuscations which we will define in the following.

GNUnet communicators utilize Elligator for the encoding and decoding of the ephemeral public keys described in Section 5 of [BHKL13]. The general idea when generating an Elligator key pair is is to create both a random high-order curve point and a low-order curve point. Adding them together results in a curve point that is evenly distributed on the whole Curve25519. Not all Curve25519 points are suitable for use with Elligator. In particular, not all Curve25519 points have the property that the Elligator encoding and subsequent decoding result in the original point (See Section 8.2 for details). To create a Curve25519 point that can be used with Elligator, one needs to find a curve point for which this property holds. One heurisitic is to generate random key pairs until one such point is found.

Let G be the generator of the prime order group of Ed25519, H the generator of the low order subgroup of Ed25519 and EdToCurve() a function which converts Ed25519 points to their corresponding Curve25519 points. We define "KeyGenElligator" as follows:

KeyGenElligator():
  VALID := 0
  while(!VALID):
    x := random(256)
    x[0] &= 248
    x[31] &= 127
    x[31] |= 64
    E_high := x * G
    E_low := (x mod 8) * H
    E := E_high + E_low
    X := EdToCurve(E)
    if ElligatorDec(ElligatorEnc(X)) == X:
      return (x,X)

"ElligatorEnc()" and "ElligatorDec()" are the required encoding and decoding functions to obfuscate a curve point and are are defined in the following. The obfuscated curve point is called the Elligator "Representative". Let A and P be the parameters for Curve25519 as specified in section 4.1 of [RFC7748]. Further, let X be any valid x-coordinate of a Curve25519 point, sqrt() a function which calculates the square root of the finite field element, U the number sqrt(-1) which is a non-quadratic number in the finite field, and L() a function which computes the legendre symbol of a field element. As each of the field elements have two roots, we need to define the notion of negative and non-negative numbers. This is especially important for the sqrt() function. A straightforward choice is to define the set {0,..., (P - 1) / 2} as set of all non-negative numbers. The encoding function algorithm is:

ElligatorEnc(X):
  B := random(1)
  if B == 1:
    REPR :=  sqrt(-X / ((X + A) * U))
  else:
    REPR :=  sqrt(-(X + A) / (U * X))
  return REPR

The corresponding decoding agorithm is:

ElligatorDec(REPR):
  V := -A / (1 + U * REPR^2)
  E := L(V^3 + A * V^2 + V)
  X := E * V - (1 - E)(A / 2)
  return X

4.2. Key derivation

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 define the key derivation function (KDF) used to derive a uniform symmetric key from the X25519 result "Z" and the ephemeral public key "A":

KDF(A,Z):
  PRK_h := HKDF-Extract (0, A||Z)
  MSK := HKDF-Expand (PRK_h, "gnunet-ed25519-x25519-ecdh", (512) / 8)
  return MSK

4.3. Key encapsulation

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 the following to produce random-looking encapsulations (referred to as a "representative"). 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.

Let G be the basepoint of Curve25519, EdToCurve() a function which converts Ed25519 points to their corresponding Curve25519 points, ElligatorEnc() Elligator's encoding function, ElligatorDec() Elligator's decoding function, "X" the receiver's peer identity (a 256-bit EdDSA public key), "x" the corresponding secret key, "A" an ephemeral public key (256-bit Curve25519 public key) and "a" the corresponding 256-bit ephemeral secret key. Observe that:

(x, X) := KeyGenEd25519()
(a, A) := KeyGenElligator()
Z := X25519(a, EdToCurve(X)) = X25519(x, A)

We can then define the KEM:

EncapsElligator(X):
  A,MSK := Encaps(X)
  REPR := ElligatorEnc(A)
  return REPR, MSK

Encaps(X):
  (a, A) := KeyGenElligator()
  Z := X25519(a, EdToCurve(X))
  MSK := KDF(A,Z)
  return A, MSK
DecapsElligator(x, REPR):
  A := ElligatorDec(REPR)
  return Decaps(x, A)

Decaps(x, A):
  Z := X25519(x, A)
  MSK := KDF(A,Z)
  return MSK

More details about the construction of the representative and Elligator's usage can be found in Section 4.1.

5. UDP communicator

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 4.3. 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 meta data. 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 conducted 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. (FIXME: not the case for BROADCAST).

5.1. Key exchange

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 "EncapsElligator" and the peer identity of the receiving communciator. The encapsulation is transfered via a key exchange (KX) message as defined in Figure 1.

0           8           16          24
+-----+-----+-----+-----+-----+-----+-----+-----+
|                REPRESENTATIVE                 |
|                                               |
|                                               |
|                                               |
|                                               |
|                                               |
|                                               |
|                                               |
+-----+-----+-----+-----+-----+-----+-----+-----+
|                    GCM TAG                    |
|                                               |
|                                               |
|                                               |
+-----+-----+-----+-----+-----+-----+-----+-----+
/                 ENCRYPTED DATA                /
+-----+-----+-----+-----+-----+-----+-----+-----+
Figure 1: The binary representation of the KX message.
REPRESENTATIVE
The 256-bit serialized encapsulation result of the Elligator KEM.
GCM TAG
The 128-bit GCM tag used to authenticate the ciphertext immediately following the header part of the KX message.
ENCRYPTED DATA
The remaining data (as indicated by SIZE) is AES-GCM encrypted using the current session key and authenticated through the GCM TAG.

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 for each peer identity to reject possible replay attacks.

0     8     16    24    32    40    48    56
+-----+-----+-----+-----+-----+-----+-----+-----+
|                                               |
|                 SENDER PEER ID                |
|                                               |
|                                               |
+-----+-----+-----+-----+-----+-----+-----+-----+
|                                               |
|                 SIGNATURE                     |
|                                               |
|                                               |
|                                               |
|                                               |
|                                               |
|                                               |
+-----+-----+-----+-----+-----+-----+-----+-----+
|                MONOTONIC TIMESTAMP            |
|                                               |
|                                               |
|                                               |
|                                               |
|                                               |
|                                               |
|                                               |
+-----+-----+-----+-----+-----+-----+-----+-----+
/                PAYLOAD                        /
+-----+-----+-----+-----+-----+-----+-----+-----+
Figure 2: The binary representation of the KX Confirmation header
SENDER PEER ID
A 256-bit EdDSA public key.
SIGNATURE
The EdDSA signature is computed with the peer private key over the session metadata as detailed in Figure 3.
MONOTONIC TIMESTAMP
FIXME.
PAYLOAD
The message payload data.

The confirmation header also includes a signature over the session's meta data, which is signed with the corresponding private key of the sender 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              |
|                                               |
|                                               |
|                                               |
+-----+-----+-----+-----+-----+-----+-----+-----+
|                EPHEMERAL PUBLIC KEY           |
|                                               |
|                                               |
|                                               |
+-----+-----+-----+-----+-----+-----+-----+-----+
|                MONOTONIC TIMESTAMP            |
|                                               |
|                                               |
|                                               |
|                                               |
|                                               |
|                                               |
|                                               |
+-----+-----+-----+-----+-----+-----+-----+-----+
Figure 3: The wire format of the data structure over which the signature of the UDP Confirmation header is computed.
SIZE
A 32-bit value containing the length of the signed data in bytes in network byte order.
PURPOSE
A 32-bit signature purpose flag in network byte order. The value of this field MUST be 33. It defines the context in which the signature is created so that it cannot be reused in other parts of the protocol including possible future extensions. The value of this field corresponds to an entry in the GANA "GNUnet Signature Purpose" registry Section 9.
SENDER PEER ID
A 256-bit EdDSA public key.
RECEIVER PEER ID
A 256-bit EdDSA public key.
EPHEMERAL PUBLIC KEY
A 256-bit Curve25519 public key. This public key is send in an Elligator encoded format, called the representative, in the KX header.
MONOTONIC TIMESTAMP
FIXME.

Upon receiving a KX message, the receiving peer decapsulates the respresentative using the "DecapsElligator" procedure defined in Section 4.3 and receives a master secret key MSK. 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 identites is through the means of UDP BROADCAST messages as described in Section 5.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 iterativly 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 5.3.

5.2. Key schedule

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):
  PRK := HKDF-Extract (SEQ, MSK)
  K,IV := HKDF-Expand (PRK, "gnunet-communicator-udp-key-iv", 44)
  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):
  PRK := HKDF-Extract (SEQ, MSK)
  KID := HKDF-Expand (PRK, "gnunet-communicator-udp-kid", 256 / 8)
  return KID

The sequence number SEQ for any shared secret is initially 0 and incremented on the senders side for each successive encryption and on the receivers side for each decryption.

5.3. Message exchange

KX messages as presented in Section 5.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 communication with the reuse of 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 send as BOX messages, which incorporate a KID as defined in Section 5.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                /
+-----+-----+-----+-----+-----+-----+-----+-----+
Figure 4: The binary representation of the UDP Box message.
KEY ID
A 256-bit value containing the KID of the symmetric key to use for decryption as derived using DeriveKID as described in Section 5.2.
GCM TAG
A 128-bit GCM tag used to authenticate the ciphertext immediately following this TCP Box header.
ENCRYPTED DATA
The remaining data (as indicated by SIZE) is AES-GCM encrypted using the derived key and IV identified by the KID.

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)       |
|                                               |
|                                               |
|                                               |
|                                               |
|                                               |
|                                               |
|                                               |
|                                               |
|                                               |
|                                               |
|                                               |
|                                               |
|                                               |
|                                               |
|                                               |
+-----+-----+-----+-----+-----+-----+-----+-----+
Figure 5: The wire format of an ACK header.
SIZE
A 16-bit value containing the length of the message in bytes in network byte order.
TYPE
A 16-bit signature type flag in network byte order. The value of this field MUST be 1460.
SEQ ACK
Sequence acknowledgment limit. Specifies current maximum sequence number supported by receiver.
MSK HASH
CMAC of the base key being acknowledged.

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 (FIXME: currently limited to 256). Should the sending peer use up all acknowledgments for all its shared secrets, messages are sent through KX messages again.

5.4. Rekeying

The amount of data which can be encrypted with a shared secret MUST be limited (FIXME: Currently at 4GB). Before the capacity of a shared secret is used up (FIXME: currently at 70%), 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. The wire format of the Rekey header can be seen in Figure 6.

0                       16
+-----+-----+-----+-----+-----+-----+-----+-----+
|         SIZE          |       TYPE (0x0X)     |
+-----+-----+-----+-----+-----+-----+-----+-----+
|                EPHEMERAL PUBLIC KEY           |
|                                               |
|                                               |
|                                               |
|                                               |
|                                               |
|                                               |
|                                               |
+-----+-----+-----+-----+-----+-----+-----+-----+
Figure 6: The wire format of a Rekey header.
SIZE
A 16-bit value containing the length of the message in bytes in network byte order.
TYPE
A 16-bit signature type flag in network byte order. The value of this field MUST be 1462.
EPHEMERAL PUBLIC KEY
A 256-bit X25519 ephemeral public key to rekey with.

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.

5.5. Broadcast

(FIXME: Broadcast documentation is missing)

6. TCP communicator

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, re-keying occurs to renew the key material. Note that the re-keying 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.

6.1. Handshake

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 4.3.

The encapsulation MUST be directly followed by an encrypted TCP handshake message as shown in Figure 7. 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 signature.

0     8     16    24    32    40    48    56
+-----+-----+-----+-----+-----+-----+-----+-----+
|                 SENDER PEER ID                |
|                                               |
|                                               |
|                                               |
+-----+-----+-----+-----+-----+-----+-----+-----+
|                 SIGNATURE                     |
|                                               |
|                                               |
|                                               |
|                                               |
|                                               |
|                                               |
|                                               |
+-----+-----+-----+-----+-----+-----+-----+-----+
|                MONOTONIC TIMESTAMP            |
+-----+-----+-----+-----+-----+-----+-----+-----+
|                     NONCE                     |
|                                               |
|                                               |
|                                               |
+-----+-----+-----+-----+-----+-----+-----+-----+
Figure 7: The binary representation of the TCP handshake message.
SENDER PEER ID
A 256-bit EdDSA public key.
SIGNATURE
A 512-bit EdDSA signature. The signature is calculated over the data as defined in Figure 8.
MONOTONIC TIMESTAMP
FIXME.
NONCE
A 256-bit random value used as a challenge to be signed in a TCP handshake acknowledgment message.

The data scheme used for computing the signature is depicted in Figure 8.

0     8     16    24    32    40    48    56
+-----+-----+-----+-----+-----+-----+-----+-----+
|         SIZE          |       PURPOSE (0x0X)  |
+-----+-----+-----+-----+-----+-----+-----+-----+
|                 SENDER PEER ID                |
|                                               |
|                                               |
|                                               |
+-----+-----+-----+-----+-----+-----+-----+-----+
|                 RECEIVER PEER ID              |
|                                               |
|                                               |
|                                               |
+-----+-----+-----+-----+-----+-----+-----+-----+
|                REPRESENTATIVE                 |
|                                               |
|                                               |
|                                               |
+-----+-----+-----+-----+-----+-----+-----+-----+
|                MONOTONIC TIMESTAMP            |
|                                               |
|                                               |
|                                               |
|                                               |
|                                               |
|                                               |
|                                               |
+-----+-----+-----+-----+-----+-----+-----+-----+
|                     NONCE                     |
|                                               |
|                                               |
|                                               |
+-----+-----+-----+-----+-----+-----+-----+-----+
Figure 8: The wire format used for creating the signature of the tcp handshake message.
SIZE
A 32-bit value containing the length of the signed data in bytes in network byte order.
PURPOSE
A 32-bit signature purpose flag in network byte order. The value of this field MUST be 31. It defines the context in which the signature is created so that it cannot be reused in other parts of the protocol including possible future extensions. The value of this field corresponds to an entry in the GANA "GNUnet Signature Purpose" registry Section 9.
SENDER PEER ID
A 256-bit EdDSA public key.
RECEIVER PEER ID
A 256-bit EdDSA public key.
REPRESENTATIVE
The 256-bit serialized encapsulation result of the Elligator KEM.
MONOTONIC TIMESTAMP
FIXME.
NONCE
A 256-bit random value.

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. (FIXME: Other checks such as sender peer identity etc needed). 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 9.

0           8           16          24
+-----+-----+-----+-----+-----+-----+-----+-----+
|         SIZE          |        TYPE (0x0X)    |
+-----+-----+-----+-----+-----+-----+-----+-----+
|                 SENDER PEER ID                |
|                                               |
|                                               |
|                                               |
|                                               |
|                                               |
|                                               |
|                                               |
+-----+-----+-----+-----+-----+-----+-----+-----+
|                 RECEIVER PEER ID              |
|                                               |
|                                               |
|                                               |
|                                               |
|                                               |
|                                               |
|                                               |
+-----+-----+-----+-----+-----+-----+-----+-----+
|                 SIGNATURE                     |
|                                               |
|                                               |
|                                               |
|                                               |
|                                               |
|                                               |
|                                               |
+-----+-----+-----+-----+-----+-----+-----+-----+
|                MONOTONIC TIMESTAMP            |
|                                               |
+-----+-----+-----+-----+-----+-----+-----+-----+
|                     NONCE                     |
|                                               |
|                                               |
|                                               |
|                                               |
|                                               |
|                                               |
|                                               |
+-----+-----+-----+-----+-----+-----+-----+-----+
Figure 9: The binary representation of the tcp handshake acknowledgment message.
SIZE
A 16-bit value containing the length of the message in bytes in network byte order.
TYPE
A 16-bit signature type flag in network byte order. The value of this field MUST be 1453.
SENDER PEER ID
A 256-bit EdDSA public key.
RECEIVER PEER ID
A 256-bit EdDSA public key.
Signature
A 512-bit EdDSA signature. The signature is calculated over the data as defined in Figure 10.
MONOTONIC TIMESTAMP
FIXME.
NONCE
A 256-bit random value.

The data scheme used for computing the signature for the acknowledgment message is depicted in Figure 10.

0           8           16          24
+-----+-----+-----+-----+-----+-----+-----+-----+
|         SIZE          |        TYPE (0x0X)    |
+-----+-----+-----+-----+-----+-----+-----+-----+
|                 SENDER PEER ID                |
|                                               |
|                                               |
|                                               |
|                                               |
|                                               |
|                                               |
|                                               |
+-----+-----+-----+-----+-----+-----+-----+-----+
|                 RECEIVER PEER ID              |
|                                               |
|                                               |
|                                               |
|                                               |
|                                               |
|                                               |
|                                               |
+-----+-----+-----+-----+-----+-----+-----+-----+
|                MONOTONIC TIMESTAMP            |
|                                               |
+-----+-----+-----+-----+-----+-----+-----+-----+
|                     NONCE                     |
|                                               |
/                                               /
/                                               /
|                                               |
+-----+-----+-----+-----+-----+-----+-----+-----+
Figure 10: The wire format used for creating the signature of the tcp handshake acknowledgment message.
SIZE
A 16-bit value containing the length of the message in bytes in network byte order.
TYPE
A 16-bit signature type flag in network byte order. The value of this field MUST be 39.
SENDER PEER ID
A 256-bit EdDSA public key.
RECEIVER PEER ID
A 256-bit EdDSA public key.
MONOTONIC TIMESTAMP
FIXME.
NONCE
A 256-bit random value.

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.

6.2. Key exchange

During the initial handshake, each communication channel performs the Elligator KEM defined in Section 4.3. 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 6.1 and Section 6.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 4.3 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):
  PRK := HKDF-Extract (0, REC_ID||MSK)
  K := HKDF-Expand (PRK, "gnunet-communicator-tcp-key", 32)
  IV := HKDF-Expand (PRK, "gnunet-communicator-tcp-ctr, 16)
  K_mac := HKDF-Expand (PRK, "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 repsentative, it can decrypt the following TCP handshake message. The same applies for the TCP handshake message send by the receiving TCP communicator.

6.3. Message exchange

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 11, 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 for replay attacks by exchanging new key material after a randomly chosen amount of transferred data as described in Section 6.4. The necessary key exchanges to establish the new key material are protected using monotonic timestamps.

(FIXME: hmac, MtE discussion, padding-oracle).

0           8           16          24
+-----+-----+-----+-----+-----+-----+-----+-----+
|         SIZE          |        TYPE (0x0X)    |
+-----+-----+-----+-----+-----+-----+-----+-----+
|                    HASHCODE                   |
|                                               |
|                                               |
|                                               |
|                                               |
|                                               |
|                                               |
|                                               |
+-----+-----+-----+-----+-----+-----+-----+-----+

Figure 11: The binary representation of the TCP BOX message.
SIZE
A 16-bit value containing the length of the message in bytes in network byte order.
TYPE
A 16-bit signature type flag in network byte order. The value of this field MUST be 1451.
HASHCODE
A 256-bit HMAC-SHA512 hashcode for the subsequently sent payload.

6.4. Rekeying

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 12. 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 are derived. For further details please refer to Section 6.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                   |
|                                               |
|                                               |
|                                               |
|                                               |
|                                               |
|                                               |
|                                               |
+-----+-----+-----+-----+-----+-----+-----+-----+
|                EPHEMERAL PUBLIC KEY           |
|                                               |
|                                               |
|                                               |
|                                               |
|                                               |
|                                               |
|                                               |
+-----+-----+-----+-----+-----+-----+-----+-----+
|                 SIGNATURE                     |
|                                               |
|                                               |
|                                               |
|                                               |
|                                               |
|                                               |
|                                               |
+-----+-----+-----+-----+-----+-----+-----+-----+
|                MONOTONIC TIMESTAMP            |
|                                               |
+-----+-----+-----+-----+-----+-----+-----+-----+
Figure 12: The binary representation of the TCP Rekey message.
SIZE
A 16-bit value containing the length of the message in bytes in network byte order.
TYPE
A 16-bit signature type flag in network byte order. The value of this field MUST be 1450.
HASHCODE
A 256-bit HMAC-SHA512 hashcode of this TCP Rekey message. The hashcode is computed with the hashcode field initially set to zero and is inserted afterward.
EPHEMERAL PUBLIC KEY
A 256-bit Curve25519 public key which is used as part of an X25519-based key exchange to establish a shared secret.
Signature
A 512-bit EdDSA signature. The signature is calculated over the data as defined in Figure 13.
MONOTONIC TIMESTAMP
FIXME.
0     8     16    24    32    40    48    56
+-----+-----+-----+-----+-----+-----+-----+-----+
|         SIZE          |       PURPOSE (0x0X)  |
+-----+-----+-----+-----+-----+-----+-----+-----+
|                 SENDER PEER ID                |
|                                               |
|                                               |
|                                               |
+-----+-----+-----+-----+-----+-----+-----+-----+
|                 RECEIVER PEER ID              |
|                                               |
|                                               |
|                                               |
+-----+-----+-----+-----+-----+-----+-----+-----+
|                EPHEMERAL PUBLIC KEY           |
|                                               |
|                                               |
|                                               |
+-----+-----+-----+-----+-----+-----+-----+-----+
|                MONOTONIC TIMESTAMP            |
|                                               |
|                                               |
|                                               |
|                                               |
|                                               |
|                                               |
|                                               |
+-----+-----+-----+-----+-----+-----+-----+-----+
Figure 13: The wire format used for creating the signature of the TCP Rekey message.
SIZE
A 32-bit value containing the length of the signed data in bytes in network byte order.
PURPOSE
A 32-bit signature purpose flag in network byte order. The value of this field MUST be 32. It defines the context in which the signature is created so that it cannot be reused in other parts of the protocol including possible future extensions. The value of this field corresponds to an entry in the GANA "GNUnet Signature Purpose" registry Section 9.
SENDER PEER ID
A 256-bit EdDSA public key.
RECEIVER PEER ID
A 256-bit EdDSA public key.
EPHEMERAL PEER ID
A 256-bit EdDSA public key.
MONOTONIC TIMESTAMP
FIXME.

7. QUIC communicator

The QUIC [RFC9000] communicator uses TLS-over-QUIC for a baseline layer of metadata protection. Peers use self-signed certificates and corresponding public-private key pairs when establishing a TLS channel. No trust anchors are used to verify the trustworthiness and authenticity of the identities in the TLS certificates. However, QUIC communicators MUST provide a signature using the peer private key over the certificate used in the TLS key exchange.

0     8     16    24    32    40    48    56
+-----+-----+-----+-----+-----+-----+-----+-----+
|                                               |
|                    PEER ID                    |
|                                               |
|                                               |
+-----+-----+-----+-----+-----+-----+-----+-----+
|                                               |
|                 SIGNATURE                     |
|                                               |
|                                               |
|                                               |
|                                               |
|                                               |
|                                               |
+-----+-----+-----+-----+-----+-----+-----+-----+
Figure 14: The binary representation of the initial identification packet
PEER ID
A 256-bit EdDSA public key.
SIGNATURE
The EdDSA signature is computed with the peer private key over the DER-encoded TLS certificate of the peer along with a pseudo-header as detailed in Figure 15.
0     8     16    24    32    40    48    56
+-----+-----+-----+-----+-----+-----+-----+-----+
|         SIZE          |       PURPOSE (0x0TODO)|
+-----+-----+-----+-----+-----+-----+-----+-----+
|        DER-encoded public key certificate     |
/                                               /
/                                               /
+-----+-----+-----+-----+-----+-----+-----+-----+
Figure 15: The wire format used for creating the signature of the identification packet.
SIZE
A 32-bit value containing the length of the signed data in bytes in network byte order.
PURPOSE
A 32-bit signature purpose flag in network byte order. The value of this field MUST be XXXX. It defines the context in which the signature is created so that it cannot be reused in other parts of the protocol including possible future extensions. The value of this field corresponds to an entry in the GANA "GNUnet Signature Purpose" registry Section 9.
EXPIRATION
Field as defined in the RRBLOCK message above.
BDATA
Field as defined in the RRBLOCK message above.

8. Security and Privacy Considerations

8.1. Ed25519 KEM

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. This use of a KEM and its safety has been investigated by [T21].

8.2. Elligator

In case of Montgomery curves, such as Curve25519, a point [X, Y] on that curve (e.g. the ephemeral public key) follows the equation Y^2 = X^3 + A * X^2 + X mod P, where A and P are parameters for Curve25519 specified in section 4.1 of [RFC7748]. For any valid x-coordinate, the left side of the equation is always a quadratic number. An attacker could read the x-coordinate and verify if this property holds. While this property holds for any valid Curve25519 point, it only holds in about 50% of the cases for a random number. By observing multiple communication attempts, an attacker can be certain that curve points are being sent if the property consistently holds. To circumvent this attack, curve points should be encoded into property-less numbers, making valid and invalid curve points indistinguishable to an outside observer. The Elligator encoding function "ElligatorEnc" (also known as the "inverse map") and decoding function "ElligatorDec" (also known as the "direct map") implement this feature.

The encoding function is defined for the entire Curve25519. Most modern implementations of Curve25519 only generate points from its prime subgroup to circumvent known attacks for which points not within the prime subgroup are susceptible. In our case, those attacks are not an issue as we use the ephemeral secret key only once for computing key material. The exclusive use of the prime subgroup is a recognizable property that an outside observer can easily detect, even in the case of using the encoding function. An attacker could decode the suspected parts of packets to the corresponding Curve25519 points and check if the resulting points are always in the prime subgroup. To circumvent this attack, we need to choose the ephemeral key pair randomly from the whole curve as defined in "KeyGenElligator".

Note that both for a value REPR and its negative counterpart -REPR (in the finite field), the decoding function will result in the same x-coordinate. Moreover, for two different valid x-coordinates, the resulting representatives of the corresponding encoding calls are different. Conversely, this means that we can't decode both representatives back to their original x-coordinate. This is why the sender eventually tries a number of random key pairs in KeyGenElligator() in order to create a valid public key that can be used for a key exchange. Also note that this effectively reduces the entropy of our public keys by 1 bit, which is tolerable.

In the original paper, Elligator's encoding function takes the sign of y-coordinate as an additional input parameter. Its value determines which of the two terms is used instead of our random selection. We also skip the calculation of the corresponding y-coordinate in the decoding function. We omitted the y-coordinate parts of both functions because Curve25519 points are solely represented by their x-coordinate in modern crypto systems due to known attacks. Nevertheless, the desired feature of Elligator is still ensured.

Lastly, we emphasize that the resulting representative of the encoding function is strictly smaller than 2^254 - 9. Therefore, the most and second most significant bit are always zero, which is an obvious property an attacker could observe. We avoid this problem by randomly flipping both bits. These bits will be ignored by the target peer after reception.

9. GANA Considerations

10. Normative References

[RFC2119]
Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, , <https://www.rfc-editor.org/info/rfc2119>.
[RFC5869]
Krawczyk, H. and P. Eronen, "HMAC-based Extract-and-Expand Key Derivation Function (HKDF)", RFC 5869, DOI 10.17487/RFC5869, , <https://www.rfc-editor.org/info/rfc5869>.
[RFC6234]
Eastlake 3rd, D. and T. Hansen, "US Secure Hash Algorithms (SHA and SHA-based HMAC and HKDF)", RFC 6234, DOI 10.17487/RFC6234, , <https://www.rfc-editor.org/info/rfc6234>.
[RFC7748]
Langley, A., Hamburg, M., and S. Turner, "Elliptic Curves for Security", RFC 7748, DOI 10.17487/RFC7748, , <https://www.rfc-editor.org/info/rfc7748>.
[RFC8032]
Josefsson, S. and I. Liusvaara, "Edwards-Curve Digital Signature Algorithm (EdDSA)", RFC 8032, DOI 10.17487/RFC8032, , <https://www.rfc-editor.org/info/rfc8032>.
[RFC8174]
Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, , <https://www.rfc-editor.org/info/rfc8174>.
[RFC9000]
Iyengar, J., Ed. and M. Thomson, Ed., "QUIC: A UDP-Based Multiplexed and Secure Transport", RFC 9000, DOI 10.17487/RFC9000, , <https://www.rfc-editor.org/info/rfc9000>.

11. Informative References

[T21]
Thormaker, E., "On using the same key pair for Ed25519 and an X25519 based KEM", , <https://eprint.iacr.org/2021/509.pdf>.
[BHKL13]
Bernstein, D.J., Hamburg, M., Krasnova, A., and T. Lange, "Elligator: Elliptic-curve points indistinguishable from uniform random strings", , <https://eprint.iacr.org/2013/325.pdf>.

Authors' Addresses

Martin Schanzenbach
Fraunhofer AISEC
Lichtenbergstrasse 11
85748 Garching
Germany
Christian Grothoff
Berner Fachhochschule
Hoeheweg 80
CH-2501 Biel/Bienne
Switzerland
Pedram Fardzadeh
Technischen Universität München
Boltzmannstrasse 3
85748 Garching
Germany