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