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