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