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
   6      it under the terms of the GNU General Public License as published
   7      by the Free Software Foundation; either version 3, or (at your
   8      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      General Public License for more details.
  14
  15      You should have received a copy of the GNU General Public License
  16      along with GNUnet; see the file COPYING.  If not, write to the
  17      Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  18      Boston, MA 02110-1301, USA.
  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 /**
 124  * Message for notifying a disconnection in a path
 125  */
 126 struct GNUNET_CADET_ConnectionBrokenMessage
 127 {
 128   /**
 129    * Type: #GNUNET_MESSAGE_TYPE_CADET_CONNECTION_BROKEN.
 130    */
 131   struct GNUNET_MessageHeader header;
 132
 133   /**
 134    * For alignment.
 135    */
 136   uint32_t reserved GNUNET_PACKED;
 137
 138   /**
 139    * ID of the connection.
 140    */
 141   struct GNUNET_CADET_ConnectionTunnelIdentifier cid;
 142
 143   /**
 144    * ID of the endpoint
 145    */
 146   struct GNUNET_PeerIdentity peer1;
 147
 148   /**
 149    * ID of the endpoint
 150    */
 151   struct GNUNET_PeerIdentity peer2;
 152 };
 153
 154
 155 /**
 156  * Message to destroy a connection.
 157  */
 158 struct GNUNET_CADET_ConnectionDestroyMessage
 159 {
 160   /**
 161    * Type: #GNUNET_MESSAGE_TYPE_CADET_CONNECTION_DESTROY
 162    */
 163   struct GNUNET_MessageHeader header;
 164
 165   /**
 166    * For alignment.
 167    */
 168   uint32_t reserved GNUNET_PACKED;
 169
 170   /**
 171    * ID of the connection.
 172    */
 173   struct GNUNET_CADET_ConnectionTunnelIdentifier cid;
 174 };
 175
 176
 177 /******************************************************************************/
 178 /*******************************   TUNNEL   ***********************************/
 179 /******************************************************************************/
 180
 181 /**
 182  * Unique identifier (counter) for an encrypted message in a channel.
 183  * Used to match #GNUNET_MESSAGE_TYPE_CADET_CONNECTION_HOP_BY_HOP_ENCRYPTED_ACK
 184  * and  #GNUNET_MESSAGE_TYPE_CADET_TUNNEL_ENCRYPTED_POLL messages
 185  * against the respective  #GNUNET_MESSAGE_TYPE_CADET_TUNNEL_ENCRYPTED
 186  * messages.
 187  */
 188 struct CadetEncryptedMessageIdentifier
 189 {
 190   /**
 191    * This number is incremented by one per message. It may wrap around.
 192    * In network byte order.
 193    */
 194   uint32_t pid GNUNET_PACKED;
 195 };
 196
 197
 198 /**
 199  * Flags to be used in GNUNET_CADET_KX.
 200  */
 201 enum GNUNET_CADET_KX_Flags {
 202
 203   /**
 204    * Should the peer reply with its KX details?
 205    */
 206   GNUNET_CADET_KX_FLAG_NONE = 0,
 207
 208   /**
 209    * The peer should reply with its KX details?
 210    */
 211   GNUNET_CADET_KX_FLAG_FORCE_REPLY = 1
 212 };
 213
 214
 215 /**
 216  * Message for a Key eXchange for a tunnel.
 217  */
 218 struct GNUNET_CADET_TunnelKeyExchangeMessage
 219 {
 220   /**
 221    * Type: #GNUNET_MESSAGE_TYPE_CADET_TUNNEL_KX or
 222    * #GNUNET_MESSAGE_TYPE_CADET_TUNNEL_KX_AUTH as part
 223    * of `struct GNUNET_CADET_TunnelKeyExchangeAuthMessage`.
 224    */
 225   struct GNUNET_MessageHeader header;
 226
 227   /**
 228    * Flags for the key exchange in NBO, based on
 229    * `enum GNUNET_CADET_KX_Flags`.
 230    */
 231   uint32_t flags GNUNET_PACKED;
 232
 233   /**
 234    * ID of the connection.
 235    */
 236   struct GNUNET_CADET_ConnectionTunnelIdentifier cid;
 237
 238   /**
 239    * Sender's ephemeral public ECC key encoded in a
 240    * format suitable for network transmission, as created
 241    * using 'gcry_sexp_sprint'.
 242    */
 243   struct GNUNET_CRYPTO_EcdhePublicKey ephemeral_key;
 244
 245 #if DEBUG_KX
 246   /**
 247    * Sender's ephemeral public ECC key encoded in a
 248    * format suitable for network transmission, as created
 249    * using 'gcry_sexp_sprint'.
 250    */
 251   struct GNUNET_CRYPTO_EcdhePrivateKey ephemeral_key_XXX; // for debugging KX-crypto!
 252
 253   /**
 254    * Sender's ephemeral public ECC key encoded in a
 255    * format suitable for network transmission, as created
 256    * using 'gcry_sexp_sprint'.
 257    */
 258   struct GNUNET_CRYPTO_EddsaPrivateKey private_key_XXX; // for debugging KX-crypto!
 259 #endif
 260
 261   /**
 262    * Sender's next ephemeral public ECC key encoded in a
 263    * format suitable for network transmission, as created
 264    * using 'gcry_sexp_sprint'.
 265    */
 266   struct GNUNET_CRYPTO_EcdhePublicKey ratchet_key;
 267
 268 };
 269
 270
 271 /**
 272  * Message for a Key eXchange for a tunnel, with authentication.
 273  * Used as a response to the initial KX as well as for rekeying.
 274  */
 275 struct GNUNET_CADET_TunnelKeyExchangeAuthMessage
 276 {
 277
 278   /**
 279    * Message header with key material.
 280    */
 281   struct GNUNET_CADET_TunnelKeyExchangeMessage kx;
 282
 283 #if DEBUG_KX
 284   /**
 285    * Received ephemeral public ECC key encoded in a
 286    * format suitable for network transmission, as created
 287    * using 'gcry_sexp_sprint'.
 288    */
 289   struct GNUNET_CRYPTO_EcdhePublicKey r_ephemeral_key_XXX; // for debugging KX-crypto!
 290 #endif
 291
 292   /**
 293    * KDF-proof that sender could compute the 3-DH, used in lieu of a
 294    * signature or payload data.
 295    */
 296   struct GNUNET_HashCode auth;
 297
 298 };
 299
 300
 301 /**
 302  * Encrypted axolotl header with numbers that identify which
 303  * keys in which ratchet are to be used to decrypt the body.
 304  */
 305 struct GNUNET_CADET_AxHeader
 306 {
 307
 308   /**
 309    * Number of messages sent with the current ratchet key.
 310    */
 311   uint32_t Ns GNUNET_PACKED;
 312
 313   /**
 314    * Number of messages sent with the previous ratchet key.
 315    */
 316   uint32_t PNs GNUNET_PACKED;
 317
 318   /**
 319    * Current ratchet key.
 320    */
 321   struct GNUNET_CRYPTO_EcdhePublicKey DHRs;
 322
 323 };
 324
 325
 326 /**
 327  * Axolotl-encrypted tunnel message with application payload.
 328  */
 329 struct GNUNET_CADET_TunnelEncryptedMessage
 330 {
 331   /**
 332    * Type: #GNUNET_MESSAGE_TYPE_CADET_TUNNEL_ENCRYPTED
 333    */
 334   struct GNUNET_MessageHeader header;
 335
 336   /**
 337    * Reserved, for alignment.
 338    */
 339   uint32_t reserved GNUNET_PACKED;
 340
 341   /**
 342    * ID of the connection.
 343    */
 344   struct GNUNET_CADET_ConnectionTunnelIdentifier cid;
 345
 346   /**
 347    * MAC of the encrypted message, used to verify message integrity.
 348    * Everything after this value  will be encrypted with the header key
 349    * and authenticated.
 350    */
 351   struct GNUNET_ShortHashCode hmac;
 352
 353   /**
 354    * Axolotl-header that specifies which keys to use in which ratchet
 355    * to decrypt the body that follows.
 356    */
 357   struct GNUNET_CADET_AxHeader ax_header;
 358
 359   /**
 360    * Encrypted content follows.
 361    */
 362 };
 363
 364
 365 /******************************************************************************/
 366 /*******************************   CHANNEL  ***********************************/
 367 /******************************************************************************/
 368
 369
 370 /**
 371  * Message to create a Channel.
 372  */
 373 struct GNUNET_CADET_ChannelOpenMessage
 374 {
 375   /**
 376    * Type: #GNUNET_MESSAGE_TYPE_CADET_CHANNEL_OPEN
 377    */
 378   struct GNUNET_MessageHeader header;
 379
 380   /**
 381    * Channel options.
 382    */
 383   uint32_t opt GNUNET_PACKED;
 384
 385   /**
 386    * Hash of destination port and listener.
 387    */
 388   struct GNUNET_HashCode h_port;
 389
 390   /**
 391    * ID of the channel within the tunnel.
 392    */
 393   struct GNUNET_CADET_ChannelTunnelNumber ctn;
 394 };
 395
 396
 397 /**
 398  * Message to acknowledge opening a channel of type
 399  * #GNUNET_MESSAGE_TYPE_CADET_CHANNEL_OPEN_ACK.
 400  */
 401 struct GNUNET_CADET_ChannelOpenAckMessage
 402 {
 403   /**
 404    * Type: #GNUNET_MESSAGE_TYPE_CADET_CHANNEL_OPEN_ACK
 405    */
 406   struct GNUNET_MessageHeader header;
 407
 408   /**
 409    * For alignment.
 410    */
 411   uint32_t reserved GNUNET_PACKED;
 412
 413   /**
 414    * ID of the channel
 415    */
 416   struct GNUNET_CADET_ChannelTunnelNumber ctn;
 417
 418   /**
 419    * Port number of the channel, used to prove to the
 420    * initiator that the receiver knows the port.
 421    */
 422   struct GNUNET_HashCode port;
 423 };
 424
 425
 426 /**
 427  * Message to destroy a channel of type
 428  * #GNUNET_MESSAGE_TYPE_CADET_CHANNEL_DESTROY.
 429  */
 430 struct GNUNET_CADET_ChannelDestroyMessage
 431 {
 432   /**
 433    * Type: #GNUNET_MESSAGE_TYPE_CADET_CHANNEL_DESTROY
 434    */
 435   struct GNUNET_MessageHeader header;
 436
 437   /**
 438    * For alignment.
 439    */
 440   uint32_t reserved GNUNET_PACKED;
 441
 442   /**
 443    * ID of the channel
 444    */
 445   struct GNUNET_CADET_ChannelTunnelNumber ctn;
 446 };
 447
 448
 449 /**
 450  * Number used to uniquely identify messages in a CADET Channel.
 451  */
 452 struct ChannelMessageIdentifier
 453 {
 454   /**
 455    * Unique ID of the message, cycles around, in NBO.
 456    */
 457   uint32_t mid GNUNET_PACKED;
 458 };
 459
 460
 461 /**
 462  * Message for cadet data traffic.
 463  */
 464 struct GNUNET_CADET_ChannelAppDataMessage
 465 {
 466   /**
 467    * Type: #GNUNET_MESSAGE_TYPE_CADET_CHANNEL_APP_DATA.
 468    */
 469   struct GNUNET_MessageHeader header;
 470
 471   /**
 472    * Unique ID of the payload message.
 473    */
 474   struct ChannelMessageIdentifier mid;
 475
 476   /**
 477    * ID of the channel
 478    */
 479   struct GNUNET_CADET_ChannelTunnelNumber ctn;
 480
 481   /**
 482    * Payload follows
 483    */
 484 };
 485
 486
 487 /**
 488  * Message to acknowledge end-to-end data.
 489  */
 490 struct GNUNET_CADET_ChannelDataAckMessage
 491 {
 492   /**
 493    * Type: #GNUNET_MESSAGE_TYPE_CADET_CHANNEL_APP_DATA_ACK
 494    */
 495   struct GNUNET_MessageHeader header;
 496
 497   /**
 498    * ID of the channel
 499    */
 500   struct GNUNET_CADET_ChannelTunnelNumber ctn;
 501
 502   /**
 503    * Bitfield of already-received newer messages.  Note that bit 0
 504    * corresponds to @e mid + 1.
 505    *
 506    * pid +  0 @ LSB
 507    * pid + 63 @ MSB
 508    */
 509   uint64_t futures GNUNET_PACKED;
 510
 511   /**
 512    * Next message ID expected.
 513    */
 514   struct ChannelMessageIdentifier mid;
 515 };
 516
 517
 518 GNUNET_NETWORK_STRUCT_END
 519
 520 #if 0                           /* keep Emacsens' auto-indent happy */
 521 {
 522 #endif
 523 #ifdef __cplusplus
 524 }
 525 #endif
 526
 527 /* ifndef CADET_PROTOCOL_H */
 528 #endif
 529 /* end of cadet_protocol.h */