src/cadet/cadet_protocol.h

   1 /*
   2      This file is part of GNUnet.
   3      Copyright (C) 2007 - 2017 GNUnet e.V.
   4
   5      GNUnet is free software: you can redistribute it and/or modify it
   6      under the terms of the GNU Affero General Public License as published
   7      by the Free Software Foundation, either version 3 of the License,
   8      or (at your option) any later version.
   9
  10      GNUnet is distributed in the hope that it will be useful, but
  11      WITHOUT ANY WARRANTY; without even the implied warranty of
  12      MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13      Affero General Public License for more details.
  14
  15      You should have received a copy of the GNU Affero General Public License
  16      along with this program.  If not, see <http://www.gnu.org/licenses/>.
  17
  18      SPDX-License-Identifier: AGPL3.0-or-later
  19  */
  20
  21 /**
  22  * @file cadet/cadet_protocol.h
  23  * @brief P2P messages used by CADET
  24  * @author Bartlomiej Polot
  25  * @author Christian Grothoff
  26  */
  27
  28 #ifndef CADET_PROTOCOL_H_
  29 #define CADET_PROTOCOL_H_
  30
  31 /**
  32  * At best, enable when debugging #5328!
  33  */
  34 #define DEBUG_KX 0
  35 #if DEBUG_KX
  36 #warning NEVER run this in production! KX debugging is on!
  37 #endif
  38
  39 #include "platform.h"
  40 #include "gnunet_util_lib.h"
  41 #include "cadet.h"
  42
  43 #ifdef __cplusplus
  44
  45 struct GNUNET_CADET_TunnelMessage;
  46 extern "C"
  47 {
  48 #if 0
  49 /* keep Emacsens' auto-indent happy */
  50 }
  51 #endif
  52 #endif
  53
  54 /******************************************************************************/
  55 /********************      CADET NETWORK MESSAGES     **************************/
  56 /******************************************************************************/
  57
  58 GNUNET_NETWORK_STRUCT_BEGIN
  59
  60
  61 /******************************************************************************/
  62 /*****************************   CONNECTION  **********************************/
  63 /******************************************************************************/
  64
  65
  66 /**
  67  * Message for cadet connection creation.
  68  */
  69 struct GNUNET_CADET_ConnectionCreateMessage
  70 {
  71   /**
  72    * Type: #GNUNET_MESSAGE_TYPE_CADET_CONNECTION_CREATE
  73    *
  74    * Size: sizeof (struct GNUNET_CADET_ConnectionCreateMessage) +
  75    *       path_length * sizeof (struct GNUNET_PeerIdentity)
  76    */
  77   struct GNUNET_MessageHeader header;
  78
  79   /**
  80    * Connection options in network byte order.
  81    * #GNUNET_CADET_OPTION_DEFAULT for buffered;
  82    * #GNUNET_CADET_OPTION_NOBUFFER for unbuffered.
  83    * Other flags are ignored and should not be set at this level.
  84    */
  85   uint32_t options GNUNET_PACKED;
  86
  87   /**
  88    * ID of the connection
  89    */
  90   struct GNUNET_CADET_ConnectionTunnelIdentifier cid;
  91
  92   /**
  93    * path_length structs defining the *whole* path from the origin [0] to the
  94    * final destination [path_length-1].
  95    */
  96   /* struct GNUNET_PeerIdentity peers[path_length]; */
  97 };
  98
  99
 100 /**
 101  * Message for ack'ing a connection
 102  */
 103 struct GNUNET_CADET_ConnectionCreateAckMessage
 104 {
 105   /**
 106    * Type: #GNUNET_MESSAGE_TYPE_CADET_CONNECTION_CREATE_ACK
 107    */
 108   struct GNUNET_MessageHeader header;
 109
 110   /**
 111    * For alignment.
 112    */
 113   uint32_t reserved GNUNET_PACKED;
 114
 115   /**
 116    * ID of the connection.
 117    */
 118   struct GNUNET_CADET_ConnectionTunnelIdentifier cid;
 119 };
 120
 121
 122 /**
 123  * Message for notifying a disconnection in a path
 124  */
 125 struct GNUNET_CADET_ConnectionBrokenMessage
 126 {
 127   /**
 128    * Type: #GNUNET_MESSAGE_TYPE_CADET_CONNECTION_BROKEN.
 129    */
 130   struct GNUNET_MessageHeader header;
 131
 132   /**
 133    * For alignment.
 134    */
 135   uint32_t reserved GNUNET_PACKED;
 136
 137   /**
 138    * ID of the connection.
 139    */
 140   struct GNUNET_CADET_ConnectionTunnelIdentifier cid;
 141
 142   /**
 143    * ID of the endpoint
 144    */
 145   struct GNUNET_PeerIdentity peer1;
 146
 147   /**
 148    * ID of the endpoint
 149    */
 150   struct GNUNET_PeerIdentity peer2;
 151 };
 152
 153
 154 /**
 155  * Message to destroy a connection.
 156  */
 157 struct GNUNET_CADET_ConnectionDestroyMessage
 158 {
 159   /**
 160    * Type: #GNUNET_MESSAGE_TYPE_CADET_CONNECTION_DESTROY
 161    */
 162   struct GNUNET_MessageHeader header;
 163
 164   /**
 165    * For alignment.
 166    */
 167   uint32_t reserved GNUNET_PACKED;
 168
 169   /**
 170    * ID of the connection.
 171    */
 172   struct GNUNET_CADET_ConnectionTunnelIdentifier cid;
 173 };
 174
 175
 176 /******************************************************************************/
 177 /*******************************   TUNNEL   ***********************************/
 178 /******************************************************************************/
 179
 180 /**
 181  * Unique identifier (counter) for an encrypted message in a channel.
 182  * Used to match #GNUNET_MESSAGE_TYPE_CADET_CONNECTION_HOP_BY_HOP_ENCRYPTED_ACK
 183  * and  #GNUNET_MESSAGE_TYPE_CADET_TUNNEL_ENCRYPTED_POLL messages
 184  * against the respective  #GNUNET_MESSAGE_TYPE_CADET_TUNNEL_ENCRYPTED
 185  * messages.
 186  */
 187 struct CadetEncryptedMessageIdentifier
 188 {
 189   /**
 190    * This number is incremented by one per message. It may wrap around.
 191    * In network byte order.
 192    */
 193   uint32_t pid GNUNET_PACKED;
 194 };
 195
 196
 197 /**
 198  * Flags to be used in GNUNET_CADET_KX.
 199  */
 200 enum GNUNET_CADET_KX_Flags
 201 {
 202   /**
 203    * Should the peer reply with its KX details?
 204    */
 205   GNUNET_CADET_KX_FLAG_NONE = 0,
 206
 207   /**
 208    * The peer should reply with its KX details?
 209    */
 210   GNUNET_CADET_KX_FLAG_FORCE_REPLY = 1
 211 };
 212
 213
 214 /**
 215  * Message for a Key eXchange for a tunnel.
 216  */
 217 struct GNUNET_CADET_TunnelKeyExchangeMessage
 218 {
 219   /**
 220    * Type: #GNUNET_MESSAGE_TYPE_CADET_TUNNEL_KX or
 221    * #GNUNET_MESSAGE_TYPE_CADET_TUNNEL_KX_AUTH as part
 222    * of `struct GNUNET_CADET_TunnelKeyExchangeAuthMessage`.
 223    */
 224   struct GNUNET_MessageHeader header;
 225
 226   /**
 227    * Flags for the key exchange in NBO, based on
 228    * `enum GNUNET_CADET_KX_Flags`.
 229    */
 230   uint32_t flags GNUNET_PACKED;
 231
 232   /**
 233    * ID of the connection.
 234    */
 235   struct GNUNET_CADET_ConnectionTunnelIdentifier cid;
 236
 237   /**
 238    * Sender's ephemeral public ECC key encoded in a
 239    * format suitable for network transmission, as created
 240    * using 'gcry_sexp_sprint'.
 241    */
 242   struct GNUNET_CRYPTO_EcdhePublicKey ephemeral_key;
 243
 244 #if DEBUG_KX
 245   /**
 246    * Sender's ephemeral public ECC key encoded in a
 247    * format suitable for network transmission, as created
 248    * using 'gcry_sexp_sprint'.
 249    */
 250   struct GNUNET_CRYPTO_EcdhePrivateKey ephemeral_key_XXX; // for debugging KX-crypto!
 251
 252   /**
 253    * Sender's ephemeral public ECC key encoded in a
 254    * format suitable for network transmission, as created
 255    * using 'gcry_sexp_sprint'.
 256    */
 257   struct GNUNET_CRYPTO_EddsaPrivateKey private_key_XXX; // for debugging KX-crypto!
 258 #endif
 259
 260   /**
 261    * Sender's next ephemeral public ECC key encoded in a
 262    * format suitable for network transmission, as created
 263    * using 'gcry_sexp_sprint'.
 264    */
 265   struct GNUNET_CRYPTO_EcdhePublicKey ratchet_key;
 266 };
 267
 268
 269 /**
 270  * Message for a Key eXchange for a tunnel, with authentication.
 271  * Used as a response to the initial KX as well as for rekeying.
 272  */
 273 struct GNUNET_CADET_TunnelKeyExchangeAuthMessage
 274 {
 275   /**
 276    * Message header with key material.
 277    */
 278   struct GNUNET_CADET_TunnelKeyExchangeMessage kx;
 279
 280 #if DEBUG_KX
 281   /**
 282    * Received ephemeral public ECC key encoded in a
 283    * format suitable for network transmission, as created
 284    * using 'gcry_sexp_sprint'.
 285    */
 286   struct GNUNET_CRYPTO_EcdhePublicKey r_ephemeral_key_XXX; // for debugging KX-crypto!
 287 #endif
 288
 289   /**
 290    * KDF-proof that sender could compute the 3-DH, used in lieu of a
 291    * signature or payload data.
 292    */
 293   struct GNUNET_HashCode auth;
 294 };
 295
 296
 297 /**
 298  * Encrypted axolotl header with numbers that identify which
 299  * keys in which ratchet are to be used to decrypt the body.
 300  */
 301 struct GNUNET_CADET_AxHeader
 302 {
 303   /**
 304    * Number of messages sent with the current ratchet key.
 305    */
 306   uint32_t Ns GNUNET_PACKED;
 307
 308   /**
 309    * Number of messages sent with the previous ratchet key.
 310    */
 311   uint32_t PNs GNUNET_PACKED;
 312
 313   /**
 314    * Current ratchet key.
 315    */
 316   struct GNUNET_CRYPTO_EcdhePublicKey DHRs;
 317 };
 318
 319
 320 /**
 321  * Axolotl-encrypted tunnel message with application payload.
 322  */
 323 struct GNUNET_CADET_TunnelEncryptedMessage
 324 {
 325   /**
 326    * Type: #GNUNET_MESSAGE_TYPE_CADET_TUNNEL_ENCRYPTED
 327    */
 328   struct GNUNET_MessageHeader header;
 329
 330   /**
 331    * Reserved, for alignment.
 332    */
 333   uint32_t reserved GNUNET_PACKED;
 334
 335   /**
 336    * ID of the connection.
 337    */
 338   struct GNUNET_CADET_ConnectionTunnelIdentifier cid;
 339
 340   /**
 341    * MAC of the encrypted message, used to verify message integrity.
 342    * Everything after this value  will be encrypted with the header key
 343    * and authenticated.
 344    */
 345   struct GNUNET_ShortHashCode hmac;
 346
 347   /**
 348    * Axolotl-header that specifies which keys to use in which ratchet
 349    * to decrypt the body that follows.
 350    */
 351   struct GNUNET_CADET_AxHeader ax_header;
 352
 353   /**
 354    * Encrypted content follows.
 355    */
 356 };
 357
 358
 359 /******************************************************************************/
 360 /*******************************   CHANNEL  ***********************************/
 361 /******************************************************************************/
 362
 363
 364 /**
 365  * Message to create a Channel.
 366  */
 367 struct GNUNET_CADET_ChannelOpenMessage
 368 {
 369   /**
 370    * Type: #GNUNET_MESSAGE_TYPE_CADET_CHANNEL_OPEN
 371    */
 372   struct GNUNET_MessageHeader header;
 373
 374   /**
 375    * Channel options.
 376    */
 377   uint32_t opt GNUNET_PACKED;
 378
 379   /**
 380    * Hash of destination port and listener.
 381    */
 382   struct GNUNET_HashCode h_port;
 383
 384   /**
 385    * ID of the channel within the tunnel.
 386    */
 387   struct GNUNET_CADET_ChannelTunnelNumber ctn;
 388 };
 389
 390
 391 /**
 392  * Message to acknowledge opening a channel of type
 393  * #GNUNET_MESSAGE_TYPE_CADET_CHANNEL_OPEN_ACK.
 394  */
 395 struct GNUNET_CADET_ChannelOpenAckMessage
 396 {
 397   /**
 398    * Type: #GNUNET_MESSAGE_TYPE_CADET_CHANNEL_OPEN_ACK
 399    */
 400   struct GNUNET_MessageHeader header;
 401
 402   /**
 403    * For alignment.
 404    */
 405   uint32_t reserved GNUNET_PACKED;
 406
 407   /**
 408    * ID of the channel
 409    */
 410   struct GNUNET_CADET_ChannelTunnelNumber ctn;
 411
 412   /**
 413    * Port number of the channel, used to prove to the
 414    * initiator that the receiver knows the port.
 415    */
 416   struct GNUNET_HashCode port;
 417 };
 418
 419
 420 /**
 421  * Message to destroy a channel of type
 422  * #GNUNET_MESSAGE_TYPE_CADET_CHANNEL_DESTROY.
 423  */
 424 struct GNUNET_CADET_ChannelDestroyMessage
 425 {
 426   /**
 427    * Type: #GNUNET_MESSAGE_TYPE_CADET_CHANNEL_DESTROY
 428    */
 429   struct GNUNET_MessageHeader header;
 430
 431   /**
 432    * For alignment.
 433    */
 434   uint32_t reserved GNUNET_PACKED;
 435
 436   /**
 437    * ID of the channel
 438    */
 439   struct GNUNET_CADET_ChannelTunnelNumber ctn;
 440 };
 441
 442
 443 /**
 444  * Number used to uniquely identify messages in a CADET Channel.
 445  */
 446 struct ChannelMessageIdentifier
 447 {
 448   /**
 449    * Unique ID of the message, cycles around, in NBO.
 450    */
 451   uint32_t mid GNUNET_PACKED;
 452 };
 453
 454
 455 /**
 456  * Message for cadet data traffic.
 457  */
 458 struct GNUNET_CADET_ChannelAppDataMessage
 459 {
 460   /**
 461    * Type: #GNUNET_MESSAGE_TYPE_CADET_CHANNEL_APP_DATA.
 462    */
 463   struct GNUNET_MessageHeader header;
 464
 465   /**
 466    * Unique ID of the payload message.
 467    */
 468   struct ChannelMessageIdentifier mid;
 469
 470   /**
 471    * ID of the channel
 472    */
 473   struct GNUNET_CADET_ChannelTunnelNumber ctn;
 474
 475   /**
 476    * Payload follows
 477    */
 478 };
 479
 480
 481 /**
 482  * Message to acknowledge end-to-end data.
 483  */
 484 struct GNUNET_CADET_ChannelDataAckMessage
 485 {
 486   /**
 487    * Type: #GNUNET_MESSAGE_TYPE_CADET_CHANNEL_APP_DATA_ACK
 488    */
 489   struct GNUNET_MessageHeader header;
 490
 491   /**
 492    * ID of the channel
 493    */
 494   struct GNUNET_CADET_ChannelTunnelNumber ctn;
 495
 496   /**
 497    * Bitfield of already-received newer messages.  Note that bit 0
 498    * corresponds to @e mid + 1.
 499    *
 500    * pid +  0 @ LSB
 501    * pid + 63 @ MSB
 502    */
 503   uint64_t futures GNUNET_PACKED;
 504
 505   /**
 506    * Next message ID expected.
 507    */
 508   struct ChannelMessageIdentifier mid;
 509 };
 510
 511
 512 GNUNET_NETWORK_STRUCT_END
 513
 514 #if 0                           /* keep Emacsens' auto-indent happy */
 515 {
 516 #endif
 517 #ifdef __cplusplus
 518 }
 519 #endif
 520
 521 /* ifndef CADET_PROTOCOL_H */
 522 #endif
 523 /* end of cadet_protocol.h */