src/cadet/gnunet-service-cadet-new_tunnels.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
   7      it under the terms of the GNU General Public License as published
   8      by the Free Software Foundation; either version 3, or (at your
   9      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      General Public License for more details.
  15
  16      You should have received a copy of the GNU General Public License
  17      along with GNUnet; see the file COPYING.  If not, write to the
  18      Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  19      Boston, MA 02110-1301, USA.
  20 */
  21
  22 /**
  23  * @file cadet/gnunet-service-cadet-new_tunnels.h
  24  * @brief Information we track per tunnel.
  25  * @author Bartlomiej Polot
  26  * @author Christian Grothoff
  27  */
  28 #ifndef GNUNET_SERVICE_CADET_TUNNELS_H
  29 #define GNUNET_SERVICE_CADET_TUNNELS_H
  30
  31 #include "gnunet-service-cadet-new.h"
  32 #include "cadet_protocol.h"
  33
  34
  35 /**
  36  * How many connections would we like to have per tunnel?
  37  */
  38 #define DESIRED_CONNECTIONS_PER_TUNNEL 3
  39
  40
  41 /**
  42  * All the encryption states a tunnel can be in.
  43  */
  44 enum CadetTunnelEState
  45 {
  46   /**
  47    * Uninitialized status, we need to send KX.  We will stay
  48    * in this state until the first connection is up.
  49    */
  50   CADET_TUNNEL_KEY_UNINITIALIZED,
  51
  52   /**
  53    * Ephemeral key sent, waiting for peer's key.
  54    */
  55   CADET_TUNNEL_KEY_SENT,
  56
  57   /**
  58    * Key received and we sent ours back, but we got no traffic yet.
  59    * We will not yet send traffic, as this might have been a replay.
  60    * The other (initiating) peer should send a CHANNEL_OPEN next
  61    * anyway.
  62    */
  63   CADET_TUNNEL_KEY_PING,
  64
  65   /**
  66    * Handshake completed: session key available.
  67    */
  68   CADET_TUNNEL_KEY_OK,
  69
  70   /**
  71    * New ephemeral key and ping sent, waiting for pong. Unlike KEY_PING,
  72    * we still have a valid session key and therefore we *can* still send
  73    * traffic on the tunnel.
  74    */
  75   CADET_TUNNEL_KEY_REKEY
  76 };
  77
  78
  79 /**
  80  * Get the static string for the peer this tunnel is directed.
  81  *
  82  * @param t Tunnel.
  83  *
  84  * @return Static string the destination peer's ID.
  85  */
  86 const char *
  87 GCT_2s (const struct CadetTunnel *t);
  88
  89
  90 /**
  91  * Create a tunnel to @a destionation.  Must only be called
  92  * from within #GCP_get_tunnel().
  93  *
  94  * @param destination where to create the tunnel to
  95  * @return new tunnel to @a destination
  96  */
  97 struct CadetTunnel *
  98 GCT_create_tunnel (struct CadetPeer *destination);
  99
 100
 101 /**
 102  * Destroys the tunnel @a t now, without delay. Used during shutdown.
 103  *
 104  * @param t tunnel to destroy
 105  */
 106 void
 107 GCT_destroy_tunnel_now (struct CadetTunnel *t);
 108
 109
 110 /**
 111  * Add a @a connection to the @a tunnel.
 112  *
 113  * @param t a tunnel
 114  * @param cid connection identifer to use for the connection
 115  * @param path path to use for the connection
 116  * @return #GNUNET_OK on success,
 117  *         #GNUNET_SYSERR on failure (duplicate connection)
 118  */
 119 int
 120 GCT_add_inbound_connection (struct CadetTunnel *t,
 121                             const struct GNUNET_CADET_ConnectionTunnelIdentifier *cid,
 122                             struct CadetPeerPath *path);
 123
 124
 125 /**
 126  * We lost a connection, remove it from our list and clean up
 127  * the connection object itself.
 128  *
 129  * @param ct binding of connection to tunnel of the connection that was lost.
 130  */
 131 void
 132 GCT_connection_lost (struct CadetTConnection *ct);
 133
 134
 135 /**
 136  * Return the peer to which this tunnel goes.
 137  *
 138  * @param t a tunnel
 139  * @return the destination of the tunnel
 140  */
 141 struct CadetPeer *
 142 GCT_get_destination (struct CadetTunnel *t);
 143
 144
 145 /**
 146  * Consider using the path @a p for the tunnel @a t.
 147  * The tunnel destination is at offset @a off in path @a p.
 148  *
 149  * @param cls our tunnel
 150  * @param path a path to our destination
 151  * @param off offset of the destination on path @a path
 152  */
 153 void
 154 GCT_consider_path (struct CadetTunnel *t,
 155                    struct CadetPeerPath *p,
 156                    unsigned int off);
 157
 158
 159 /**
 160  * Add a channel to a tunnel.
 161  *
 162  * @param t Tunnel.
 163  * @param ch Channel
 164  * @return unique number identifying @a ch within @a t
 165  */
 166 struct GNUNET_CADET_ChannelTunnelNumber
 167 GCT_add_channel (struct CadetTunnel *t,
 168                  struct CadetChannel *ch);
 169
 170
 171 /**
 172  * Remove a channel from a tunnel.
 173  *
 174  * @param t Tunnel.
 175  * @param ch Channel
 176  * @param ctn unique number identifying @a ch within @a t
 177  */
 178 void
 179 GCT_remove_channel (struct CadetTunnel *t,
 180                     struct CadetChannel *ch,
 181                     struct GNUNET_CADET_ChannelTunnelNumber ctn);
 182
 183
 184 /**
 185  * Send a DESTROY message via the tunnel.
 186  *
 187  * @param t the tunnel to transmit over
 188  * @param ctn ID of the channel to destroy
 189  */
 190 void
 191 GCT_send_channel_destroy (struct CadetTunnel *t,
 192                           struct GNUNET_CADET_ChannelTunnelNumber ctn);
 193
 194
 195 /**
 196  * Sends an already built message on a tunnel, encrypting it and
 197  * choosing the best connection if not provided.
 198  *
 199  * @param message Message to send. Function modifies it.
 200  * @param t Tunnel on which this message is transmitted.
 201  * @param cont Continuation to call once message is really sent.
 202  * @param cont_cls Closure for @c cont.
 203  * @return Handle to cancel message.
 204  */
 205 struct CadetTunnelQueueEntry *
 206 GCT_send (struct CadetTunnel *t,
 207           const struct GNUNET_MessageHeader *message,
 208           GNUNET_SCHEDULER_TaskCallback cont,
 209           void *cont_cls);
 210
 211
 212 /**
 213  * Cancel a previously sent message while it's in the queue.
 214  *
 215  * ONLY can be called before the continuation given to the send
 216  * function is called. Once the continuation is called, the message is
 217  * no longer in the queue!
 218  *
 219  * @param q Handle to the queue entry to cancel.
 220  */
 221 void
 222 GCT_send_cancel (struct CadetTunnelQueueEntry *q);
 223
 224
 225 /**
 226  * Return the number of channels using a tunnel.
 227  *
 228  * @param t tunnel to count obtain the number of channels for
 229  * @return number of channels using the tunnel
 230  */
 231 unsigned int
 232 GCT_count_channels (struct CadetTunnel *t);
 233
 234
 235 /**
 236  * Return the number of connections available for a tunnel.
 237  *
 238  * @param t tunnel to count obtain the number of connections for
 239  * @return number of connections available for the tunnel
 240  */
 241 unsigned int
 242 GCT_count_any_connections (struct CadetTunnel *t);
 243
 244
 245 /**
 246  * Iterator over connections.
 247  *
 248  * @param cls closure
 249  * @param c one of the connections
 250  */
 251 typedef void
 252 (*GCT_ConnectionIterator) (void *cls,
 253                            struct CadetConnection *c);
 254
 255
 256 /**
 257  * Iterate over all connections of a tunnel.
 258  *
 259  * @param t Tunnel whose connections to iterate.
 260  * @param iter Iterator.
 261  * @param iter_cls Closure for @c iter.
 262  */
 263 void
 264 GCT_iterate_connections (struct CadetTunnel *t,
 265                          GCT_ConnectionIterator iter,
 266                          void *iter_cls);
 267
 268
 269 /**
 270  * Iterator over channels.
 271  *
 272  * @param cls closure
 273  * @param ch one of the channels
 274  */
 275 typedef void
 276 (*GCT_ChannelIterator) (void *cls,
 277                         struct CadetChannel *ch);
 278
 279
 280 /**
 281  * Iterate over all channels of a tunnel.
 282  *
 283  * @param t Tunnel whose channels to iterate.
 284  * @param iter Iterator.
 285  * @param iter_cls Closure for @c iter.
 286  */
 287 void
 288 GCT_iterate_channels (struct CadetTunnel *t,
 289                       GCT_ChannelIterator iter,
 290                       void *iter_cls);
 291
 292
 293 /**
 294  * Get the encryption state of a tunnel.
 295  *
 296  * @param t Tunnel.
 297  *
 298  * @return Tunnel's encryption state.
 299  */
 300 enum CadetTunnelEState
 301 GCT_get_estate (struct CadetTunnel *t);
 302
 303
 304 /**
 305  * Handle KX message.
 306  *
 307  * @param ct connection/tunnel combo that received encrypted message
 308  * @param msg the key exchange message
 309  */
 310 void
 311 GCT_handle_kx (struct CadetTConnection *ct,
 312                const struct GNUNET_CADET_TunnelKeyExchangeMessage *msg);
 313
 314
 315 /**
 316  * Handle encrypted message.
 317  *
 318  * @param ct connection/tunnel combo that received encrypted message
 319  * @param msg the encrypted message to decrypt
 320  */
 321 void
 322 GCT_handle_encrypted (struct CadetTConnection *ct,
 323                       const struct GNUNET_CADET_TunnelEncryptedMessage *msg);
 324
 325
 326 /**
 327  * Log all possible info about the tunnel state.
 328  *
 329  * @param t Tunnel to debug.
 330  * @param level Debug level to use.
 331  */
 332 void
 333 GCT_debug (const struct CadetTunnel *t,
 334            enum GNUNET_ErrorType level);
 335
 336
 337 #endif