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  * Add a @a connection to the @a tunnel.
 103  *
 104  * @param t a tunnel
 105  * @param cid connection identifer to use for the connection
 106  * @param path path to use for the connection
 107  */
 108 void
 109 GCT_add_inbound_connection (struct CadetTunnel *t,
 110                             const struct GNUNET_CADET_ConnectionTunnelIdentifier *cid,
 111                             struct CadetPeerPath *path);
 112
 113
 114 /**
 115  * Return the peer to which this tunnel goes.
 116  *
 117  * @param t a tunnel
 118  * @return the destination of the tunnel
 119  */
 120 struct CadetPeer *
 121 GCT_get_destination (struct CadetTunnel *t);
 122
 123
 124 /**
 125  * Consider using the path @a p for the tunnel @a t.
 126  * The tunnel destination is at offset @a off in path @a p.
 127  *
 128  * @param cls our tunnel
 129  * @param path a path to our destination
 130  * @param off offset of the destination on path @a path
 131  */
 132 void
 133 GCT_consider_path (struct CadetTunnel *t,
 134                    struct CadetPeerPath *p,
 135                    unsigned int off);
 136
 137
 138 /**
 139  * Add a channel to a tunnel.
 140  *
 141  * @param t Tunnel.
 142  * @param ch Channel
 143  * @return unique number identifying @a ch within @a t
 144  */
 145 struct GNUNET_CADET_ChannelTunnelNumber
 146 GCT_add_channel (struct CadetTunnel *t,
 147                  struct CadetChannel *ch);
 148
 149
 150 /**
 151  * Remove a channel from a tunnel.
 152  *
 153  * @param t Tunnel.
 154  * @param ch Channel
 155  * @param ctn unique number identifying @a ch within @a t
 156  */
 157 void
 158 GCT_remove_channel (struct CadetTunnel *t,
 159                     struct CadetChannel *ch,
 160                     struct GNUNET_CADET_ChannelTunnelNumber ctn);
 161
 162
 163 /**
 164  * Send a DESTROY message via the tunnel.
 165  *
 166  * @param t the tunnel to transmit over
 167  * @param ctn ID of the channel to destroy
 168  */
 169 void
 170 GCT_send_channel_destroy (struct CadetTunnel *t,
 171                           struct GNUNET_CADET_ChannelTunnelNumber ctn);
 172
 173
 174 /**
 175  * Sends an already built message on a tunnel, encrypting it and
 176  * choosing the best connection if not provided.
 177  *
 178  * @param message Message to send. Function modifies it.
 179  * @param t Tunnel on which this message is transmitted.
 180  * @param cont Continuation to call once message is really sent.
 181  * @param cont_cls Closure for @c cont.
 182  * @return Handle to cancel message. NULL if @c cont is NULL.
 183  */
 184 struct CadetTunnelQueueEntry *
 185 GCT_send (struct CadetTunnel *t,
 186           const struct GNUNET_MessageHeader *message,
 187           GNUNET_SCHEDULER_TaskCallback cont,
 188           void *cont_cls);
 189
 190
 191 /**
 192  * Cancel a previously sent message while it's in the queue.
 193  *
 194  * ONLY can be called before the continuation given to the send
 195  * function is called. Once the continuation is called, the message is
 196  * no longer in the queue!
 197  *
 198  * @param q Handle to the queue entry to cancel.
 199  */
 200 void
 201 GCT_send_cancel (struct CadetTunnelQueueEntry *q);
 202
 203
 204 /**
 205  * Return the number of channels using a tunnel.
 206  *
 207  * @param t tunnel to count obtain the number of channels for
 208  * @return number of channels using the tunnel
 209  */
 210 unsigned int
 211 GCT_count_channels (struct CadetTunnel *t);
 212
 213
 214 /**
 215  * Return the number of connections available for a tunnel.
 216  *
 217  * @param t tunnel to count obtain the number of connections for
 218  * @return number of connections available for the tunnel
 219  */
 220 unsigned int
 221 GCT_count_any_connections (struct CadetTunnel *t);
 222
 223
 224 /**
 225  * Iterator over connections.
 226  *
 227  * @param cls closure
 228  * @param c one of the connections
 229  */
 230 typedef void
 231 (*GCT_ConnectionIterator) (void *cls,
 232                            struct CadetConnection *c);
 233
 234
 235 /**
 236  * Iterate over all connections of a tunnel.
 237  *
 238  * @param t Tunnel whose connections to iterate.
 239  * @param iter Iterator.
 240  * @param iter_cls Closure for @c iter.
 241  */
 242 void
 243 GCT_iterate_connections (struct CadetTunnel *t,
 244                          GCT_ConnectionIterator iter,
 245                          void *iter_cls);
 246
 247
 248 /**
 249  * Iterator over channels.
 250  *
 251  * @param cls closure
 252  * @param ch one of the channels
 253  */
 254 typedef void
 255 (*GCT_ChannelIterator) (void *cls,
 256                         struct CadetChannel *ch);
 257
 258
 259 /**
 260  * Iterate over all channels of a tunnel.
 261  *
 262  * @param t Tunnel whose channels to iterate.
 263  * @param iter Iterator.
 264  * @param iter_cls Closure for @c iter.
 265  */
 266 void
 267 GCT_iterate_channels (struct CadetTunnel *t,
 268                       GCT_ChannelIterator iter,
 269                       void *iter_cls);
 270
 271
 272 /**
 273  * Get the encryption state of a tunnel.
 274  *
 275  * @param t Tunnel.
 276  *
 277  * @return Tunnel's encryption state.
 278  */
 279 enum CadetTunnelEState
 280 GCT_get_estate (struct CadetTunnel *t);
 281
 282
 283 /**
 284  * Handle KX message.
 285  *
 286  * @param ct connection/tunnel combo that received encrypted message
 287  * @param msg the key exchange message
 288  */
 289 void
 290 GCT_handle_kx (struct CadetTConnection *ct,
 291                const struct GNUNET_CADET_TunnelKeyExchangeMessage *msg);
 292
 293
 294 /**
 295  * Handle encrypted message.
 296  *
 297  * @param ct connection/tunnel combo that received encrypted message
 298  * @param msg the encrypted message to decrypt
 299  */
 300 void
 301 GCT_handle_encrypted (struct CadetTConnection *ct,
 302                       const struct GNUNET_CADET_TunnelEncryptedMessage *msg);
 303
 304
 305 /**
 306  * Log all possible info about the tunnel state.
 307  *
 308  * @param t Tunnel to debug.
 309  * @param level Debug level to use.
 310  */
 311 void
 312 GCT_debug (const struct CadetTunnel *t,
 313            enum GNUNET_ErrorType level);
 314
 315
 316 #endif