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