src/cadet/gnunet-service-cadet.h

   1
   2 /*
   3      This file is part of GNUnet.
   4      Copyright (C) 2001-2017 GNUnet e.V.
   5
   6      GNUnet is free software: you can redistribute it and/or modify it
   7      under the terms of the GNU Affero General Public License as published
   8      by the Free Software Foundation, either version 3 of the License,
   9      or (at your option) any later version.
  10
  11      GNUnet is distributed in the hope that it will be useful, but
  12      WITHOUT ANY WARRANTY; without even the implied warranty of
  13      MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14      Affero General Public License for more details.
  15 */
  16
  17 /**
  18  * @file cadet/gnunet-service-cadet.h
  19  * @brief Information we track per peer.
  20  * @author Bartlomiej Polot
  21  * @author Christian Grothoff
  22  */
  23 #ifndef GNUNET_SERVICE_CADET_H
  24 #define GNUNET_SERVICE_CADET_H
  25
  26 #include "gnunet_util_lib.h"
  27 #include "cadet_protocol.h"
  28
  29 /**
  30  * A client to the CADET service.  Each client gets a unique handle.
  31  */
  32 struct CadetClient;
  33
  34 /**
  35  * A peer in the GNUnet network.  Each peer we care about must have one globally
  36  * unique such handle within this process.
  37  */
  38 struct CadetPeer;
  39
  40 /**
  41  * Tunnel from us to another peer.  There can only be at most one
  42  * tunnel per peer.
  43  */
  44 struct CadetTunnel;
  45
  46 /**
  47  * Entry in the message queue of a `struct CadetTunnel`.
  48  */
  49 struct CadetTunnelQueueEntry;
  50
  51 /**
  52  * A path of peer in the GNUnet network.  There must only be at most
  53  * once such path.  Paths may share disjoint prefixes, but must all
  54  * end at a unique suffix.  Paths must also not be proper subsets of
  55  * other existing paths.
  56  */
  57 struct CadetPeerPath;
  58
  59 /**
  60  * Entry in a peer path.
  61  */
  62 struct CadetPeerPathEntry
  63 {
  64   /**
  65    * DLL of paths where the same @e peer is at the same offset.
  66    */
  67   struct CadetPeerPathEntry *next;
  68
  69   /**
  70    * DLL of paths where the same @e peer is at the same offset.
  71    */
  72   struct CadetPeerPathEntry *prev;
  73
  74   /**
  75    * The peer at this offset of the path.
  76    */
  77   struct CadetPeer *peer;
  78
  79   /**
  80    * Path this entry belongs to.
  81    */
  82   struct CadetPeerPath *path;
  83
  84   /**
  85    * Connection using this path, or NULL for none.
  86    */
  87   struct CadetConnection *cc;
  88
  89   /**
  90    * Path's historic score up to this point.  Basically, how often did
  91    * we succeed or fail to use the path up to this entry in a
  92    * connection.  Positive values indicate good experiences, negative
  93    * values bad experiences.  Code updating the score must guard
  94    * against overflows.
  95    */
  96   int score;
  97
  98 };
  99
 100 /**
 101  * Entry in list of connections used by tunnel, with metadata.
 102  */
 103 struct CadetTConnection
 104 {
 105   /**
 106    * Next in DLL.
 107    */
 108   struct CadetTConnection *next;
 109
 110   /**
 111    * Prev in DLL.
 112    */
 113   struct CadetTConnection *prev;
 114
 115   /**
 116    * Connection handle.
 117    */
 118   struct CadetConnection *cc;
 119
 120   /**
 121    * Tunnel this connection belongs to.
 122    */
 123   struct CadetTunnel *t;
 124
 125   /**
 126    * Creation time, to keep oldest connection alive.
 127    */
 128   struct GNUNET_TIME_Absolute created;
 129
 130   /**
 131    * Connection throughput, to keep fastest connection alive.
 132    */
 133   uint32_t throughput;
 134
 135   /**
 136    * Is the connection currently ready for transmission?
 137    */
 138   int is_ready;
 139 };
 140
 141
 142 /**
 143  * Port opened by a client.
 144  */
 145 struct OpenPort
 146 {
 147
 148   /**
 149    * Client that opened the port.
 150    */
 151   struct CadetClient *c;
 152
 153   /**
 154    * Port number.
 155    */
 156   struct GNUNET_HashCode port;
 157
 158   /**
 159    * Port hashed with our PID (matches incoming OPEN messages).
 160    */
 161   struct GNUNET_HashCode h_port;
 162
 163 };
 164
 165
 166 /**
 167  * Active path through the network (used by a tunnel).  There may
 168  * be at most one connection per path.
 169  */
 170 struct CadetConnection;
 171
 172 /**
 173  * Description of a segment of a `struct CadetConnection` at the
 174  * intermediate peers.  Routes are basically entries in a peer's
 175  * routing table for forwarding traffic.  At both endpoints, the
 176  * routes are terminated by a `struct CadetConnection`, which knows
 177  * the complete `struct CadetPath` that is formed by the individual
 178  * routes.
 179  */
 180 struct CadetRoute;
 181
 182 /**
 183  * Logical end-to-end conenction between clients.  There can be
 184  * any number of channels between clients.
 185  */
 186 struct CadetChannel;
 187
 188 /**
 189  * Handle to our configuration.
 190  */
 191 extern const struct GNUNET_CONFIGURATION_Handle *cfg;
 192
 193 /**
 194  * Handle to the statistics service.
 195  */
 196 extern struct GNUNET_STATISTICS_Handle *stats;
 197
 198 /**
 199  * Handle to communicate with ATS.
 200  */
 201 extern struct GNUNET_ATS_ConnectivityHandle *ats_ch;
 202
 203 /**
 204  * Local peer own ID.
 205  */
 206 extern struct GNUNET_PeerIdentity my_full_id;
 207
 208 /**
 209  * Own private key.
 210  */
 211 extern struct GNUNET_CRYPTO_EddsaPrivateKey *my_private_key;
 212
 213 /**
 214  * All ports clients of this peer have opened.  Maps from
 215  * a hashed port to a `struct OpenPort`.
 216  */
 217 extern struct GNUNET_CONTAINER_MultiHashMap *open_ports;
 218
 219 /**
 220  * Map from `struct GNUNET_CADET_ConnectionTunnelIdentifier`
 221  * hash codes to `struct CadetConnection` objects.
 222  */
 223 extern struct GNUNET_CONTAINER_MultiShortmap *connections;
 224
 225 /**
 226  * Map from ports to channels where the ports were closed at the
 227  * time we got the inbound connection.
 228  * Indexed by h_port, contains `struct CadetChannel`.
 229  */
 230 extern struct GNUNET_CONTAINER_MultiHashMap *loose_channels;
 231
 232 /**
 233  * Map from PIDs to `struct CadetPeer` entries.
 234  */
 235 extern struct GNUNET_CONTAINER_MultiPeerMap *peers;
 236
 237 /**
 238  * How many messages are needed to trigger an AXOLOTL ratchet advance.
 239  */
 240 extern unsigned long long ratchet_messages;
 241
 242 /**
 243  * How long until we trigger a ratched advance due to time.
 244  */
 245 extern struct GNUNET_TIME_Relative ratchet_time;
 246
 247 /**
 248  * How frequently do we send KEEPALIVE messages on idle connections?
 249  */
 250 extern struct GNUNET_TIME_Relative keepalive_period;
 251
 252 /**
 253  * Signal that shutdown is happening: prevent recovery measures.
 254  */
 255 extern int shutting_down;
 256
 257 /**
 258  * Set to non-zero values to create random drops to test retransmissions.
 259  */
 260 extern unsigned long long drop_percent;
 261
 262
 263 /**
 264  * Send a message to a client.
 265  *
 266  * @param c client to get the message
 267  * @param env envelope with the message
 268  */
 269 void
 270 GSC_send_to_client (struct CadetClient *c,
 271                     struct GNUNET_MQ_Envelope *env);
 272
 273
 274 /**
 275  * A channel was destroyed by the other peer. Tell our client.
 276  *
 277  * @param c client that lost a channel
 278  * @param ccn channel identification number for the client
 279  * @param ch the channel object
 280  */
 281 void
 282 GSC_handle_remote_channel_destroy (struct CadetClient *c,
 283                                    struct GNUNET_CADET_ClientChannelNumber ccn,
 284                                    struct CadetChannel *ch);
 285
 286 /**
 287  * A client that created a loose channel that was not bound to a port
 288  * disconnected, drop it from the #loose_channels list.
 289  *
 290  * @param h_port the hashed port the channel was trying to bind to
 291  * @param ch the channel that was lost
 292  */
 293 void
 294 GSC_drop_loose_channel (const struct GNUNET_HashCode *h_port,
 295                         struct CadetChannel *ch);
 296
 297
 298 /**
 299  * Bind incoming channel to this client, and notify client
 300  * about incoming connection.
 301  *
 302  * @param c client to bind to
 303  * @param ch channel to be bound
 304  * @param dest peer that establishes the connection
 305  * @param port port number
 306  * @param options options
 307  * @return local channel number assigned to the new client
 308  */
 309 struct GNUNET_CADET_ClientChannelNumber
 310 GSC_bind (struct CadetClient *c,
 311           struct CadetChannel *ch,
 312           struct CadetPeer *dest,
 313           const struct GNUNET_HashCode *port,
 314           uint32_t options);
 315
 316
 317 /**
 318  * Return identifier for a client as a string.
 319  *
 320  * @param c client to identify
 321  * @return string for debugging
 322  */
 323 const char *
 324 GSC_2s (struct CadetClient *c);
 325
 326
 327 #endif