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 connectivity states a tunnel can be in.
  43  */
  44 enum CadetTunnelCState
  45 {
  46   /**
  47    * Uninitialized status, should never appear in operation.
  48    */
  49   CADET_TUNNEL_NEW,
  50
  51   /**
  52    * No path to the peer known yet.
  53    */
  54   CADET_TUNNEL_SEARCHING,
  55
  56   /**
  57    * Request sent, not yet answered.
  58    */
  59   CADET_TUNNEL_WAITING,
  60
  61   /**
  62    * Peer connected and ready to accept data.
  63    */
  64   CADET_TUNNEL_READY,
  65
  66   /**
  67    * Tunnel being shut down, don't try to keep it alive.
  68    */
  69   CADET_TUNNEL_SHUTDOWN
  70 };
  71
  72
  73
  74 /**
  75  * All the encryption states a tunnel can be in.
  76  */
  77 enum CadetTunnelEState
  78 {
  79   /**
  80    * Uninitialized status, should never appear in operation.
  81    */
  82   CADET_TUNNEL_KEY_UNINITIALIZED,
  83
  84   /**
  85    * Ephemeral key sent, waiting for peer's key.
  86    */
  87   CADET_TUNNEL_KEY_SENT,
  88
  89   /**
  90    * In OTR: New ephemeral key and ping sent, waiting for pong.
  91    *
  92    * This means that we DO have the peer's ephemeral key, otherwise the
  93    * state would be KEY_SENT. We DO NOT have a valid session key (either no
  94    * previous key or previous key expired).
  95    *
  96    *
  97    * In Axolotl: Key sent and received but no deciphered traffic yet.
  98    *
  99    * This means that we can send traffic (otherwise we would never complete
 100    * the handshake), but we don't have complete confirmation. Since the first
 101    * traffic MUST be a complete channel creation 3-way handshake, no payload
 102    * will be sent before confirmation.
 103    */
 104   CADET_TUNNEL_KEY_PING,
 105
 106   /**
 107    * Handshake completed: session key available.
 108    */
 109   CADET_TUNNEL_KEY_OK,
 110
 111   /**
 112    * New ephemeral key and ping sent, waiting for pong. Unlike KEY_PING,
 113    * we still have a valid session key and therefore we *can* still send
 114    * traffic on the tunnel.
 115    */
 116   CADET_TUNNEL_KEY_REKEY
 117 };
 118
 119
 120 /**
 121  * Number uniquely identifying a channel within a tunnel.
 122  */
 123 struct GCT_ChannelTunnelNumber
 124 {
 125   uint32_t channel_in_tunnel GNUNET_PACKED;
 126 };
 127
 128
 129 /**
 130  * Get the static string for the peer this tunnel is directed.
 131  *
 132  * @param t Tunnel.
 133  *
 134  * @return Static string the destination peer's ID.
 135  */
 136 const char *
 137 GCT_2s (const struct CadetTunnel *t);
 138
 139
 140 /**
 141  * Create a tunnel to @a destionation.  Must only be called
 142  * from within #GCP_get_tunnel().
 143  *
 144  * @param destination where to create the tunnel to
 145  * @return new tunnel to @a destination
 146  */
 147 struct CadetTunnel *
 148 GCT_create_tunnel (struct CadetPeer *destination);
 149
 150
 151 /**
 152  * Return the peer to which this tunnel goes.
 153  *
 154  * @param t a tunnel
 155  * @return the destination of the tunnel
 156  */
 157 struct CadetPeer *
 158 GCT_get_destination (struct CadetTunnel *t);
 159
 160
 161 /**
 162  * Consider using the path @a p for the tunnel @a t.
 163  * The tunnel destination is at offset @a off in path @a p.
 164  *
 165  * @param cls our tunnel
 166  * @param path a path to our destination
 167  * @param off offset of the destination on path @a path
 168  */
 169 void
 170 GCT_consider_path (struct CadetTunnel *t,
 171                    struct CadetPeerPath *p,
 172                    unsigned int off);
 173
 174
 175 /**
 176  * Add a channel to a tunnel.
 177  *
 178  * @param t Tunnel.
 179  * @param ch Channel
 180  * @return unique number identifying @a ch within @a t
 181  */
 182 struct GCT_ChannelTunnelNumber
 183 GCT_add_channel (struct CadetTunnel *t,
 184                  struct CadetChannel *ch);
 185
 186
 187 /**
 188  * Remove a channel from a tunnel.
 189  *
 190  * @param t Tunnel.
 191  * @param ch Channel
 192  * @param gid unique number identifying @a ch within @a t
 193  */
 194 void
 195 GCT_remove_channel (struct CadetTunnel *t,
 196                     struct CadetChannel *ch,
 197                     struct GCT_ChannelTunnelNumber gid);
 198
 199
 200 /**
 201  * Sends an already built message on a tunnel, encrypting it and
 202  * choosing the best connection if not provided.
 203  *
 204  * @param message Message to send. Function modifies it.
 205  * @param t Tunnel on which this message is transmitted.
 206  * @param cont Continuation to call once message is really sent.
 207  * @param cont_cls Closure for @c cont.
 208  * @return Handle to cancel message. NULL if @c cont is NULL.
 209  */
 210 struct CadetTunnelQueueEntry *
 211 GCT_send (struct CadetTunnel *t,
 212           const struct GNUNET_MessageHeader *message,
 213           GNUNET_SCHEDULER_TaskCallback cont,
 214           void *cont_cls);
 215
 216
 217 /**
 218  * Cancel a previously sent message while it's in the queue.
 219  *
 220  * ONLY can be called before the continuation given to the send
 221  * function is called. Once the continuation is called, the message is
 222  * no longer in the queue!
 223  *
 224  * @param q Handle to the queue entry to cancel.
 225  */
 226 void
 227 GCT_send_cancel (struct CadetTunnelQueueEntry *q);
 228
 229
 230 /**
 231  * Return the number of channels using a tunnel.
 232  *
 233  * @param t tunnel to count obtain the number of channels for
 234  * @return number of channels using the tunnel
 235  */
 236 unsigned int
 237 GCT_count_channels (struct CadetTunnel *t);
 238
 239
 240 /**
 241  * Return the number of connections available for a tunnel.
 242  *
 243  * @param t tunnel to count obtain the number of connections for
 244  * @return number of connections available for the tunnel
 245  */
 246 unsigned int
 247 GCT_count_any_connections (struct CadetTunnel *t);
 248
 249
 250 /**
 251  * Iterator over connections.
 252  *
 253  * @param cls closure
 254  * @param c one of the connections
 255  */
 256 typedef void
 257 (*GCT_ConnectionIterator) (void *cls,
 258                            struct CadetConnection *c);
 259
 260
 261 /**
 262  * Iterate over all connections of a tunnel.
 263  *
 264  * @param t Tunnel whose connections to iterate.
 265  * @param iter Iterator.
 266  * @param iter_cls Closure for @c iter.
 267  */
 268 void
 269 GCT_iterate_connections (struct CadetTunnel *t,
 270                          GCT_ConnectionIterator iter,
 271                          void *iter_cls);
 272
 273
 274 /**
 275  * Iterator over channels.
 276  *
 277  * @param cls closure
 278  * @param ch one of the channels
 279  */
 280 typedef void
 281 (*GCT_ChannelIterator) (void *cls,
 282                         struct CadetChannel *ch);
 283
 284
 285 /**
 286  * Iterate over all channels of a tunnel.
 287  *
 288  * @param t Tunnel whose channels to iterate.
 289  * @param iter Iterator.
 290  * @param iter_cls Closure for @c iter.
 291  */
 292 void
 293 GCT_iterate_channels (struct CadetTunnel *t,
 294                       GCT_ChannelIterator iter,
 295                       void *iter_cls);
 296
 297
 298 /**
 299  * Get the connectivity state of a tunnel.
 300  *
 301  * @param t Tunnel.
 302  *
 303  * @return Tunnel's connectivity state.
 304  */
 305 enum CadetTunnelCState
 306 GCT_get_cstate (struct CadetTunnel *t);
 307
 308
 309 /**
 310  * Get the encryption state of a tunnel.
 311  *
 312  * @param t Tunnel.
 313  *
 314  * @return Tunnel's encryption state.
 315  */
 316 enum CadetTunnelEState
 317 GCT_get_estate (struct CadetTunnel *t);
 318
 319
 320 /**
 321  * Handle KX message.
 322  *
 323  * @param ct connection/tunnel combo that received encrypted message
 324  * @param msg the key exchange message
 325  */
 326 void
 327 GCT_handle_kx (struct CadetTConnection *ct,
 328                const struct GNUNET_CADET_KX *msg);
 329
 330
 331 /**
 332  * Handle encrypted message.
 333  *
 334  * @param ct connection/tunnel combo that received encrypted message
 335  * @param msg the encrypted message to decrypt
 336  */
 337 void
 338 GCT_handle_encrypted (struct CadetTConnection *ct,
 339                       const struct GNUNET_CADET_Encrypted *msg);
 340
 341
 342 /**
 343  * Log all possible info about the tunnel state.
 344  *
 345  * @param t Tunnel to debug.
 346  * @param level Debug level to use.
 347  */
 348 void
 349 GCT_debug (const struct CadetTunnel *t,
 350            enum GNUNET_ErrorType level);
 351
 352
 353 #endif