src/cadet/cadet_protocol.h

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