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