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