src/cadet/gnunet-service-cadet.h

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