src/cadet/cadet.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 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      SPDX-License-Identifier: AGPL3.0-or-later
  19  */
  20
  21 /**
  22  * @author Bartlomiej Polot
  23  * @file cadet/cadet.h
  24  */
  25
  26 #ifndef CADET_H_
  27 #define CADET_H_
  28
  29 #ifdef __cplusplus
  30 extern "C" {
  31 #if 0 /* keep Emacsens' auto-indent happy */
  32 }
  33 #endif
  34 #endif
  35
  36 #include <stdint.h>
  37
  38 #if !defined(GNUNET_CULL_LOGGING)
  39 #define CADET_TIMING_START                 \
  40   struct GNUNET_TIME_Absolute __timestamp; \
  41   __timestamp = GNUNET_TIME_absolute_get()
  42
  43 #define CADET_TIMING_END                                        \
  44   struct GNUNET_TIME_Relative __duration;                       \
  45   __duration = GNUNET_TIME_absolute_get_duration(__timestamp); \
  46   LOG(GNUNET_ERROR_TYPE_INFO,                                  \
  47       " %s duration %s\n",                                     \
  48       __FUNCTION__,                                            \
  49       GNUNET_STRINGS_relative_time_to_string(__duration, GNUNET_YES));
  50 #else
  51 #define CADET_TIMING_START
  52 #define CADET_TIMING_END
  53 #endif
  54
  55
  56 #include "platform.h"
  57 #include "gnunet_util_lib.h"
  58 #include "gnunet_peer_lib.h"
  59 #include "gnunet_core_service.h"
  60 #include "gnunet_cadet_service.h"
  61 #include "gnunet_protocols.h"
  62 #include "gnunet_cadet_service.h"
  63
  64 /******************************************************************************/
  65 /**************************       CONSTANTS      ******************************/
  66 /******************************************************************************/
  67
  68 /**
  69  * Minimum value for channel IDs of local clients.
  70  */
  71 #define GNUNET_CADET_LOCAL_CHANNEL_ID_CLI 0x80000000U
  72
  73 /**
  74  * FIXME.
  75  */
  76 #define HIGH_PID 0xFF000000
  77
  78 /**
  79  * FIXME.
  80  */
  81 #define LOW_PID 0x00FFFFFF
  82
  83
  84 /**
  85  * Test if the two PIDs (of type `uint32_t`) are in the range where we
  86  * have to worry about overflows.  This is the case when @a pid is
  87  * large and @a max is small, useful when comparing @a pid smaller
  88  * than @a max.
  89  */
  90 #define PID_OVERFLOW(pid, max) (((pid) > HIGH_PID) && ((max) < LOW_PID))
  91
  92 /******************************************************************************/
  93 /**************************        MESSAGES      ******************************/
  94 /******************************************************************************/
  95
  96 GNUNET_NETWORK_STRUCT_BEGIN
  97
  98
  99 /**
 100  * Number uniquely identifying a channel of a client.
 101  */
 102 struct GNUNET_CADET_ClientChannelNumber {
 103   /**
 104    * Values for channel numbering.
 105    * Local channel numbers given by the service (incoming) are
 106    * smaller than #GNUNET_CADET_LOCAL_CHANNEL_ID_CLI.
 107    * Local channel numbers given by the client (created) are
 108    * larger than #GNUNET_CADET_LOCAL_CHANNEL_ID_CLI.
 109    */
 110   uint32_t channel_of_client GNUNET_PACKED;
 111 };
 112
 113
 114 /**
 115  * Message for a client to create and destroy channels.
 116  */
 117 struct GNUNET_CADET_PortMessage {
 118   /**
 119    * Type: #GNUNET_MESSAGE_TYPE_CADET_LOCAL_PORT_OPEN
 120    * or #GNUNET_MESSAGE_TYPE_CADET_LOCAL_PORT_CLOSE
 121    *
 122    * Size: sizeof(struct GNUNET_CADET_ChannelMessage)
 123    */
 124   struct GNUNET_MessageHeader header;
 125
 126   /**
 127    * Port to open/close.
 128    */
 129   struct GNUNET_HashCode port GNUNET_PACKED;
 130 };
 131
 132
 133 /**
 134  * Message for a client to create channels.
 135  */
 136 struct GNUNET_CADET_LocalChannelCreateMessage {
 137   /**
 138    * Type: #GNUNET_MESSAGE_TYPE_CADET_LOCAL_CHANNEL_CREATE
 139    *
 140    * Size: sizeof(struct GNUNET_CADET_ChannelOpenMessageMessage)
 141    */
 142   struct GNUNET_MessageHeader header;
 143
 144   /**
 145    * ID of a channel controlled by this client.
 146    */
 147   struct GNUNET_CADET_ClientChannelNumber ccn;
 148
 149   /**
 150    * Channel's peer
 151    */
 152   struct GNUNET_PeerIdentity peer;
 153
 154   /**
 155    * Port of the channel.
 156    */
 157   struct GNUNET_HashCode port;
 158
 159   /**
 160    * Options.
 161    */
 162   uint32_t opt GNUNET_PACKED;
 163 };
 164
 165
 166 /**
 167  * Message for or to a client to destroy tunnel.
 168  */
 169 struct GNUNET_CADET_LocalChannelDestroyMessage {
 170   /**
 171    * Type: #GNUNET_MESSAGE_TYPE_CADET_LOCAL_CHANNEL_DESTROY
 172    */
 173   struct GNUNET_MessageHeader header;
 174
 175   /**
 176    * ID of a channel controlled by this client.
 177    */
 178   struct GNUNET_CADET_ClientChannelNumber ccn;
 179 };
 180
 181
 182 /**
 183  * Message for cadet data traffic.
 184  */
 185 struct GNUNET_CADET_LocalData {
 186   /**
 187    * Type: #GNUNET_MESSAGE_TYPE_CADET_LOCAL_DATA
 188    */
 189   struct GNUNET_MessageHeader header;
 190
 191   /**
 192    * ID of the channel
 193    */
 194   struct GNUNET_CADET_ClientChannelNumber ccn;
 195
 196   /**
 197    * Priority and preferences (an enum GNUNET_MQ_PriorityPreferences)
 198    * of the message in NBO.
 199    */
 200   uint32_t pp GNUNET_PACKED;
 201
 202   /**
 203    * Payload follows
 204    */
 205 };
 206
 207
 208 /**
 209  * Message to allow the client send more data to the service
 210  * (always service -> client).
 211  */
 212 struct GNUNET_CADET_LocalAck {
 213   /**
 214    * Type: #GNUNET_MESSAGE_TYPE_CADET_LOCAL_ACK
 215    */
 216   struct GNUNET_MessageHeader header;
 217
 218   /**
 219    * ID of the channel allowed to send more data.
 220    */
 221   struct GNUNET_CADET_ClientChannelNumber ccn;
 222 };
 223
 224
 225 /**
 226  * Message to inform the client about channels in the service.
 227  *
 228  * TODO: split into two messages!
 229  */
 230 struct GNUNET_CADET_LocalInfo {
 231   /**
 232    * Type: #GNUNET_MESSAGE_TYPE_CADET_LOCAL_INFO_TUNNEL or
 233    * #GNUNET_MESSAGE_TYPE_CADET_LOCAL_INFO_PEER
 234    */
 235   struct GNUNET_MessageHeader header;
 236
 237   /**
 238    * ID of the channel allowed to send more data.
 239    */
 240   struct GNUNET_CADET_ClientChannelNumber ccn;
 241
 242   /**
 243    * ID of the destination of the channel (can be local peer).
 244    */
 245   struct GNUNET_PeerIdentity peer;
 246 };
 247
 248
 249 /**
 250  * Message to inform the client about channels in the service.
 251  */
 252 struct GNUNET_CADET_RequestPathInfoMessage {
 253   /**
 254    * Type: #GNUNET_MESSAGE_TYPE_CADET_LOCAL_REQUEST_INFO_PATH
 255    */
 256   struct GNUNET_MessageHeader header;
 257
 258   /**
 259    * Always zero.
 260    */
 261   uint32_t resered GNUNET_PACKED;
 262
 263   /**
 264    * ID of the destination of the channel (can be local peer).
 265    */
 266   struct GNUNET_PeerIdentity peer;
 267 };
 268
 269
 270 /**
 271  * Message to inform the client about channels in the service.
 272  */
 273 struct GNUNET_CADET_ChannelInfoMessage {
 274   /**
 275    * Type: #GNUNET_MESSAGE_TYPE_CADET_LOCAL_INFO_CHANNEL.
 276    */
 277   struct GNUNET_MessageHeader header;
 278
 279   /**
 280    * Root of the channel
 281    */
 282   struct GNUNET_PeerIdentity root;
 283
 284   /**
 285    * Destination of the channel
 286    */
 287   struct GNUNET_PeerIdentity dest;
 288
 289   /* FIXME: expand! */
 290 };
 291
 292
 293 /**
 294  * Message to as the service about information on a channel.
 295  */
 296 struct GNUNET_CADET_RequestChannelInfoMessage {
 297   /**
 298    * Type: #GNUNET_MESSAGE_TYPE_CADET_LOCAL_REQUEST_INFO_CHANNEL.
 299    */
 300   struct GNUNET_MessageHeader header;
 301
 302   /**
 303    * Target of the channel.
 304    */
 305   struct GNUNET_PeerIdentity target;
 306 };
 307
 308
 309 /**
 310  * Message to inform the client about one of the paths known to the service.
 311  */
 312 struct GNUNET_CADET_LocalInfoPath {
 313   /**
 314    * Type: #GNUNET_MESSAGE_TYPE_CADET_LOCAL_INFO_PATH.
 315    */
 316   struct GNUNET_MessageHeader header;
 317
 318   /**
 319    * Offset of the peer that was requested.
 320    */
 321   uint32_t off GNUNET_PACKED;
 322 };
 323
 324
 325 /**
 326  * Message to inform the client about one of the peers in the service.
 327  */
 328 struct GNUNET_CADET_LocalInfoPeers {
 329   /**
 330    * Type: #GNUNET_MESSAGE_TYPE_CADET_LOCAL_INFO_PEERS
 331    */
 332   struct GNUNET_MessageHeader header;
 333
 334   /**
 335    * Number of paths.
 336    */
 337   uint16_t paths GNUNET_PACKED;
 338
 339   /**
 340    * Do we have a tunnel toward this peer?
 341    */
 342   int16_t tunnel GNUNET_PACKED;
 343
 344   /**
 345    * Shortest known path.
 346    */
 347   uint32_t best_path_length GNUNET_PACKED;
 348
 349   /**
 350    * ID of the peer (can be local peer).
 351    */
 352   struct GNUNET_PeerIdentity destination;
 353 };
 354
 355
 356 /**
 357  * Message to inform the client about one of the tunnels in the service.
 358  *
 359  * TODO: split into two messages!
 360  */
 361 struct GNUNET_CADET_LocalInfoTunnel {
 362   /**
 363    * Type: #GNUNET_MESSAGE_TYPE_CADET_LOCAL_INFO_TUNNEL
 364    * or #GNUNET_MESSAGE_TYPE_CADET_LOCAL_INFO_TUNNELS
 365    */
 366   struct GNUNET_MessageHeader header;
 367
 368   /**
 369    * Number of channels.
 370    */
 371   uint32_t channels GNUNET_PACKED;
 372
 373   /**
 374    * ID of the destination of the tunnel (can be local peer).
 375    */
 376   struct GNUNET_PeerIdentity destination;
 377
 378   /**
 379    * Number of connections.
 380    */
 381   uint32_t connections GNUNET_PACKED;
 382
 383   /**
 384    * Encryption state.
 385    */
 386   uint16_t estate GNUNET_PACKED;
 387
 388   /**
 389    * Connection state.
 390    */
 391   uint16_t cstate GNUNET_PACKED;
 392
 393   /* If TUNNEL (no 'S'): struct GNUNET_CADET_ConnectionTunnelIdentifier connection_ids[connections] */
 394   /* If TUNNEL (no 'S'): uint32_t channel_ids[channels] */
 395 };
 396
 397
 398 GNUNET_NETWORK_STRUCT_END
 399
 400
 401 /**
 402  * @brief Translate a fwd variable into a string representation, for logging.
 403  *
 404  * @param fwd Is FWD? (#GNUNET_YES or #GNUNET_NO)
 405  *
 406  * @return String representing FWD or BCK.
 407  */
 408 char *
 409 GC_f2s(int fwd);
 410
 411
 412 /**
 413  * Check if one pid is bigger than other, accounting for overflow.
 414  *
 415  * @param bigger Argument that should be bigger.
 416  * @param smaller Argument that should be smaller.
 417  *
 418  * @return True if bigger (arg1) has a higher value than smaller (arg 2).
 419  */
 420 int
 421 GC_is_pid_bigger(uint32_t bigger, uint32_t smaller);
 422
 423
 424 /**
 425  * Get the higher ACK value out of two values, taking in account overflow.
 426  *
 427  * @param a First ACK value.
 428  * @param b Second ACK value.
 429  *
 430  * @return Highest ACK value from the two.
 431  */
 432 uint32_t
 433 GC_max_pid(uint32_t a, uint32_t b);
 434
 435
 436 /**
 437  * Get the lower ACK value out of two values, taking in account overflow.
 438  *
 439  * @param a First ACK value.
 440  * @param b Second ACK value.
 441  *
 442  * @return Lowest ACK value from the two.
 443  */
 444 uint32_t
 445 GC_min_pid(uint32_t a, uint32_t b);
 446
 447
 448 /**
 449  * Allocate a string with a hexdump of any binary data.
 450  *
 451  * @param bin Arbitrary binary data.
 452  * @param len Length of @a bin in bytes.
 453  * @param output Where to write the output (if *output be NULL it's allocated).
 454  *
 455  * @return The size of the output.
 456  */
 457 size_t
 458 GC_bin2s(void *bin, unsigned int len, char **output);
 459
 460
 461 /**
 462  * Convert a message type into a string to help debug
 463  * Generated with:
 464  * FIND:        "#define ([^ ]+)[ ]*([0-9]+)"
 465  * REPLACE:     "    case \2: return "\1"; break;"
 466  *
 467  * @param m Message type.
 468  *
 469  * @return Human readable string description.
 470  */
 471 const char *
 472 GC_m2s(uint16_t m);
 473
 474 #if 0 /* keep Emacsens' auto-indent happy */
 475 {
 476 #endif
 477 #ifdef __cplusplus
 478 }
 479 #endif
 480
 481 #endif