draft-gnunet-communicators.xml (79942B)
1 <?xml version='1.0' encoding='utf-8'?> 2 <!DOCTYPE rfc [ 3 <!ENTITY RFC1034 PUBLIC '' "http://xml.resource.org/public/rfc/bibxml/reference.RFC.1034.xml"> 4 <!ENTITY RFC1035 PUBLIC '' "http://xml.resource.org/public/rfc/bibxml/reference.RFC.1035.xml"> 5 <!ENTITY RFC1928 PUBLIC '' "http://xml.resource.org/public/rfc/bibxml/reference.RFC.1928.xml"> 6 <!ENTITY RFC2119 PUBLIC '' "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml"> 7 <!--<!ENTITY RFC2693 PUBLIC '' "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2693.xml">--> 8 <!ENTITY RFC2782 PUBLIC '' "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2782.xml"> 9 <!ENTITY RFC3629 PUBLIC '' "http://xml.resource.org/public/rfc/bibxml/reference.RFC.3629.xml"> 10 <!ENTITY RFC3686 PUBLIC '' "http://xml.resource.org/public/rfc/bibxml/reference.RFC.3686.xml"> 11 <!ENTITY RFC3826 PUBLIC '' "http://xml.resource.org/public/rfc/bibxml/reference.RFC.3826.xml"> 12 <!ENTITY RFC4033 PUBLIC '' "http://xml.resource.org/public/rfc/bibxml/reference.RFC.4033.xml"> 13 <!ENTITY RFC5237 PUBLIC '' "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5237.xml"> 14 <!--<!ENTITY RFC3912 PUBLIC '' "http://xml.resource.org/public/rfc/bibxml/reference.RFC.3912.xml">--> 15 <!ENTITY RFC5869 PUBLIC '' "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5869.xml"> 16 <!ENTITY RFC5890 PUBLIC '' "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5890.xml"> 17 <!ENTITY RFC5895 PUBLIC '' "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5895.xml"> 18 <!ENTITY RFC6066 PUBLIC '' "http://xml.resource.org/public/rfc/bibxml/reference.RFC.6066.xml"> 19 <!ENTITY RFC6234 PUBLIC '' "http://xml.resource.org/public/rfc/bibxml/reference.RFC.6234.xml"> 20 <!ENTITY RFC6761 PUBLIC '' "http://xml.resource.org/public/rfc/bibxml/reference.RFC.6761.xml"> 21 <!ENTITY RFC6895 PUBLIC '' "http://xml.resource.org/public/rfc/bibxml/reference.RFC.6895.xml"> 22 <!ENTITY RFC6979 PUBLIC '' "http://xml.resource.org/public/rfc/bibxml/reference.RFC.6979.xml"> 23 <!ENTITY RFC7363 PUBLIC '' "http://xml.resource.org/public/rfc/bibxml/reference.RFC.7363.xml"> 24 <!ENTITY RFC8806 PUBLIC '' "http://xml.resource.org/public/rfc/bibxml/reference.RFC.8806.xml"> 25 <!ENTITY RFC7748 PUBLIC '' "http://xml.resource.org/public/rfc/bibxml/reference.RFC.7748.xml"> 26 <!ENTITY RFC8032 PUBLIC '' "http://xml.resource.org/public/rfc/bibxml/reference.RFC.8032.xml"> 27 <!ENTITY RFC8126 PUBLIC '' "http://xml.resource.org/public/rfc/bibxml/reference.RFC.8126.xml"> 28 <!ENTITY RFC8174 PUBLIC '' "http://xml.resource.org/public/rfc/bibxml/reference.RFC.8174.xml"> 29 <!ENTITY RFC8244 PUBLIC '' "http://xml.resource.org/public/rfc/bibxml/reference.RFC.8244.xml"> 30 <!ENTITY RFC8324 PUBLIC '' "http://xml.resource.org/public/rfc/bibxml/reference.RFC.8324.xml"> 31 <!ENTITY RFC8499 PUBLIC '' "http://xml.resource.org/public/rfc/bibxml/reference.RFC.8499.xml"> 32 <!ENTITY RFC9114 PUBLIC '' "http://xml.resource.org/public/rfc/bibxml/reference.RFC.9114.xml"> 33 <!ENTITY RFC9106 PUBLIC '' "http://xml.resource.org/public/rfc/bibxml/reference.RFC.9106.xml"> 34 <!ENTITY RFC9180 PUBLIC '' "http://xml.resource.org/public/rfc/bibxml/reference.RFC.9180.xml"> 35 <!ENTITY I-D.ietf-dnsop-alt-tld PUBLIC '' "http://xml.resource.org/public/rfc/bibxml3/reference.I-D.ietf-dnsop-alt-tld.xml"> 36 ]> 37 <?xml-stylesheet type='text/xsl' href='rfc2629.xslt' ?> 38 <?rfc strict="yes" ?> 39 <?rfc toc="yes" ?> 40 <?rfc symrefs="yes"?> 41 <?rfc sortrefs="yes" ?> 42 <?rfc compact="yes" ?> 43 <?rfc subcompact="no" ?> 44 <rfc xmlns:xi="http://www.w3.org/2001/XInclude" 45 category="info" 46 docName="draft-gnunet-communicators-00" 47 ipr="trust200902" 48 obsoletes="" updates="" 49 submissionType="independent" 50 xml:lang="en" 51 version="3"> 52 <!-- xml2rfc v2v3 conversion 2.26.0 --> 53 <front> 54 <title abbrev="The GNUnet communicators"> 55 The GNUnet communicators 56 </title> 57 <seriesInfo name="Internet-Draft" value="draft-gnunet-communicators-00"/> 58 <author fullname="Martin Schanzenbach" initials="M." surname="Schanzenbach"> 59 <organization>Fraunhofer AISEC</organization> 60 <address> 61 <postal> 62 <street>Lichtenbergstrasse 11</street> 63 <city>Garching</city> 64 <code>85748</code> 65 <country>DE</country> 66 </postal> 67 <email>martin.schanzenbach@aisec.fraunhofer.de</email> 68 </address> 69 </author> 70 <author fullname="Christian Grothoff" initials="C." surname="Grothoff"> 71 <organization>Berner Fachhochschule</organization> 72 <address> 73 <postal> 74 <street>Hoeheweg 80</street> 75 <city>Biel/Bienne</city> 76 <code>2501</code> 77 <country>CH</country> 78 </postal> 79 <email>christian.grothoff@bfh.ch</email> 80 </address> 81 </author> 82 <author fullname="Pedram Fardzadeh" initials="P." surname="Fardzadeh"> 83 <organization>Technischen Universität München</organization> 84 <address> 85 <postal> 86 <street>Boltzmannstrasse 3</street> 87 <city>Garching</city> 88 <code>85748</code> 89 <country>DE</country> 90 </postal> 91 <email>pedram.fardzadeh@tum.de</email> 92 </address> 93 </author> 94 <author fullname="ch3" initials="" surname="ch3"> 95 <organization>GNUnet e.V.</organization> 96 <address> 97 <postal> 98 <street></street> 99 <city>Lenggries</city> 100 <code></code> 101 <country>DE</country> 102 </postal> 103 <email>ch3@mailbox.org</email> 104 </address> 105 </author> 106 107 108 <!-- Meta-data Declarations --> 109 <area>General</area> 110 <workgroup>Independent Stream</workgroup> 111 <keyword>transport protocols</keyword> 112 <abstract> 113 <t> 114 This document contains the GNUnet communicator 115 specification. 116 </t> 117 <t> 118 This document defines the normative wire format of communicator protocols, 119 cryptographic routines and security 120 considerations for use by implementers. 121 </t> 122 <t> 123 This specification was developed outside the IETF and does not have 124 IETF consensus. It is published here to inform readers about the 125 function of GNUnet communicators, guide future communicator implementations, and ensure 126 interoperability among implementations including with the pre-existing 127 GNUnet implementation. 128 </t> 129 </abstract> 130 </front> 131 <middle> 132 <section anchor="introduction" numbered="true" toc="default"> 133 <name>Introduction</name> 134 <t> 135 This document defines the normative wire format of resource 136 records, resolution processes, cryptographic routines and 137 security considerations for use by implementers. 138 </t> 139 <t> 140 This specification was developed outside the IETF and does not have 141 IETF consensus. It is published here to guide GNS implementers 142 and to ensure interoperability among implementations. 143 </t> 144 <section numbered="true" toc="default"> 145 <name>Requirements Notation</name> 146 <t> 147 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 148 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 149 "OPTIONAL" in this document are to be interpreted as described in 150 BCP 14 <xref target="RFC2119"/> <xref target="RFC8174"/> when, and only 151 when, they appear in all capitals, as shown here. 152 </t> 153 </section> 154 </section> 155 <section> 156 <name>Terminology</name> 157 <dl> 158 <dt>Communicator</dt> 159 <dd> 160 What is a communicator? 161 </dd> 162 <dt>Peer Identity</dt> 163 <dd> 164 Peer IDs in GNUnet are Ed25519 public keys as defined <xref target="RFC8032"/> 165 and serialized accordingly. 166 </dd> 167 </dl> 168 </section> 169 <section> 170 <name>Notation</name> 171 <t> 172 We use the notation from <xref target="RFC9180"/> and <xref target="LSD0011"/>. 173 In addition, we define: 174 </t> 175 <dl> 176 <dt>(skXed, pkXed)</dt> 177 <dd> 178 A key pair is used in role X, where X is one of S as sender or R as recipient, respectively; 179 skXed is the Ed25519 private key and pkXed is the Ed25519 public key as defined in 180 <xref target="RFC8032"/>. 181 </dd> 182 </dl> 183 </section> <section anchor="overview" numbered="true" toc="default"> 184 <name>Overview</name> 185 <t> 186 Each communicator must specify its (global) communication characteristics, 187 which for now only say whether the communication is reliable (e.g., TCP, HTTPS) 188 or unreliable (e.g., UDP, WLAN). 189 Each communicator must specify a unique address prex, or NULL if the 190 communicator cannot establish outgoing connections (for example, because 191 it is only acting as a TCP server). 192 A communicator must tell TRANSPORT which addresses it is reachable under. 193 Addresses may be added or removed at any time. 194 A communicator may have zero addresses (transmission only). 195 Addresses do not have to match the address prefix. 196 </t> 197 <t> 198 TRANSPORT may ask a communicator to try to connect to another address. 199 TRANSPORT will only ask for connections where the address matches the 200 communicator’s address prefix that was provided when the connection was 201 established. 202 Communicators should then attempt to establish a connection. 203 No response is provided to TRANSPORT service on failure. 204 The TRANSPORT service has to ask the communicator explicitly to retry. 205 </t> 206 <t> 207 If a communicator succeeds in establishing an outgoing connection for 208 transmission, or if a communicator receives an incoming bi-directional 209 connection, the communicator must inform the TRANSPORT service that a 210 message queue (MQ) for transmission is now available. 211 For that MQ, the communicator must provide the peer identity claimed by 212 the other end. 213 It must also provide a human-readable address (for debugging) and a 214 maximum transfer unit (MTU). 215 A MTU of zero means sending is not supported, SIZE_MAX should be used for 216 no MTU. The communicator should also tell TRANSPORT what network type is 217 used for the queue. 218 The communicator may tell TRANSPORT anytime that the queue was deleted 219 and is no longer available. 220 </t> 221 <t> 222 The communicator API also provides for flow control. 223 First, communicators exhibit backpressure on TRANSPORT: 224 the number of messages TRANSPORT may add to a queue for transmission will 225 be limited. 226 So, by not draining the transmission queue, backpressure is provided to 227 TRANSPORT. 228 In the other direction, communicators may allow TRANSPORT to give 229 backpressure towards the communicator by providing a non-NULL 230 GNUNET_TRANSPORT_MessageCompletedCallback argument to the 231 GNUNET_TRANSPORT_communicator_receive function. 232 In this case, TRANSPORT will only invoke this function once it has 233 processed the message and is ready to receive more. 234 Communicators should then limit how much traffic they receive based on 235 this backpressure. 236 Note that communicators do not have to provide a 237 GNUNET_TRANSPORT_MessageCompletedCallback; 238 for example, UDP cannot support backpressure due to the nature of the 239 UDP protocol. 240 In this case, TRANSPORT will implement its own TRANSPORT-to-TRANSPORT 241 flow control to reduce the sender’s data rate to acceptable levels. 242 </t> 243 <t> 244 TRANSPORT may notify a communicator about backchannel messages TRANSPORT 245 received from other peers for this communicator. 246 Similarly, communicators can ask TRANSPORT to try to send a backchannel 247 message to other communicators of other peers. 248 The semantics of the backchannel message are up to the communicators 249 who use them. 250 TRANSPORT may fail to transmit backchannel messages, and TRANSPORT will 251 not attempt to retransmit them. 252 </t> 253 </section> 254 <section anchor="primitives" numbered="true" toc="default"> 255 <name>Cryptographic dependencies</name> 256 <section anchor="elligator_dhkem" numbered="true" toc="default"> 257 <name>Elligator DHKEM</name> 258 <t> 259 GNUnet communicators utilize en Elligator KEM for the encoding and decoding 260 the ephemeral public keys. 261 While standard Diffie-Hellman-based KEMs securely establish a secret between 262 two parties, an observer can easily identify the encapsulation as a public key. 263 In the presence of an active attacker, this could lead to packet dropping based on this information, 264 preventing communication between peers. 265 The UDP and TCP communicators use the Elligator KEM defined in 266 <xref target="LSD0011"/>. 267 This leaves the attacker with the option to either do nothing or intercept all random-looking packets, 268 thereby potentially disrupting a large part of today's internet communication. 269 </t> 270 <t> 271 We use the KEMs and their notations as defined in <xref target="RFC9180"/> and 272 <xref target="LSD0011"/>. 273 </t> 274 </section> 275 <section anchor="key_derivation" numbered="true" toc="default"> 276 <name>Key derivation</name> 277 <t> 278 We use a hash-based key derivation function (HKDF) as defined in 279 <xref target="RFC5869" />, using SHA-256 <xref target="RFC6234"/> for the extraction 280 phase and SHA-256 <xref target="RFC6234"/> for the expansion phase. 281 We derive the master secret as a uniform symmetric key 282 from the X25519 result "Z" and the ephemeral public key "A" in a 283 "HKDF-Extract" step and then derive context-specific keys through "HKDF-Expand" as needed. 284 </t> 285 <t> 286 Peer IDs in GNUnet are Ed25519 public keys as defined <xref target="RFC8032"/>. 287 In order to use such keys in our X25519-based KEMs (including the Elligator KEM), those 288 keys must be converted to Curve25519 public keys, which is generally possible. 289 </t> 290 </section> 291 </section> 292 <section anchor="udp_comm" numbered="true" toc="default"> 293 <name>UDP communicator</name> 294 <t> 295 The UDP communicator implements an encryption layer that protects both the payload and the communicator's 296 specific metadata (not to be confused with the UDP header). In particular, any message sent by the communicator 297 is indistinguishable from random payload to an outside observer, with the exception of broadcast messages. 298 </t> 299 <t> 300 For any new connection to a target peer, the communicator attempts to establish a shared secret using the 301 KEM defined in <xref target="elligator_dhkem"/>. 302 The communicator initiating the connection sends the resulting Elligator representative, the authentication tag 303 and the encrypted data to the receiving peer. 304 Since the GCM authentication tag and the encrypted data in the key exchange message also appear random, 305 the entire message is computationally indistinguishable from a random byte stream. 306 Independent of the payload, each message includes the sender's peer identity, a monotonic timestamp, and a 307 signature over the session metadata. 308 Receivers <bcp14>MUST</bcp14> keep track of the monotonic timestamps of key exchanges with each peer 309 to prevent replay attacks. 310 For each subsequent message the same procedure is used with a new encapsulation. 311 While the communicator may always fall back to this type of encryption, it is inefficient for 312 high-volume data transfer because a new key exchange is required for every message. 313 However, sometimes we may have no other choice, for example, if there is only bi-directional connectivity 314 to the receiving peer. 315 </t> 316 <t> 317 If the target peer is able to acknowledge the reception of a message, the employed key can be reused. 318 Such acknowledgments can be sent either via a bi-directional UDP connection or a backchannel connection provided 319 by TRANSPORT. 320 This acknowledgment prompts the communicator to offer a new queue to TRANSPORT, which has a higher priority 321 than the default queue but starts with limited capacity. 322 The capacity increases whenever the communicator receives an acknowledgment for a transmission. 323 This queue is suitable for high-volume data transfer, and TRANSPORT will prioritize it if available. 324 </t> 325 <t> 326 There are three distinct message types that are sent and received by UDP communicators: KX, BOX and BROADCAST. 327 For KX and BOX messages, their metadata is chosen such that they are indistinguishable from random. This property 328 does not hold for BROADCAST messages and is not necessary, as they are only sent within a local area network. 329 </t> 330 331 <section anchor="Key_exchange" numbered="true" toc="default"> 332 <name>Key exchange</name> 333 <t> 334 Independent of the type of message queue, a key exchange is initiated at least once by the sending peer. 335 In cases where the receiving peer cannot acknowledge the reception of messages, a key exchange is performed for every message. 336 Two key pairs are needed for the KEM: An ephemeral key pair generated as part of the encapsulation procedure 337 <tt>Encap(pkR) -> (MSK,enc)</tt> and the peer identity of the receiving communciator. 338 The algorithm in use for the KEM is <tt>DHKEM(X25519+Elligator, HKDF-SHA256)</tt> <xref target="LSD0011"/>. 339 The peer identity of the receiving communicator is an Ed25519 public key <tt>pkRed</tt>. 340 In order to use it compliantly with a X25519-based DHKEM as defined in <xref target="LSD0011"/> and <xref target="RFC9180"/>, the 341 curve point must first be converted from Edwards into its birationally equivalent Montgomery form 342 <tt>pkR</tt>. 343 The encapsulation <tt>enc</tt> is transferred via a key exchange (KX) message, as defined in <xref target="figure_udp_initialkx"/>. 344 </t> 345 <figure anchor="figure_udp_initialkx" title="The binary representation of the KX message."> 346 <artwork name="" type="" align="left" alt=""><![CDATA[ 347 0 8 16 24 348 +-----+-----+-----+-----+-----+-----+-----+-----+ 349 | ENC | 350 | | 351 | | 352 | | 353 | | 354 | | 355 | | 356 | | 357 +-----+-----+-----+-----+-----+-----+-----+-----+ 358 | GCM TAG | 359 | | 360 | | 361 | | 362 +-----+-----+-----+-----+-----+-----+-----+-----+ 363 / ENCRYPTED DATA / 364 +-----+-----+-----+-----+-----+-----+-----+-----+ 365 ]]></artwork> 366 </figure> 367 <dl> 368 <dt>ENC</dt> 369 <dd> 370 The 256-bit serialized encapsulation result <tt>enc</tt> of the KEM. 371 </dd> 372 <dt>GCM TAG</dt> 373 <dd> 374 The 128-bit GCM tag is used to authenticate the ciphertext immediately following the header part of the KX message. 375 </dd> 376 <dt>ENCRYPTED DATA</dt> 377 <dd> 378 The remaining data (as indicated by SIZE) is AES-GCM encrypted using the current session key and authenticated 379 through the GCM TAG. 380 </dd> 381 </dl> 382 <t> 383 In order to prevent replay attacks for KX messages, the plaintext resulting from decryption of the encrypted data 384 <bcp14>MUST</bcp14> must start with a session-specific Confirmation header as defined in <xref target="figure_udp_confirmation"/>. 385 It includes the sender's peer identity and a monotonic timestamp, which the receiving peer <bcp14>MUST</bcp14> 386 keep track of each peer identity to reject possible replay attacks. 387 </t> 388 <figure anchor="figure_udp_confirmation" title="The binary representation of the KX Confirmation header"> 389 <artwork name="" type="" align="left" alt=""><![CDATA[ 390 0 8 16 24 32 40 48 56 391 +-----+-----+-----+-----+-----+-----+-----+-----+ 392 | | 393 | SENDER PEER ID | 394 | | 395 | | 396 +-----+-----+-----+-----+-----+-----+-----+-----+ 397 | | 398 | SIGNATURE | 399 | | 400 | | 401 | | 402 | | 403 | | 404 | | 405 +-----+-----+-----+-----+-----+-----+-----+-----+ 406 | MONOTONIC TIMESTAMP | 407 | | 408 | | 409 | | 410 | | 411 | | 412 | | 413 | | 414 +-----+-----+-----+-----+-----+-----+-----+-----+ 415 / PAYLOAD / 416 +-----+-----+-----+-----+-----+-----+-----+-----+ 417 ]]></artwork> 418 </figure> 419 <dl> 420 <dt>SENDER PEER ID</dt> 421 <dd> 422 A 256-bit EdDSA public key (<tt>pkSed</tt>). 423 </dd> 424 <dt>SIGNATURE</dt> 425 <dd> 426 The EdDSA signature is computed with the peer private key 427 over the session metadata, as detailed in <xref target="figure_udp_handshake_sig"/>. 428 </dd> 429 <dt>MONOTONIC TIMESTAMP</dt> 430 <dd> 431 A 64-bit value for the absolute time used by GNUnet, in microseconds and in network byte order. 432 </dd> 433 <dt>PAYLOAD</dt> 434 <dd> 435 The message payload data. 436 </dd> 437 </dl> 438 <t> 439 The confirmation header also includes a signature over the session's metadata, which is signed with the corresponding private key of 440 the sender's peer identity. The data format over which the signature is computed is defined in <xref target="figure_udp_handshake_sig"/> 441 </t> 442 <figure anchor="figure_udp_handshake_sig" title="The wire format of the data structure over which the signature of the UDP Confirmation header is computed."> 443 <artwork name="" type="" align="left" alt=""><![CDATA[ 444 0 8 16 24 32 40 48 56 445 +-----+-----+-----+-----+-----+-----+-----+-----+ 446 | SIZE | PURPOSE (0x0X) | 447 +-----+-----+-----+-----+-----+-----+-----+-----+ 448 | SENDER PEER ID | 449 | | 450 | | 451 | | 452 +-----+-----+-----+-----+-----+-----+-----+-----+ 453 | RECEIVER PEER ID | 454 | | 455 | | 456 | | 457 +-----+-----+-----+-----+-----+-----+-----+-----+ 458 | ENC | 459 | | 460 | | 461 | | 462 +-----+-----+-----+-----+-----+-----+-----+-----+ 463 | MONOTONIC TIMESTAMP | 464 | | 465 | | 466 | | 467 | | 468 | | 469 | | 470 | | 471 +-----+-----+-----+-----+-----+-----+-----+-----+ 472 ]]></artwork> 473 </figure> 474 <dl> 475 <dt>SIZE</dt> 476 <dd> 477 A 32-bit value containing the length of the signed data in bytes 478 in network byte order. 479 </dd> 480 <dt>PURPOSE</dt> 481 <dd> 482 A 32-bit signature purpose flag in network byte order. The value of this 483 field <bcp14>MUST</bcp14> be 33. It defines the context in which 484 the signature is created so that it cannot be reused in other parts 485 of the protocol, including possible future extensions. 486 The value of this field corresponds to an entry in the 487 GANA "GNUnet Signature Purpose" registry <xref target="GANA"/>. 488 </dd> 489 <dt>SENDER PEER ID</dt> 490 <dd> 491 A 256-bit EdDSA public key (<tt>pkSed</tt>). 492 </dd> 493 <dt>RECEIVER PEER ID</dt> 494 <dd> 495 A 256-bit EdDSA public key (<tt>pkRed</tt>). 496 </dd> 497 <dt>ENC</dt> 498 <dd> 499 The 256-bit serialized encapsulation result <tt>enc</tt> of the KEM. 500 </dd> 501 <dt>MONOTONIC TIMESTAMP</dt> 502 <dd> 503 A 64-bit value for the absolute time used by GNUnet, in microseconds and in network byte order. 504 </dd> 505 </dl> 506 <t> 507 Upon receiving a KX message, the receiving peer decapsulates the secret key <tt>MSK</tt> using 508 <tt>MSK <- Decap(skR,enc)</tt>, where <tt>skR</tt> is the X25519 private key derived from 509 its Ed25519 counterpart <tt>skRed</tt>. 510 This <tt>Decap(skR, enc)</tt> procedure is defined in <xref target="LSD0011"/>. 511 Note that the exchange of the receiver peer identity is not within the scope of the UDP communicator's key 512 exchange and is already assumed to be known to the sending peer. 513 One way to exchange peer identities is through the UDP BROADCAST messages as described in 514 <xref target="udp_bc"/>. 515 </t> 516 <t> 517 The MSK is then used together with a sequence number SEQ to derive symmetric encryption key K and initialization 518 vector IV using the "SetupCipher" procedure outlined below. 519 Both the sending and the receiving peer <bcp14>SHOULD</bcp14> store the master shared secret MSK and attribute 520 it to the corresponding peer. 521 <!-- FIXME SEQ is increased by ACKs! --> 522 In case of an acknowledgment from the receiving peer, the established MSK can be reused by iteratively increasing 523 the sequence number SEQ for SetupCipher(MSK, SEQ). 524 </t> 525 <t> 526 Additional data might be inserted after the confirmation header as part of the encrypted data of the KX message. 527 <!-- Wat? --> 528 Padding may be necessary due to the use of AES-GCM. 529 Once a KX message is received and validated, the peer <bcp14>SHOULD</bcp14> try to acknowledge the established 530 MSK to switch to a stable session. 531 The details about the acknowledgment process and subsequent message exchange can be found in 532 <xref target="udp_message_exchange"/>. 533 </t> 534 </section> 535 <section anchor="udp_key_schedule" numbered="true" toc="default"> 536 <name>Key schedule</name> 537 <t> 538 Once a shared secret MSK is established through the Elligator KEM, a symmetric key and 539 initialization vector are derived. 540 According to a key schedule from a 32-bit sequence number SEQ (in network byte order) and the MSK. 541 The initial value of the sequence number is 0. 542 </t> 543 <artwork anchor="setup_cipher" name="" type="" align="left" alt=""><![CDATA[ 544 SetupCipher(MSK,SEQ): 545 K := HKDF-Expand (MSK, "gnunet-communicator-udp-key"||SEQ, 32) 546 IV := HKDF-Expand (MSK, "gnunet-communicator-udp-iv"||SEQ, 12) 547 return K,IV 548 ]]></artwork> 549 <t> 550 SetupCipher returns a 256-bit AES key "K" as well as a 96-bit "IV" for use in AES-GCM. 551 </t> 552 <t> 553 Each derived key is uniquely identified using a separately derived 554 256-bit key ID (KID) derived in a similar fashion: 555 </t> 556 <artwork anchor="derive_kid" name="" type="" align="left" alt=""><![CDATA[ 557 DeriveKID(MSK,SEQ): 558 KID := HKDF-Expand (MSK, "gnunet-communicator-udp-kid"||SEQ, 32) 559 return KID 560 ]]></artwork> 561 <t> 562 The sequence number SEQ for any shared secret is initially 0 and incremented on the sender side for each 563 successive encryption and on the receiver side for each decryption. 564 </t> 565 </section> 566 <section anchor="udp_message_exchange" numbered="true" toc="default"> 567 <name>Message exchange</name> 568 <t> 569 KX messages, as presented in <xref target="Key_exchange"/>, are sufficient for transferring arbitrary amounts of data. This way of 570 communicating is slow due to the establishment of a shared secret for each message using asymmetric cryptography. The UDP communicator 571 offers a faster way of communicating by reusing a shared secret. For this purpose, the receiver of a message <bcp14>SHOULD</bcp14> 572 acknowledge the reception to signal the sender that the same shared secret can be reused. The sender can then use the acknowledged shared 573 secret and increment the utilized sequence number for each subsequent message to derive new symmetric key material. These messages are 574 sent as BOX messages, which incorporate a KID as defined in <xref target="derive_kid"/> to identify both the master shared secret and 575 sequence number. The wire format of a BOX message is depicted in <xref target="figure_udp_box"/>. 576 </t> 577 <figure anchor="figure_udp_box" title="The binary representation of the UDP Box message."> 578 <artwork name="" type="" align="left" alt=""><![CDATA[ 579 0 8 16 24 580 +-----+-----+-----+-----+-----+-----+-----+-----+ 581 | KEY ID | 582 | | 583 | | 584 | | 585 | | 586 | | 587 | | 588 | | 589 +-----+-----+-----+-----+-----+-----+-----+-----+ 590 | GCM TAG | 591 | | 592 | | 593 | | 594 +-----+-----+-----+-----+-----+-----+-----+-----+ 595 / ENCRYPTED DATA / 596 +-----+-----+-----+-----+-----+-----+-----+-----+ 597 ]]></artwork> 598 </figure> 599 <dl> 600 <dt>KEY ID</dt> 601 <dd> 602 A 256-bit value containing the KID of the symmetric key to 603 use for decryption as derived using DeriveKID as described in <xref target="derive_kid"/>. 604 </dd> 605 <dt>GCM TAG</dt> 606 <dd> 607 A 128-bit GCM tag used to authenticate the ciphertext immediately following this TCP Box header. 608 </dd> 609 <dt>ENCRYPTED DATA</dt> 610 <dd> 611 The remaining data (as indicated by SIZE) is AES-GCM encrypted using the 612 derived key and IV identified by the KID. 613 </dd> 614 </dl> 615 <t> 616 An acknowledgment can be sent in various ways is ultimately decided by TRANSPORT. If the target peer can also reach the sending peer via 617 UDP messages, both KX messages or BOX messages could be utilized to send the acknowledgment as their payload. TRANSPORT could also choose 618 to utilize another communicator type to send the acknowledgment (backchannel). Either way, acknowledgments are always sent in form of an 619 ACK header. The wire format of the ACK header can be seen in <xref target="figure_udp_ack"/>. 620 </t> 621 <figure anchor="figure_udp_ack" title="The wire format of an ACK header."> 622 <artwork name="" type="" align="left" alt=""><![CDATA[ 623 0 16 624 +-----+-----+-----+-----+-----+-----+-----+-----+ 625 | SIZE | TYPE (0x0X) | 626 +-----+-----+-----+-----+-----+-----+-----+-----+ 627 | SEQ ACK | 628 +-----+-----+-----+-----+-----+-----+-----+-----+ 629 | MSK HASH (fromerly CMAC) | 630 | | 631 | | 632 | | 633 | | 634 | | 635 | | 636 | | 637 | | 638 | | 639 | | 640 | | 641 | | 642 | | 643 | | 644 | | 645 +-----+-----+-----+-----+-----+-----+-----+-----+ 646 ]]></artwork> 647 </figure> 648 <dl> 649 <dt>SIZE</dt> 650 <dd> 651 A 16-bit value containing the length of the message in bytes in network byte order. 652 </dd> 653 <dt>TYPE</dt> 654 <dd> 655 A 16-bit signature type flag in network byte order. The value of this field MUST be 1460. 656 </dd> 657 <dt>SEQ ACK</dt> 658 <dd> 659 Sequence acknowledgment limit. Specifies the current maximum sequence number supported by the receiver. 660 </dd> 661 <dt>MSK HASH</dt> 662 <dd> 663 CMAC of the base key being acknowledged. 664 </dd> 665 </dl> 666 <t> 667 To avoid having to acknowledge every single message individually, the sender of an acknowledgment can specify the allowed sequence number for 668 the sender in the ACK header. 669 The receiver <bcp14>MUST</bcp14> precalculate all derived keys and corresponding KIDs for which it has already sent ACKs. Consequently, for 670 valid sequence numbers below the current ACK limit, KID should match one of the precalculated keys in the key cache, and the encrypted data 671 can be decrypted. Otherwise, the message <bcp14>MUST</bcp14> be rejected. 672 </t> 673 <t> 674 Multiple shared secrets can be used simultaneously between the sending peer and target peer. Should the 675 sending peer use up all acknowledgments for all its shared secrets, messages are sent through KX messages again. 676 </t> 677 </section> 678 <section anchor="udp_rekeying" numbered="true" toc="default"> 679 <name>Rekeying</name> 680 <t> 681 The amount of data that can be encrypted with a shared secret <bcp14>MUST</bcp14> be limited. Before 682 the capacity of a shared secret is used up, the sender initiates rekeying by sending a new ephemeral public key 683 for a key exchange. As multiple shared secrets can be used simultaneously, rekeying doesn't necessarily delete the old shared secret if its 684 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 685 ephemeral public key is encrypted, there is no need to use Elligator's encoding function and we use the normal, unobfuscated 686 <tt>DHKEM(X25519, HKDF-SHA256)</tt>. The wire format of the Rekey header can 687 be seen in <xref target="figure_udp_rekey"/>. 688 </t> 689 <figure anchor="figure_udp_rekey" title="The wire format of a Rekey header."> 690 <artwork name="" type="" align="left" alt=""><![CDATA[ 691 0 16 692 +-----+-----+-----+-----+-----+-----+-----+-----+ 693 | SIZE | TYPE (0x0X) | 694 +-----+-----+-----+-----+-----+-----+-----+-----+ 695 | ENC | 696 | | 697 | | 698 | | 699 | | 700 | | 701 | | 702 | | 703 +-----+-----+-----+-----+-----+-----+-----+-----+ 704 ]]></artwork> 705 </figure> 706 <dl> 707 <dt>SIZE</dt> 708 <dd> 709 A 16-bit value containing the length of the message in bytes in network byte order. 710 </dd> 711 <dt>TYPE</dt> 712 <dd> 713 A 16-bit signature type flag in network byte order. The value of this field MUST be 1462. 714 </dd> 715 <dt>ENC</dt> 716 <dd> 717 The 256-bit serialized encapsulation result <tt>enc</tt> of the KEM. 718 </dd> 719 </dl> 720 <t> 721 Additional data might be inserted after the Rekey header as part of the encrypted data of the BOX message. Padding 722 may be necessary due to the use of AES-GCM. 723 </t> 724 </section> 725 <section anchor="udp_bc" numbered="true" toc="default"> 726 <name>Broadcast</name> 727 <t> 728 BROADCAST messages are sent by peers to announce their presence. Those messages are only distributed in the LAN and sent in cleartext. 729 </t> 730 <figure anchor="figure_udp_broadcast" title="The binary representation of the udp BROADCAST message"> 731 <artwork name="" type="" align="left" alt=""><![CDATA[ 732 0 8 16 24 32 40 48 56 733 +-----+-----+-----+-----+-----+-----+-----+-----+ 734 | | 735 | SENDER PEER ID | 736 | | 737 | | 738 +-----+-----+-----+-----+-----+-----+-----+-----+ 739 | | 740 | SIGNATURE | 741 | | 742 | | 743 | | 744 | | 745 | | 746 | | 747 +-----+-----+-----+-----+-----+-----+-----+-----+ 748 ]]></artwork> 749 </figure> 750 <dl> 751 <dt>SENDER PEER ID</dt> 752 <dd> 753 A 256-bit EdDSA public key (<tt>pkSed</tt>). 754 </dd> 755 <dt>SIGNATURE</dt> 756 <dd> 757 The EdDSA signature is computed with the announced peer private key 758 over the peer identity and address hash, as depicted in <xref target="figure_udp_broadcast_sig"/>. 759 </dd> 760 </dl> 761 <figure anchor="figure_udp_broadcast_sig" title="The wire format of the data structure over which the signature of the UDP BROADCAST message is computed."> 762 <artwork name="" type="" align="left" alt=""><![CDATA[ 763 0 8 16 24 32 40 48 56 764 +-----+-----+-----+-----+-----+-----+-----+-----+ 765 | SIZE | PURPOSE (0x0X) | 766 +-----+-----+-----+-----+-----+-----+-----+-----+ 767 | SENDER PEER ID | 768 | | 769 | | 770 | | 771 +-----+-----+-----+-----+-----+-----+-----+-----+ 772 | ADDRESS HASH | 773 | | 774 | | 775 | | 776 +-----+-----+-----+-----+-----+-----+-----+-----+ 777 ]]></artwork> 778 </figure> 779 <dl> 780 <dt>SIZE</dt> 781 <dd> 782 A 32-bit value containing the length of the signed data in bytes 783 in network byte order. 784 </dd> 785 <dt>PURPOSE</dt> 786 <dd> 787 A 32-bit signature purpose flag in network byte order. The value of this 788 field <bcp14>MUST</bcp14> be 34. It defines the context in which 789 the signature is created so that it cannot be reused in other parts 790 of the protocol, including possible future extensions. 791 The value of this field corresponds to an entry in the 792 GANA "GNUnet Signature Purpose" registry <xref target="GANA"/>. 793 </dd> 794 <dt>SENDER PEER ID</dt> 795 <dd> 796 A 256-bit EdDSA public key (<tt>pkSed</tt>). 797 </dd> 798 <dt>ADDRESS HASH</dt> 799 <dd> 800 Hash of the sender's UDP address. 801 </dd> 802 </dl> 803 </section> 804 </section> 805 <section anchor="tcp_comm" numbered="true" toc="default"> 806 <name>TCP communicator</name> 807 <t> 808 TCP communicators always establish an encrypted and bi-directional communication channel. For 809 each direction of communication, a dedicated shared secret is used to both encrypt and 810 authenticate messages. These shared secrets are exchanged during the initial handshake. After a 811 certain amount of data has been transmitted, rekeying occurs to renew the key material. 812 Note that the rekeying process is triggered individually for each communication direction. 813 </t> 814 <t> 815 To achieve a zero-plaintext design, we <bcp14>MUST</bcp14> use the mac-then-encrypt approach to 816 hide the message size on the wire. Extra caution needs to be taken due to the vulnerability of 817 the mac-then-encrypt design to padding oracle attacks. To mitigate this issue, the TCP communicator 818 uses AES-CTR for encryption, which does not require padding. Additionally, the use of ephemeral keys 819 combined with monotonic timestamps limits an attacker's ability to exploit the oracle, as replay 820 attacks are prevented. 821 </t> 822 <section anchor="tcp_handshake" numbered="true" toc="default"> 823 <name>Handshake</name> 824 <t> 825 The main purpose of the handshake is to establish shared key material for each direction of the communication 826 channel. 827 The initiating TCP Communicator starts the handshake by sending an encapsulation from the Elligator KEM 828 defined in <xref target="elligator_dhkem"/>. 829 </t> 830 <t> 831 The encapsulation <bcp14>MUST</bcp14> be directly followed by an encrypted TCP handshake message, as shown in 832 <xref target="figure_tcp_handshake"/>. 833 In addition to the peer identity of the sender and a timestamp, it contains a nonce as a challenge for the 834 receiving TCP communicator. 835 All data is authenticated with a signature. 836 </t> 837 <figure anchor="figure_tcp_handshake" title="The binary representation of the TCP handshake message."> 838 <artwork name="" type="" align="left" alt=""><![CDATA[ 839 0 8 16 24 32 40 48 56 840 +-----+-----+-----+-----+-----+-----+-----+-----+ 841 | SENDER PEER ID | 842 | | 843 | | 844 | | 845 +-----+-----+-----+-----+-----+-----+-----+-----+ 846 | SIGNATURE | 847 | | 848 | | 849 | | 850 | | 851 | | 852 | | 853 | | 854 +-----+-----+-----+-----+-----+-----+-----+-----+ 855 | MONOTONIC TIMESTAMP | 856 +-----+-----+-----+-----+-----+-----+-----+-----+ 857 | NONCE | 858 | | 859 | | 860 | | 861 +-----+-----+-----+-----+-----+-----+-----+-----+ 862 ]]></artwork> 863 </figure> 864 <dl> 865 <dt>SENDER PEER ID</dt> 866 <dd> 867 A 256-bit EdDSA public key (<tt>pkSed</tt>). 868 </dd> 869 <dt>SIGNATURE</dt> 870 <dd> 871 A 512-bit EdDSA signature. The signature is calculated over 872 the data as defined in <xref target="figure_tcp_handshake_sig"/>. 873 </dd> 874 <dt>MONOTONIC TIMESTAMP</dt> 875 <dd> 876 A 64-bit value for the absolute time used by GNUnet, in microseconds and in network byte order. 877 </dd> 878 <dt>NONCE</dt> 879 <dd> 880 A 256-bit random value used as a challenge to be signed in a TCP handshake acknowledgment message. 881 </dd> 882 </dl> 883 <t> 884 The data scheme used for computing the signature is depicted in <xref target="figure_tcp_handshake_sig"/>. 885 </t> 886 <figure anchor="figure_tcp_handshake_sig" title="The wire format used for creating the signature of the tcp handshake message."> 887 <artwork name="" type="" align="left" alt=""><![CDATA[ 888 0 8 16 24 32 40 48 56 889 +-----+-----+-----+-----+-----+-----+-----+-----+ 890 | SIZE | PURPOSE (0x0X) | 891 +-----+-----+-----+-----+-----+-----+-----+-----+ 892 | SENDER PEER ID | 893 | | 894 | | 895 | | 896 +-----+-----+-----+-----+-----+-----+-----+-----+ 897 | RECEIVER PEER ID | 898 | | 899 | | 900 | | 901 +-----+-----+-----+-----+-----+-----+-----+-----+ 902 | REPRESENTATIVE | 903 | | 904 | | 905 | | 906 +-----+-----+-----+-----+-----+-----+-----+-----+ 907 | MONOTONIC TIMESTAMP | 908 | | 909 | | 910 | | 911 | | 912 | | 913 | | 914 | | 915 +-----+-----+-----+-----+-----+-----+-----+-----+ 916 | NONCE | 917 | | 918 | | 919 | | 920 +-----+-----+-----+-----+-----+-----+-----+-----+ 921 ]]></artwork> 922 </figure> 923 <dl> 924 <dt>SIZE</dt> 925 <dd> 926 A 32-bit value containing the length of the signed data in bytes 927 in network byte order. 928 </dd> 929 <dt>PURPOSE</dt> 930 <dd> 931 A 32-bit signature purpose flag in network byte order. The value of this 932 field <bcp14>MUST</bcp14> be 31. It defines the context in which 933 the signature is created so that it cannot be reused in other parts 934 of the protocol, including possible future extensions. 935 The value of this field corresponds to an entry in the 936 GANA "GNUnet Signature Purpose" registry <xref target="GANA"/>. 937 </dd> 938 <dt>SENDER PEER ID</dt> 939 <dd> 940 A 256-bit EdDSA public key. 941 </dd> 942 <dt>RECEIVER PEER ID</dt> 943 <dd> 944 A 256-bit EdDSA public key. 945 </dd> 946 <dt>REPRESENTATIVE</dt> 947 <dd> 948 The 256-bit serialized encapsulation result of the KEM. 949 </dd> 950 <dt>MONOTONIC TIMESTAMP</dt> 951 <dd> 952 A 64-bit value for the absolute time used by GNUnet, in microseconds and in network byte order. 953 </dd> 954 <dt>NONCE</dt> 955 <dd> 956 A 256-bit random value. 957 </dd> 958 </dl> 959 <t> 960 Upon reception of the ephemeral public key, the receiving TCP communicator carries out the decapsulation step of the 961 key exchange and retrieves the shared key material. The subsequently received TCP handshake message is then decrypted and verified. 962 If the signature is invalid, the connection is dropped. 963 In the case of a valid signature, the receiving TCP communicator sends its own TCP handshake message to establish 964 shared key material for outgoing messages and also replies with an encrypted TCP handshake acknowledgment message as defined 965 in <xref target="figure_tcp_handshake_ack"/>. 966 </t> 967 <figure anchor="figure_tcp_handshake_ack" title="The binary representation of the tcp handshake acknowledgment message."> 968 <artwork name="" type="" align="left" alt=""><![CDATA[ 969 0 8 16 24 970 +-----+-----+-----+-----+-----+-----+-----+-----+ 971 | SIZE | TYPE (0x0X) | 972 +-----+-----+-----+-----+-----+-----+-----+-----+ 973 | SENDER PEER ID | 974 | | 975 | | 976 | | 977 | | 978 | | 979 | | 980 | | 981 +-----+-----+-----+-----+-----+-----+-----+-----+ 982 | RECEIVER PEER ID | 983 | | 984 | | 985 | | 986 | | 987 | | 988 | | 989 | | 990 +-----+-----+-----+-----+-----+-----+-----+-----+ 991 | SIGNATURE | 992 | | 993 | | 994 | | 995 | | 996 | | 997 | | 998 | | 999 +-----+-----+-----+-----+-----+-----+-----+-----+ 1000 | MONOTONIC TIMESTAMP | 1001 | | 1002 +-----+-----+-----+-----+-----+-----+-----+-----+ 1003 | NONCE | 1004 | | 1005 | | 1006 | | 1007 | | 1008 | | 1009 | | 1010 | | 1011 +-----+-----+-----+-----+-----+-----+-----+-----+ 1012 ]]></artwork> 1013 </figure> 1014 <dl> 1015 <dt>SIZE</dt> 1016 <dd> 1017 A 16-bit value containing the length of the message in bytes 1018 in network byte order. 1019 </dd> 1020 <dt>TYPE</dt> 1021 <dd> 1022 A 16-bit signature type flag in network byte order. The value of this 1023 field <bcp14>MUST</bcp14> be 1453. 1024 </dd> 1025 <dt>SENDER PEER ID</dt> 1026 <dd> 1027 A 256-bit EdDSA public key. 1028 </dd> 1029 <dt>RECEIVER PEER ID</dt> 1030 <dd> 1031 A 256-bit EdDSA public key. 1032 </dd> 1033 <dt>Signature</dt> 1034 <dd> 1035 A 512-bit EdDSA signature. The signature is calculated over 1036 the data as defined in <xref target="figure_tcp_handshake_ack_sig"/>. 1037 </dd> 1038 <dt>MONOTONIC TIMESTAMP</dt> 1039 <dd> 1040 A 64-bit value for the absolute time used by GNUnet, in microseconds and in network byte order. 1041 </dd> 1042 <dt>NONCE</dt> 1043 <dd> 1044 A 256-bit random value. 1045 </dd> 1046 </dl> 1047 <t> 1048 The data scheme used for computing the signature for the acknowledgment message is depicted 1049 in <xref target="figure_tcp_handshake_ack_sig"/>. 1050 </t> 1051 <figure anchor="figure_tcp_handshake_ack_sig" title="The wire format used for creating the signature of the tcp handshake acknowledgment message."> 1052 <artwork name="" type="" align="left" alt=""><![CDATA[ 1053 0 8 16 24 1054 +-----+-----+-----+-----+-----+-----+-----+-----+ 1055 | SIZE | TYPE (0x0X) | 1056 +-----+-----+-----+-----+-----+-----+-----+-----+ 1057 | SENDER PEER ID | 1058 | | 1059 | | 1060 | | 1061 | | 1062 | | 1063 | | 1064 | | 1065 +-----+-----+-----+-----+-----+-----+-----+-----+ 1066 | RECEIVER PEER ID | 1067 | | 1068 | | 1069 | | 1070 | | 1071 | | 1072 | | 1073 | | 1074 +-----+-----+-----+-----+-----+-----+-----+-----+ 1075 | MONOTONIC TIMESTAMP | 1076 | | 1077 +-----+-----+-----+-----+-----+-----+-----+-----+ 1078 | NONCE | 1079 | | 1080 / / 1081 / / 1082 | | 1083 +-----+-----+-----+-----+-----+-----+-----+-----+ 1084 ]]></artwork> 1085 </figure> 1086 <dl> 1087 <dt>SIZE</dt> 1088 <dd> 1089 A 16-bit value containing the length of the message in bytes 1090 in network byte order. 1091 </dd> 1092 <dt>TYPE</dt> 1093 <dd> 1094 A 16-bit signature type flag in network byte order. The value of this 1095 field <bcp14>MUST</bcp14> be 39. 1096 </dd> 1097 <dt>SENDER PEER ID</dt> 1098 <dd> 1099 A 256-bit EdDSA public key. 1100 </dd> 1101 <dt>RECEIVER PEER ID</dt> 1102 <dd> 1103 A 256-bit EdDSA public key. 1104 </dd> 1105 <dt>MONOTONIC TIMESTAMP</dt> 1106 <dd> 1107 A 64-bit value for the absolute time used by GNUnet, in microseconds and in network byte order. 1108 </dd> 1109 <dt>NONCE</dt> 1110 <dd> 1111 A 256-bit random value. 1112 </dd> 1113 </dl> 1114 <t> 1115 The initiating TCP communicator also replies with a TCP handshake acknowledgment message after receiving 1116 a valid TCP handshake message. Lastly, each party verifies both the signature and the challenge within the received 1117 TCP handshake acknowledgment message, thus completing the handshake. 1118 </t> 1119 </section> 1120 <section anchor="tcp_KEM" numbered="true" toc="default"> 1121 <name>Key exchange</name> 1122 <t> 1123 During the initial handshake, each communication channel performs the Elligator KEM defined in 1124 <xref target="elligator_dhkem"/>. 1125 The resulting shared secret us used in an AES-CTR encryption with HMAC-SHA512. 1126 Subsequent key exchanges are performed with each rekeying. 1127 More about the initial handshake and rekeying can be found in <xref target="tcp_handshake"/> and 1128 <xref target="tcp_rekeying"/>, respectively. 1129 </t> 1130 <t> 1131 Let (REC_SK, REC_ID) be the receiver peer's EdDSA key pair. 1132 The sender peer initiates the key exchange using the Elligator KEM from <xref target="elligator_dhkem"/> 1133 resulting in an encapsulation and initial master secret key MSK. 1134 MSK is used to derive a symmetric encryption and HMAC key as well as an initialization vector using 1135 the procedure "SetupCipher": 1136 </t> 1137 <artwork anchor="setup_cipher_tcp" name="" type="" align="left" alt=""><![CDATA[ 1138 SetupCipher(REC_ID, MSK): 1139 K := HKDF-Expand (MSK, "gnunet-communicator-tcp-key", 32) 1140 IV := HKDF-Expand (MSK, "gnunet-communicator-tcp-ctr, 16) 1141 K_mac := HKDF-Expand (MSK, "gnunet-communicator-tcp-hmac, 64) 1142 return K,IV,K_mac 1143 ]]></artwork> 1144 <t> 1145 Note that the initiating TCP communicator can immediately encrypt the first TCP handshake message when 1146 sending it. 1147 As soon as the receiving TCP communicator receives and decapsulates the representative, it can decrypt the 1148 following TCP handshake message. 1149 The same applies to the TCP handshake message sent by the receiving TCP communicator. 1150 </t> 1151 </section> 1152 <section anchor="tcp_message_exchange" numbered="true" toc="default"> 1153 <name>Message exchange</name> 1154 <t> 1155 Once the handshake is completed, actual payloads can be exchanged bi-directionally using TCP BOX messages. A TCP Box message 1156 consists of a TCP BOX message, as defined in <xref target="figure_tcp_box"/>, followed by the payload. Both parts are encrypted 1157 before being sent to the receiving peer. 1158 </t> 1159 <t> 1160 TCP Box messages follow the mac-then-encrypt approach to hide the size of the payload and achieve a zero-plaintext design. 1161 The HMAC utilizes SHA512 as the underlying hash function and is ratcheted after each operation. Given the mac-then-encrypt 1162 approach, additional safeguards are needed to protect against Oracle padding attacks. Therefore, we <bcp14>MUST</bcp14> use 1163 a padding-free encryption scheme such as AES-CTR for encryption. Additionally, we restrict the attacker's ability to replay 1164 attacks by exchanging new key material after a randomly chosen amount of transferred data, as described in 1165 <xref target="tcp_rekeying"/>. The necessary key exchanges to establish the new key material are protected using monotonic 1166 timestamps. 1167 </t> 1168 <figure anchor="figure_tcp_box" title="The binary representation of the TCP BOX message."> 1169 <artwork name="" type="" align="left" alt=""><![CDATA[ 1170 0 8 16 24 1171 +-----+-----+-----+-----+-----+-----+-----+-----+ 1172 | SIZE | TYPE (0x0X) | 1173 +-----+-----+-----+-----+-----+-----+-----+-----+ 1174 | HASHCODE | 1175 | | 1176 | | 1177 | | 1178 | | 1179 | | 1180 | | 1181 | | 1182 +-----+-----+-----+-----+-----+-----+-----+-----+ 1183 1184 ]]></artwork> 1185 </figure> 1186 <dl> 1187 <dt>SIZE</dt> 1188 <dd> 1189 A 16-bit value containing the length of the message in bytes 1190 in network byte order. 1191 </dd> 1192 <dt>TYPE</dt> 1193 <dd> 1194 A 16-bit signature type flag in network byte order. The value of this 1195 field <bcp14>MUST</bcp14> be 1451. 1196 </dd> 1197 <dt>HASHCODE</dt> 1198 <dd> 1199 A 256-bit HMAC-SHA512 hashcode for the subsequently sent payload. 1200 </dd> 1201 </dl> 1202 </section> 1203 1204 <section anchor="tcp_rekeying" numbered="true" toc="default"> 1205 <name>Rekeying</name> 1206 <t> 1207 After each key exchange, up to 400 MB of data is transferred until rekeying is triggered by the sender of the communication direction. 1208 The actual amount of transferred data <bcp14>SHOULD</bcp14> be chosen randomly. If the chosen byte quantity is not reached after 1209 one day, rekeying is set off anyway. 1210 </t> 1211 <t> 1212 The receiving communicator is signaled about a rekeying through the dispatch of a TCP Rekey message, as defined in 1213 <xref target="figure_tcp_rekey"/>. The message <bcp14>MUST</bcp14> be encrypted with the current key. Due to the encryption of the message, 1214 the encoding of the new ephemeral public key with Elligator is not needed. Similarly to the initial handshake, the ephemeral public key 1215 is used to perform a key exchange from which new key material for the encryption and authentication code scheme is derived. For further 1216 details, please refer to <xref target="tcp_KEM"/>. Note that the rekeying process doesn't involve an acknowledgment by the receiver of 1217 a TCP Rekey message. So the sender might send new payload encrypted by the new key right after sending the TCP Rekey message. 1218 </t> 1219 <figure anchor="figure_tcp_rekey" title="The binary representation of the TCP Rekey message."> 1220 <artwork name="" type="" align="left" alt=""><![CDATA[ 1221 0 8 16 24 1222 +-----+-----+-----+-----+-----+-----+-----+-----+ 1223 | SIZE | TYPE (0x0X) | 1224 +-----+-----+-----+-----+-----+-----+-----+-----+ 1225 | HASHCODE | 1226 | | 1227 | | 1228 | | 1229 | | 1230 | | 1231 | | 1232 | | 1233 +-----+-----+-----+-----+-----+-----+-----+-----+ 1234 | ENC | 1235 | | 1236 | | 1237 | | 1238 | | 1239 | | 1240 | | 1241 | | 1242 +-----+-----+-----+-----+-----+-----+-----+-----+ 1243 | SIGNATURE | 1244 | | 1245 | | 1246 | | 1247 | | 1248 | | 1249 | | 1250 | | 1251 +-----+-----+-----+-----+-----+-----+-----+-----+ 1252 | MONOTONIC TIMESTAMP | 1253 | | 1254 +-----+-----+-----+-----+-----+-----+-----+-----+ 1255 ]]></artwork> 1256 </figure> 1257 <dl> 1258 <dt>SIZE</dt> 1259 <dd> 1260 A 16-bit value containing the length of the message in bytes 1261 in network byte order. 1262 </dd> 1263 <dt>TYPE</dt> 1264 <dd> 1265 A 16-bit signature type flag in network byte order. The value of this 1266 field <bcp14>MUST</bcp14> be 1450. 1267 </dd> 1268 <dt>HASHCODE</dt> 1269 <dd> 1270 A 256-bit HMAC-SHA512 hashcode of this TCP Rekey message. The hashcode is 1271 computed with the hashcode field initially set to zero and is inserted afterward. 1272 </dd> 1273 <dt>ENC</dt> 1274 <dd> 1275 The 256-bit serialized encapsulation result <tt>enc</tt> of the KEM. 1276 </dd> 1277 <dt>Signature</dt> 1278 <dd> 1279 A 512-bit EdDSA signature. The signature is calculated over 1280 the data as defined in <xref target="figure_tcp_rekey_sig"/>. 1281 </dd> 1282 <dt>MONOTONIC TIMESTAMP</dt> 1283 <dd> 1284 A 64-bit value for the absolute time used by GNUnet, in microseconds and in network byte order. 1285 </dd> 1286 </dl> 1287 <figure anchor="figure_tcp_rekey_sig" title="The wire format used for creating the signature of the TCP Rekey message."> 1288 <artwork name="" type="" align="left" alt=""><![CDATA[ 1289 0 8 16 24 32 40 48 56 1290 +-----+-----+-----+-----+-----+-----+-----+-----+ 1291 | SIZE | PURPOSE (0x0X) | 1292 +-----+-----+-----+-----+-----+-----+-----+-----+ 1293 | SENDER PEER ID | 1294 | | 1295 | | 1296 | | 1297 +-----+-----+-----+-----+-----+-----+-----+-----+ 1298 | RECEIVER PEER ID | 1299 | | 1300 | | 1301 | | 1302 +-----+-----+-----+-----+-----+-----+-----+-----+ 1303 | ENC | 1304 | | 1305 | | 1306 | | 1307 +-----+-----+-----+-----+-----+-----+-----+-----+ 1308 | MONOTONIC TIMESTAMP | 1309 | | 1310 | | 1311 | | 1312 | | 1313 | | 1314 | | 1315 | | 1316 +-----+-----+-----+-----+-----+-----+-----+-----+ 1317 ]]></artwork> 1318 </figure> 1319 <dl> 1320 <dt>SIZE</dt> 1321 <dd> 1322 A 32-bit value containing the length of the signed data in bytes 1323 in network byte order. 1324 </dd> 1325 <dt>PURPOSE</dt> 1326 <dd> 1327 A 32-bit signature purpose flag in network byte order. The value of this 1328 field <bcp14>MUST</bcp14> be 32. It defines the context in which 1329 the signature is created so that it cannot be reused in other parts 1330 of the protocol, including possible future extensions. 1331 The value of this field corresponds to an entry in the 1332 GANA "GNUnet Signature Purpose" registry <xref target="GANA"/>. 1333 </dd> 1334 <dt>SENDER PEER ID</dt> 1335 <dd> 1336 A 256-bit EdDSA public key (<tt>pkSed</tt>). 1337 </dd> 1338 <dt>RECEIVER PEER ID</dt> 1339 <dd> 1340 A 256-bit EdDSA public key (<tt>pkRed</tt>). 1341 </dd> 1342 <dt>ENC</dt> 1343 <dd> 1344 The 256-bit serialized encapsulation result <tt>enc</tt> of the KEM. 1345 </dd> 1346 <dt>MONOTONIC TIMESTAMP</dt> 1347 <dd> 1348 A 64-bit value for the absolute time used by GNUnet, in microseconds and in network byte order. 1349 </dd> 1350 </dl> 1351 </section> 1352 </section> 1353 <section anchor="http3_comm" numbered="true" toc="default"> 1354 <name>HTTP/3 communicator</name> 1355 <t> 1356 The HTTP/3 <xref target="RFC9114"/> communicator operates over a bidirectional communication channel, 1357 with the client initiating the connection and the server on the receiving end. 1358 Once the connection is successfully established, messages are transmitted via POST and GET requests, 1359 and all communication is secured using TLS. 1360 </t> 1361 <t> 1362 Upon successfully establishing an HTTP/3 connection, the client <bcp14>MUST</bcp14> immediately transmit 1363 its <tt>PeerIdentity</tt> in a POST. 1364 The server will store this PeerIdentity to identify the client. 1365 Following this exchange, data exchange between the client and server can proceed. 1366 </t> 1367 <t> 1368 When the client needs to send a message, it uses a POST request to transmit the data to the server. 1369 While the server cannot initiate messages independently, it can include data in its response to a 1370 client's POST request. 1371 </t> 1372 <t> 1373 To enable the server to proactively send data when the client has no data to transmit, 1374 long polling is used. 1375 The client sends GET requests to the server, which <bcp14>MAY</bcp14> not immediately respond 1376 but instead sets a timer for each request. 1377 The server responds either when the timer expires or when there is data to send. 1378 Upon receiving a response, the client immediately sends a new GET request to maintain an adequate 1379 number of long polling requests with the server. 1380 </t> 1381 <figure anchor="figure_http3_msg" title="The wire format of exchanged messages."> 1382 <artwork name="" type="" align="left" alt=""><![CDATA[ 1383 0 8 16 24 32 40 48 56 1384 +-----+-----+-----+-----+-----+-----+-----+-----+ 1385 | SIZE | TYPE (0x0X) | 1386 +-----+-----+-----+-----+-----+-----+-----+-----+ 1387 | MESSAGE | 1388 | | 1389 | | 1390 | | 1391 +-----+-----+-----+-----+-----+-----+-----+-----+ 1392 ]]></artwork> 1393 </figure> 1394 <dl> 1395 <dt>SIZE</dt> 1396 <dd> 1397 A 16-bit value containing the length of the signed data in bytes 1398 in network byte order. 1399 </dd> 1400 <dt></dt> 1401 <dd> 1402 A 16-bit type flag in network byte order. The value of this 1403 field <bcp14>MUST</bcp14> be XY. 1404 The value of this field corresponds to an entry in the 1405 GANA "GNUnet Message Type" registry <xref target="GANA"/>. 1406 </dd> 1407 <dt>MESSAGE</dt> 1408 <dd> 1409 The message. 1410 </dd> 1411 </dl> 1412 <t> 1413 Example POST: 1414 </t> 1415 <artwork name="" type="" align="left" alt=""><![CDATA[ 1416 :method: POST 1417 :scheme: https 1418 :authority: PEER'S IP ADDRESS 1419 :path: / 1420 content-type: application/octet-stream 1421 content-length: LENGTH OF MESSAGE 1422 ]]></artwork> 1423 <t> 1424 If server no data to send it will respond with HTTP status OK (200). 1425 If server has data to send it will respond with HTTP status OK and 1426 a response body with a message (<xref target="figure_http3_msg"/>) and 1427 content type <tt>application/octet-stream</tt> 1428 </t> 1429 <t> 1430 GET request example (long polling): 1431 </t> 1432 <artwork name="" type="" align="left" alt=""><![CDATA[ 1433 :method: GET 1434 :scheme: https 1435 :authority: PEER'S IP ADDRESS 1436 :path: / 1437 ]]></artwork> 1438 <t> 1439 If server no data to send and the long poll times out it will 1440 respond with status 204. 1441 If server has data to send it will respond with HTTP status OK (200) 1442 a response body with a message (<xref target="figure_http3_msg"/>) and 1443 content type <tt>application/octet-stream</tt>. 1444 </t> 1445 <section anchor="http3_handshake" numbered="true" toc="default"> 1446 <name>Handshake</name> 1447 <t> 1448 The public keys in the certificates in use as part of the TLS handshake 1449 are not verified or evaluated against a trust store. 1450 The initial message by the initiating peer (the HTTP/3 client) will 1451 contain the peer identity. 1452 In the future, the peer identity should be part of the TLS handshake instead. 1453 </t> 1454 </section> 1455 </section> 1456 <section anchor="libp2p_comm" numbered="true" toc="default"> 1457 <name>libp2p communicator</name> 1458 <t> 1459 The libp2p communicator uses libp2p as a means of communication. 1460 libp2p is "a modular networking framework bundled together as a full stack 1461 of protocols for peer-to-peer systems" and thus shares the general 1462 approach and a similar vision. 1463 The first goal would have been to integrate libp2p directly below core as 1464 an alternative/addition to the transport service as a first step of trying 1465 to get two different p2p networks and their implementations closer to each 1466 other. The long term goal would be to make the two networks compatible 1467 with each other and on the way learn from the respectively other network 1468 and apply the learnings to the respective on network. 1469 But it became soon clear that this was too ambitious for the short term 1470 and the short term goal was simplified to make libp2p a communicator for 1471 transport without loosing the perspective of integrating the two networks 1472 further in the future. 1473 Interesting insights include performance (in terms of throughput, memory 1474 consumption, cpu usage, ...), capabilities (NAT traversal, peer discovery, 1475 ...), different approaches to abstract similar underlying concepts, data 1476 structures employed and the usage of different schemes itself. 1477 If both networks would start to implement compatibilities to each other, 1478 both could profit from elements only the other has implemented. 1479 </t> 1480 <t> 1481 In order to address another peer and open a connecting, the libp2p 1482 multiaddress of the other peer or peer discovery is required. A libp2p 1483 multiaddress follows a very similar idea to a gnunet HELLO. Integrating 1484 the one with the other or finding a common abstraction would make a lot of 1485 sense in the mid to long term. For a libp2p communicator the easiest is to 1486 integrate a libp2p multiaddress just as one of the underlying 1487 transport/communicator addresses. 1488 The documentation of the libp2p multiaddress can be found here: 1489 https://docs.rs/libp2p/latest/libp2p/struct.Multiaddr.html 1490 </t> 1491 <t> 1492 One of the first consideration, when connecting the two networks, is the 1493 language. libp2p has implementations in many languages which all have 1494 different capabilities. (An overview is provided at 1495 https://libp2p.io/implementations.) 1496 In order to decide on the implementation mainly two factors have to be 1497 considered: Which features are needed and how difficult is the technical 1498 connection of the implementation? Depending on the implementation 1499 different wrappers and converters have to be implemented before being able 1500 to use them. 1501 </t> 1502 <t> 1503 Gnunet HELLO and libp2p multiaddress: The basic element to connect two 1504 gnunet peers via their libp2p communicators would be to exchange their 1505 libp2p multiaddress as part of a gnunet HELLO. Both represent a collection 1506 of different, underlying protocols, the respective implementations 1507 communicate over. Due to the similarity in representation, an adaption is 1508 needed to either (a) properly embed the one in the other without parsing 1509 issues, or (b) being able to directly parse both. 1510 <!-- seems not to be parsed and displayed on the web representation: 1511 For a better understanding, here is an exemplary libp2p multiaddress: 1512 <artwork anchor="libp2p multiaddress" name="" type="" align="left" alt=""><![CDATA[ 1513 /ip4/198.51.100/tcp/1234/p2p/QmYyQSo1c1Ym7orWxLYvCrM2EmxFTANf8wXmmE7DWjhx5N 1514 ]]></artwork> 1515 ... and an exemplary printable (shortened and obfuscated) representaiton 1516 of a gnunet HELLO: 1517 <artwork anchor="gnunet HELLO" name="" type="" align="left" alt=""><![CDATA[ 1518 gnunet://hello/HFXP<...>Y0/WDV0<...>WE20/1754<...>40?udp=%5Bfe80%3A%3Ad284%3A<...>3A2086&udp=%5B2003%3Acb%3A<...>%5D%3A2086<...>&tcp=%5Bfe80%3A%3A<...>%5D%3A2086&tcp=192.168.2.135%3A2086 1519 ]]></artwork> 1520 --> 1521 For the specification of libp2p multiaddresses see https://github.com/libp2p/specs/tree/master/addressing 1522 For just connecting two gnunet nodes via libp2p communicators, the main 1523 adaption needed is the compatibility between addressing schemes, as gnunet 1524 internally processes (signs with its peer id) the underlying addresses in 1525 order to exchange them via its bootstap system. 1526 </t> 1527 <t> 1528 Peer IDs: While gnunet only uses a single cryptographic primitive (EdDSA 1529 curve Ed25519) keys, libp2p has the option of using different keys. While 1530 not necessary if the connection is only as a communicator below transport, 1531 there might be the possibility of a direct compatibility at this level. 1532 (Probably a conversion in encoding/representation has still to be done.) 1533 The difference being that libp2p peer ids are stable, gnunet peer ids can 1534 change. 1535 For more see the libp2p spec on peer-ids: 1536 https://github.com/libp2p/specs/blob/master/peer-ids/peer-ids.md 1537 </t> 1538 <t> 1539 DHT: The Distributed Hash Tables of both networks are a bit different and 1540 as such not directly compatible. libp2p implements Kademlia 1541 (https://github.com/libp2p/specs/tree/master/kad-dht), whereas 1542 gnunet implements R5N 1543 (https://docs.gnunet.org/latest/users/subsystems.html#dht-distributed-hash-table). 1544 </t> 1545 </section> 1546 <section anchor="security" numbered="true" toc="default"> 1547 <name>Security and Privacy Considerations</name> 1548 <section anchor="security_kem" numbered="true" toc="default"> 1549 <name>Ed25519 KEM</name> 1550 <t> 1551 Communicators use a modified version of the standard X25519 key exchange described in 1552 section 6.1 of <xref target="RFC7748"/>. 1553 It deviates in that we use the Ed25519 key pair "x","X = x*G" of the peer identity as X25519 scalars 1554 and curve points, respectively. 1555 The safety of this use of a KEM has been investigated by <xref target="T21"/>. 1556 </t> 1557 </section> 1558 </section> 1559 <section anchor="work_in_progress" numbered="true" toc="default"> 1560 <name>Work in Progress</name> 1561 <t> 1562 TRANSPORT API: GNUNET_TRANSPORT_MessageCompletedCallback, GNUNET_TRANSPORT_communicator_receive, and 1563 GNUNET_TRANSPORT_MessageCompletedCallback should follow a generic API for all communicator types. 1564 </t> 1565 <t> 1566 UDP Communicator: RTT (Round-Trip Time) measurement is missing. Values such as the number of shared secrets could be adapted based on the RTT. 1567 </t> 1568 <t> 1569 TCP Communicator: Currently, the only sanity check for a valid TCP handshake message is the verification of the signature. Additional checks, such as 1570 verifying the sender's peer identity, are needed. 1571 The use of the mac-then-encrypt approach within the TCP BOX messages should be analyzed further, specifically regarding padding-oracle attacks. 1572 </t> 1573 </section> 1574 <!-- <section anchor="gana" numbered="true" toc="default"> 1575 <name>GANA Considerations</name> 1576 </section>--> 1577 <!-- gana --> 1578 <!--<section> 1579 <name>IANA Considerations</name> 1580 </section>--> 1581 <!-- <section> 1582 <name>Implementation and Deployment Status</name> 1583 <t> 1584 FIXME 1585 </t> 1586 </section> 1587 <section> 1588 <name>Acknowledgements</name> 1589 <t> 1590 FIXME 1591 </t> 1592 </section>--> 1593 </middle> 1594 <back> 1595 <references> 1596 <name>Normative References</name> 1597 &RFC2119; 1598 &RFC5869; 1599 &RFC6234; 1600 &RFC7748; 1601 &RFC8032; 1602 &RFC8174; 1603 &RFC9114; 1604 &RFC9180; 1605 1606 </references> 1607 <references> 1608 <name>Informative References</name> 1609 <reference anchor="T21" target="https://eprint.iacr.org/2021/509.pdf"> 1610 <front> 1611 <title>On using the same key pair for Ed25519 and an X25519 based KEM</title> 1612 <author initials="E." surname="Thormaker" 1613 fullname="Erik Thormarker"> 1614 </author> 1615 <date month="April" year="2021" /> 1616 </front> 1617 </reference> 1618 <reference anchor="LSD0011" target="https://lsd.gnunet.org/lsd0011"> 1619 <front> 1620 <title>The GNUnet communicators</title> 1621 <author initials="M" surname="Schanzenbach" 1622 fullname="Martin Schanzenbach"> 1623 </author> 1624 <author initials="P." surname="Fardzadeh" 1625 fullname="Pedram Fardzadeh"> 1626 </author> 1627 <date month="July" year="2024" /> 1628 </front> 1629 </reference> 1630 <reference anchor="GANA" target="https://gana.gnunet.org"> 1631 <front> 1632 <title>The GNUnet communicators</title> 1633 <author fullname="GNUnet e.V."> 1634 </author> 1635 <date month="July" year="2024" /> 1636 </front> 1637 </reference> </references> 1638 1639 1640 </back> 1641 </rfc>