src/cadet/gnunet-service-cadet_connection.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_connection.h
  23  * @brief A connection is a live end-to-end messaging mechanism
  24  *       where the peers are identified by a path and know how
  25  *       to forward along the route using a connection identifier
  26  *       for routing the data.
  27  * @author Bartlomiej Polot
  28  * @author Christian Grothoff
  29  */
  30 #ifndef GNUNET_SERVICE_CADET_CONNECTION_H
  31 #define GNUNET_SERVICE_CADET_CONNECTION_H
  32
  33 #include "gnunet_util_lib.h"
  34 #include "gnunet-service-cadet.h"
  35 #include "gnunet-service-cadet_peer.h"
  36 #include "cadet_protocol.h"
  37
  38
  39 /**
  40  * Function called to notify tunnel about change in our readyness.
  41  *
  42  * @param cls closure
  43  * @param is_ready #GNUNET_YES if the connection is now ready for transmission,
  44  *                 #GNUNET_NO if the connection is no longer ready for transmission
  45  */
  46 typedef void
  47 (*GCC_ReadyCallback)(void *cls,
  48                      int is_ready);
  49
  50
  51 /**
  52  * Destroy a connection, called when the CORE layer is already done
  53  * (i.e. has received a BROKEN message), but if we still have to
  54  * communicate the destruction of the connection to the tunnel (if one
  55  * exists).
  56  *
  57  * @param cc connection to destroy
  58  */
  59 void
  60 GCC_destroy_without_core (struct CadetConnection *cc);
  61
  62
  63 /**
  64  * Destroy a connection, called if the tunnel association with the
  65  * connection was already broken, but we still need to notify the CORE
  66  * layer about the breakage.
  67  *
  68  * @param cc connection to destroy
  69  */
  70 void
  71 GCC_destroy_without_tunnel (struct CadetConnection *cc);
  72
  73
  74 /**
  75  * Lookup a connection by its identifier.
  76  *
  77  * @param cid identifier to resolve
  78  * @return NULL if connection was not found
  79  */
  80 struct CadetConnection *
  81 GCC_lookup (const struct GNUNET_CADET_ConnectionTunnelIdentifier *cid);
  82
  83
  84 /**
  85  * Create a connection to @a destination via @a path and
  86  * notify @a cb whenever we are ready for more data.
  87  *
  88  * @param destination where to go
  89  * @param path which path to take (may not be the full path)
  90  * @param off offset of @a destination on @a path
  91  * @param ct which tunnel uses this connection
  92  * @param ready_cb function to call when ready to transmit
  93  * @param ready_cb_cls closure for @a cb
  94  * @return handle to the connection
  95  */
  96 struct CadetConnection *
  97 GCC_create (struct CadetPeer *destination,
  98             struct CadetPeerPath *path,
  99             unsigned int off,
 100             struct CadetTConnection *ct,
 101             GCC_ReadyCallback ready_cb,
 102             void *ready_cb_cls);
 103
 104
 105 /**
 106  * Create a connection to @a destination via @a path and
 107  * notify @a cb whenever we are ready for more data.  This
 108  * is an inbound tunnel, so we must use the existing @a cid
 109  *
 110  * @param destination where to go
 111  * @param path which path to take (may not be the full path)
 112  * @param ct which tunnel uses this connection
 113  * @param ready_cb function to call when ready to transmit
 114  * @param ready_cb_cls closure for @a cb
 115  * @return handle to the connection, NULL if we already have
 116  *         a connection that takes precedence on @a path
 117  */
 118 struct CadetConnection *
 119 GCC_create_inbound (struct CadetPeer *destination,
 120                     struct CadetPeerPath *path,
 121                     struct CadetTConnection *ct,
 122                     const struct GNUNET_CADET_ConnectionTunnelIdentifier *cid,
 123                     GCC_ReadyCallback ready_cb,
 124                     void *ready_cb_cls);
 125
 126
 127 /**
 128  * Transmit message @a msg via connection @a cc.  Must only be called
 129  * (once) after the connection has signalled that it is ready via the
 130  * `ready_cb`.  Clients can also use #GCC_is_ready() to check if the
 131  * connection is right now ready for transmission.
 132  *
 133  * @param cc connection identification
 134  * @param env envelope with message to transmit;
 135  *            the #GNUNET_MQ_notify_send() must not have yet been used
 136  *            for the envelope.  Also, the message better match the
 137  *            connection identifier of this connection...
 138  */
 139 void
 140 GCC_transmit (struct CadetConnection *cc,
 141               struct GNUNET_MQ_Envelope *env);
 142
 143
 144 /**
 145  * A CREATE_ACK was received for this connection, process it.
 146  *
 147  * @param cc the connection that got the ACK.
 148  */
 149 void
 150 GCC_handle_connection_create_ack (struct CadetConnection *cc);
 151
 152
 153 /**
 154  * We got a #GNUNET_MESSAGE_TYPE_CADET_CONNECTION_CREATE for a
 155  * connection that we already have.  Either our ACK got lost
 156  * or something is fishy.  Consider retransmitting the ACK.
 157  *
 158  * @param cc connection that got the duplicate CREATE
 159  */
 160 void
 161 GCC_handle_duplicate_create (struct CadetConnection *cc);
 162
 163
 164 /**
 165  * Handle KX message.
 166  *
 167  * @param cc connection that received encrypted message
 168  * @param msg the key exchange message
 169  */
 170 void
 171 GCC_handle_kx (struct CadetConnection *cc,
 172                const struct GNUNET_CADET_TunnelKeyExchangeMessage *msg);
 173
 174
 175 /**
 176  * Handle KX_AUTH message.
 177  *
 178  * @param cc connection that received encrypted message
 179  * @param msg the key exchange message
 180  */
 181 void
 182 GCC_handle_kx_auth (struct CadetConnection *cc,
 183                     const struct
 184                     GNUNET_CADET_TunnelKeyExchangeAuthMessage *msg);
 185
 186
 187 /**
 188  * Performance metrics for a connection.
 189  */
 190 struct CadetConnectionMetrics
 191 {
 192   /**
 193    * Our current best estimate of the latency, based on a weighted
 194    * average of at least @a latency_datapoints values.
 195    */
 196   struct GNUNET_TIME_Relative aged_latency;
 197
 198   /**
 199    * When was this connection first established? (by us sending or
 200    * receiving the CREATE_ACK for the first time)
 201    */
 202   struct GNUNET_TIME_Absolute age;
 203
 204   /**
 205    * When was this connection last used? (by us sending or
 206    * receiving a PAYLOAD message on it)
 207    */
 208   struct GNUNET_TIME_Absolute last_use;
 209
 210   /**
 211    * How many packets that ought to generate an ACK did we send via
 212    * this connection?
 213    */
 214   unsigned long long num_acked_transmissions;
 215
 216   /**
 217    * Number of packets that were sent via this connection did actually
 218    * receive an ACK?  (Note: ACKs may be transmitted and lost via
 219    * other connections, so this value should only be interpreted
 220    * relative to @e num_acked_transmissions and in relation to other
 221    * connections.)
 222    */
 223   unsigned long long num_successes;
 224 };
 225
 226
 227 /**
 228  * Obtain performance @a metrics from @a cc.
 229  *
 230  * @param cc connection to query
 231  * @return the metrics
 232  */
 233 const struct CadetConnectionMetrics *
 234 GCC_get_metrics (struct CadetConnection *cc);
 235
 236
 237 /**
 238  * Handle encrypted message.
 239  *
 240  * @param cc connection that received encrypted message
 241  * @param msg the encrypted message to decrypt
 242  */
 243 void
 244 GCC_handle_encrypted (struct CadetConnection *cc,
 245                       const struct GNUNET_CADET_TunnelEncryptedMessage *msg);
 246
 247
 248 /**
 249  * We sent a message for which we expect to receive an ACK via
 250  * the connection identified by @a cti.
 251  *
 252  * @param cid connection identifier where we expect an ACK
 253  */
 254 void
 255 GCC_ack_expected (const struct GNUNET_CADET_ConnectionTunnelIdentifier *cid);
 256
 257
 258 /**
 259  * We observed an ACK for a message that was originally sent via
 260  * the connection identified by @a cti.
 261  *
 262  * @param cid connection identifier where we got an ACK for a message
 263  *            that was originally sent via this connection (the ACK
 264  *            may have gotten back to us via a different connection).
 265  */
 266 void
 267 GCC_ack_observed (const struct GNUNET_CADET_ConnectionTunnelIdentifier *cid);
 268
 269
 270 /**
 271  * We observed some the given @a latency on the connection
 272  * identified by @a cti.  (The same connection was taken
 273  * in both directions.)
 274  *
 275  * @param cti connection identifier where we measured latency
 276  * @param latency the observed latency
 277  */
 278 void
 279 GCC_latency_observed (const struct GNUNET_CADET_ConnectionTunnelIdentifier *cti,
 280                       struct GNUNET_TIME_Relative latency);
 281
 282
 283 /**
 284  * Return the tunnel associated with this connection.
 285  *
 286  * @param cc connection to query
 287  * @return corresponding entry in the tunnel's connection list
 288  */
 289 struct CadetTConnection *
 290 GCC_get_ct (struct CadetConnection *cc);
 291
 292
 293 /**
 294  * Obtain the path used by this connection.
 295  *
 296  * @param cc connection
 297  * @param off[out] set to offset in this path where the connection @a cc ends
 298  * @return path to @a cc
 299  */
 300 struct CadetPeerPath *
 301 GCC_get_path (struct CadetConnection *cc,
 302               unsigned int *off);
 303
 304
 305 /**
 306  * Obtain unique ID for the connection.
 307  *
 308  * @param cc connection.
 309  * @return unique number of the connection
 310  */
 311 const struct GNUNET_CADET_ConnectionTunnelIdentifier *
 312 GCC_get_id (struct CadetConnection *cc);
 313
 314
 315 /**
 316  * Get a (static) string for a connection.
 317  *
 318  * @param cc Connection.
 319  */
 320 const char *
 321 GCC_2s (const struct CadetConnection *cc);
 322
 323
 324 /**
 325  * Log connection info.
 326  *
 327  * @param cc connection
 328  * @param level Debug level to use.
 329  */
 330 void
 331 GCC_debug (struct CadetConnection *cc,
 332            enum GNUNET_ErrorType level);
 333
 334
 335 #endif