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