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