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