src/cadet/gnunet-service-cadet_tunnels.h

   1 /*
   2      This file is part of GNUnet.
   3      Copyright (C) 2001-2017 GNUnet e.V.
   4
   5      GNUnet is free software: you can redistribute it and/or modify it
   6      under the terms of the GNU Affero General Public License as published
   7      by the Free Software Foundation, either version 3 of the License,
   8      or (at your option) any later version.
   9
  10      GNUnet is distributed in the hope that it will be useful, but
  11      WITHOUT ANY WARRANTY; without even the implied warranty of
  12      MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13      Affero General Public License for more details.
  14
  15      You should have received a copy of the GNU Affero General Public License
  16      along with this program.  If not, see <http://www.gnu.org/licenses/>.
  17
  18      SPDX-License-Identifier: AGPL3.0-or-later
  19  */
  20
  21 /**
  22  * @file cadet/gnunet-service-cadet_tunnels.h
  23  * @brief Information we track per tunnel.
  24  * @author Bartlomiej Polot
  25  * @author Christian Grothoff
  26  */
  27 #ifndef GNUNET_SERVICE_CADET_TUNNELS_H
  28 #define GNUNET_SERVICE_CADET_TUNNELS_H
  29
  30 #include "gnunet-service-cadet.h"
  31 #include "cadet_protocol.h"
  32
  33
  34 /**
  35  * How many connections would we like to have per tunnel?
  36  */
  37 #define DESIRED_CONNECTIONS_PER_TUNNEL 3
  38
  39
  40 /**
  41  * All the encryption states a tunnel can be in.
  42  */
  43 enum CadetTunnelEState
  44 {
  45   /**
  46    * Uninitialized status, we need to send KX.  We will stay
  47    * in this state until the first connection is up.
  48    */
  49   CADET_TUNNEL_KEY_UNINITIALIZED,
  50
  51   /**
  52    * KX message sent, waiting for other peer's KX_AUTH.
  53    */
  54   CADET_TUNNEL_KEY_AX_SENT,
  55
  56   /**
  57    * KX message received, trying to send back KX_AUTH.
  58    */
  59   CADET_TUNNEL_KEY_AX_RECV,
  60
  61   /**
  62    * KX message sent and received, trying to send back KX_AUTH.
  63    */
  64   CADET_TUNNEL_KEY_AX_SENT_AND_RECV,
  65
  66   /**
  67    * KX received and we sent KX_AUTH back, but we got no traffic yet,
  68    * so we're waiting for either KX_AUTH or ENCRYPED traffic from
  69    * the other peer.
  70    *
  71    * We will not yet send traffic, as this might have been a replay.
  72    * The other (initiating) peer should send a CHANNEL_OPEN next
  73    * anyway, and then we are in business!
  74    */
  75   CADET_TUNNEL_KEY_AX_AUTH_SENT,
  76
  77   /**
  78    * Handshake completed: session key available.
  79    */
  80   CADET_TUNNEL_KEY_OK
  81 };
  82
  83
  84 /**
  85  * Get the static string for the peer this tunnel is directed.
  86  *
  87  * @param t Tunnel.
  88  *
  89  * @return Static string the destination peer's ID.
  90  */
  91 const char *
  92 GCT_2s (const struct CadetTunnel *t);
  93
  94
  95 /**
  96  * Create a tunnel to @a destionation.  Must only be called
  97  * from within #GCP_get_tunnel().
  98  *
  99  * @param destination where to create the tunnel to
 100  * @return new tunnel to @a destination
 101  */
 102 struct CadetTunnel *
 103 GCT_create_tunnel (struct CadetPeer *destination);
 104
 105
 106 /**
 107  * Destroys the tunnel @a t now, without delay. Used during shutdown.
 108  *
 109  * @param t tunnel to destroy
 110  */
 111 void
 112 GCT_destroy_tunnel_now (struct CadetTunnel *t);
 113
 114
 115 /**
 116  * Add a @a connection to the @a tunnel.
 117  *
 118  * @param t a tunnel
 119  * @param cid connection identifer to use for the connection
 120  * @param path path to use for the connection
 121  * @return #GNUNET_OK on success,
 122  *         #GNUNET_SYSERR on failure (duplicate connection)
 123  */
 124 int
 125 GCT_add_inbound_connection (struct CadetTunnel *t,
 126                             const struct
 127                             GNUNET_CADET_ConnectionTunnelIdentifier *cid,
 128                             struct CadetPeerPath *path);
 129
 130
 131 /**
 132  * We lost a connection, remove it from our list and clean up
 133  * the connection object itself.
 134  *
 135  * @param ct binding of connection to tunnel of the connection that was lost.
 136  */
 137 void
 138 GCT_connection_lost (struct CadetTConnection *ct);
 139
 140
 141 /**
 142  * Return the peer to which this tunnel goes.
 143  *
 144  * @param t a tunnel
 145  * @return the destination of the tunnel
 146  */
 147 struct CadetPeer *
 148 GCT_get_destination (struct CadetTunnel *t);
 149
 150
 151 /**
 152  * Consider using the path @a p for the tunnel @a t.
 153  * The tunnel destination is at offset @a off in path @a p.
 154  *
 155  * @param cls our tunnel
 156  * @param path a path to our destination
 157  * @param off offset of the destination on path @a path
 158  */
 159 void
 160 GCT_consider_path (struct CadetTunnel *t,
 161                    struct CadetPeerPath *p,
 162                    unsigned int off);
 163
 164
 165 /**
 166  * Add a channel to a tunnel.
 167  *
 168  * @param t Tunnel.
 169  * @param ch Channel
 170  * @return unique number identifying @a ch within @a t
 171  */
 172 struct GNUNET_CADET_ChannelTunnelNumber
 173 GCT_add_channel (struct CadetTunnel *t,
 174                  struct CadetChannel *ch);
 175
 176
 177 /**
 178  * Remove a channel from a tunnel.
 179  *
 180  * @param t Tunnel.
 181  * @param ch Channel
 182  * @param ctn unique number identifying @a ch within @a t
 183  */
 184 void
 185 GCT_remove_channel (struct CadetTunnel *t,
 186                     struct CadetChannel *ch,
 187                     struct GNUNET_CADET_ChannelTunnelNumber ctn);
 188
 189
 190 /**
 191  * Send a DESTROY message via the tunnel.
 192  *
 193  * @param t the tunnel to transmit over
 194  * @param ctn ID of the channel to destroy
 195  */
 196 void
 197 GCT_send_channel_destroy (struct CadetTunnel *t,
 198                           struct GNUNET_CADET_ChannelTunnelNumber ctn);
 199
 200
 201 /**
 202  * Function called when a transmission requested using #GCT_send is done.
 203  *
 204  * @param cls closure
 205  * @param ctn identifier of the connection used for transmission, NULL if
 206  *            the transmission failed (to be used to match ACKs to the
 207  *            respective connection for connection performance evaluation)
 208  */
 209 typedef void
 210 (*GCT_SendContinuation)(void *cls,
 211                         const struct
 212                         GNUNET_CADET_ConnectionTunnelIdentifier *cid);
 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.
 224  */
 225 struct CadetTunnelQueueEntry *
 226 GCT_send (struct CadetTunnel *t,
 227           const struct GNUNET_MessageHeader *message,
 228           GCT_SendContinuation 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 (const struct CadetTunnel *t);
 263
 264
 265 /**
 266  * Iterator over connections.
 267  *
 268  * @param cls closure
 269  * @param ct one of the connections
 270  */
 271 typedef void
 272 (*GCT_ConnectionIterator) (void *cls,
 273                            struct CadetTConnection *ct);
 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 encryption state of a tunnel.
 315  *
 316  * @param t Tunnel.
 317  *
 318  * @return Tunnel's encryption state.
 319  */
 320 enum CadetTunnelEState
 321 GCT_get_estate (struct CadetTunnel *t);
 322
 323
 324 /**
 325  * Handle KX message.
 326  *
 327  * @param ct connection/tunnel combo that received encrypted message
 328  * @param msg the key exchange message
 329  */
 330 void
 331 GCT_handle_kx (struct CadetTConnection *ct,
 332                const struct GNUNET_CADET_TunnelKeyExchangeMessage *msg);
 333
 334
 335 /**
 336  * Handle KX_AUTH 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_auth (struct CadetTConnection *ct,
 343                     const struct
 344                     GNUNET_CADET_TunnelKeyExchangeAuthMessage *msg);
 345
 346
 347 /**
 348  * Handle encrypted message.
 349  *
 350  * @param ct connection/tunnel combo that received encrypted message
 351  * @param msg the encrypted message to decrypt
 352  */
 353 void
 354 GCT_handle_encrypted (struct CadetTConnection *ct,
 355                       const struct GNUNET_CADET_TunnelEncryptedMessage *msg);
 356
 357
 358 /**
 359  * Log all possible info about the tunnel state.
 360  *
 361  * @param t Tunnel to debug.
 362  * @param level Debug level to use.
 363  */
 364 void
 365 GCT_debug (const struct CadetTunnel *t,
 366            enum GNUNET_ErrorType level);
 367
 368
 369 #endif