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