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