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  * Am I Alice or Betty (some call her Bob), or talking to myself?
  85  *
  86  * @param other the other peer
  87  * @return #GNUNET_YES for Alice, #GNUNET_NO for Betty, #GNUNET_SYSERR if talking to myself
  88  */
  89 int
  90 GCT_alice_or_betty (const struct GNUNET_PeerIdentity *other);
  91
  92 /**
  93  * Get the static string for the peer this tunnel is directed.
  94  *
  95  * @param t Tunnel.
  96  *
  97  * @return Static string the destination peer's ID.
  98  */
  99 const char *
 100 GCT_2s (const struct CadetTunnel *t);
 101
 102
 103 /**
 104  * Create a tunnel to @a destionation.  Must only be called
 105  * from within #GCP_get_tunnel().
 106  *
 107  * @param destination where to create the tunnel to
 108  * @return new tunnel to @a destination
 109  */
 110 struct CadetTunnel *
 111 GCT_create_tunnel (struct CadetPeer *destination);
 112
 113
 114 /**
 115  * Destroys the tunnel @a t now, without delay. Used during shutdown.
 116  *
 117  * @param t tunnel to destroy
 118  */
 119 void
 120 GCT_destroy_tunnel_now (struct CadetTunnel *t);
 121
 122
 123 /**
 124  * Add a @a connection to the @a tunnel.
 125  *
 126  * @param t a tunnel
 127  * @param cid connection identifer to use for the connection
 128  * @param path path to use for the connection
 129  * @return #GNUNET_OK on success,
 130  *         #GNUNET_SYSERR on failure (duplicate connection)
 131  */
 132 int
 133 GCT_add_inbound_connection (struct CadetTunnel *t,
 134                             const struct
 135                             GNUNET_CADET_ConnectionTunnelIdentifier *cid,
 136                             struct CadetPeerPath *path);
 137
 138
 139 /**
 140  * We lost a connection, remove it from our list and clean up
 141  * the connection object itself.
 142  *
 143  * @param ct binding of connection to tunnel of the connection that was lost.
 144  */
 145 void
 146 GCT_connection_lost (struct CadetTConnection *ct);
 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 GNUNET_CADET_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 ctn unique number identifying @a ch within @a t
 191  */
 192 void
 193 GCT_remove_channel (struct CadetTunnel *t,
 194                     struct CadetChannel *ch,
 195                     struct GNUNET_CADET_ChannelTunnelNumber ctn);
 196
 197
 198 /**
 199  * Send a DESTROY message via the tunnel.
 200  *
 201  * @param t the tunnel to transmit over
 202  * @param ctn ID of the channel to destroy
 203  */
 204 void
 205 GCT_send_channel_destroy (struct CadetTunnel *t,
 206                           struct GNUNET_CADET_ChannelTunnelNumber ctn);
 207
 208
 209 /**
 210  * Function called when a transmission requested using #GCT_send is done.
 211  *
 212  * @param cls closure
 213  * @param ctn identifier of the connection used for transmission, NULL if
 214  *            the transmission failed (to be used to match ACKs to the
 215  *            respective connection for connection performance evaluation)
 216  */
 217 typedef void
 218 (*GCT_SendContinuation)(void *cls,
 219                         const struct
 220                         GNUNET_CADET_ConnectionTunnelIdentifier *cid);
 221
 222
 223 /**
 224  * Sends an already built message on a tunnel, encrypting it and
 225  * choosing the best connection if not provided.
 226  *
 227  * @param message Message to send. Function modifies it.
 228  * @param t Tunnel on which this message is transmitted.
 229  * @param cont Continuation to call once message is really sent.
 230  * @param cont_cls Closure for @c cont.
 231  * @return Handle to cancel message.
 232  */
 233 struct CadetTunnelQueueEntry *
 234 GCT_send (struct CadetTunnel *t,
 235           const struct GNUNET_MessageHeader *message,
 236           GCT_SendContinuation cont,
 237           void *cont_cls,
 238           struct GNUNET_CADET_ChannelTunnelNumber *ctn);
 239
 240
 241 /**
 242  * Cancel a previously sent message while it's in the queue.
 243  *
 244  * ONLY can be called before the continuation given to the send
 245  * function is called. Once the continuation is called, the message is
 246  * no longer in the queue!
 247  *
 248  * @param q Handle to the queue entry to cancel.
 249  */
 250 void
 251 GCT_send_cancel (struct CadetTunnelQueueEntry *q);
 252
 253
 254 /**
 255  * Return the number of channels using a tunnel.
 256  *
 257  * @param t tunnel to count obtain the number of channels for
 258  * @return number of channels using the tunnel
 259  */
 260 unsigned int
 261 GCT_count_channels (struct CadetTunnel *t);
 262
 263
 264 /**
 265  * Return the number of connections available for a tunnel.
 266  *
 267  * @param t tunnel to count obtain the number of connections for
 268  * @return number of connections available for the tunnel
 269  */
 270 unsigned int
 271 GCT_count_any_connections (const struct CadetTunnel *t);
 272
 273
 274 /**
 275  * Iterator over connections.
 276  *
 277  * @param cls closure
 278  * @param ct one of the connections
 279  */
 280 typedef void
 281 (*GCT_ConnectionIterator) (void *cls,
 282                            struct CadetTConnection *ct);
 283
 284
 285 /**
 286  * Iterate over all connections of a tunnel.
 287  *
 288  * @param t Tunnel whose connections to iterate.
 289  * @param iter Iterator.
 290  * @param iter_cls Closure for @c iter.
 291  */
 292 void
 293 GCT_iterate_connections (struct CadetTunnel *t,
 294                          GCT_ConnectionIterator iter,
 295                          void *iter_cls);
 296
 297
 298 /**
 299  * Iterator over channels.
 300  *
 301  * @param cls closure
 302  * @param ch one of the channels
 303  */
 304 typedef void
 305 (*GCT_ChannelIterator) (void *cls,
 306                         struct CadetChannel *ch);
 307
 308
 309 /**
 310  * Iterate over all channels of a tunnel.
 311  *
 312  * @param t Tunnel whose channels to iterate.
 313  * @param iter Iterator.
 314  * @param iter_cls Closure for @c iter.
 315  */
 316 void
 317 GCT_iterate_channels (struct CadetTunnel *t,
 318                       GCT_ChannelIterator iter,
 319                       void *iter_cls);
 320
 321
 322 /**
 323  * Get the encryption state of a tunnel.
 324  *
 325  * @param t Tunnel.
 326  *
 327  * @return Tunnel's encryption state.
 328  */
 329 enum CadetTunnelEState
 330 GCT_get_estate (struct CadetTunnel *t);
 331
 332 /**
 333  * Change the tunnel encryption state.
 334  * If the encryption state changes to OK, stop the rekey task.
 335  *
 336  * @param t Tunnel whose encryption state to change, or NULL.
 337  * @param state New encryption state.
 338  */
 339 void
 340 GCT_change_estate (struct CadetTunnel *t,
 341                    enum CadetTunnelEState state);
 342
 343 /**
 344  * Handle KX message.
 345  *
 346  * @param ct connection/tunnel combo that received encrypted message
 347  * @param msg the key exchange message
 348  */
 349 void
 350 GCT_handle_kx (struct CadetTConnection *ct,
 351                const struct GNUNET_CADET_TunnelKeyExchangeMessage *msg);
 352
 353
 354 /**
 355  * Handle KX_AUTH message.
 356  *
 357  * @param ct connection/tunnel combo that received encrypted message
 358  * @param msg the key exchange message
 359  */
 360 void
 361 GCT_handle_kx_auth (struct CadetTConnection *ct,
 362                     const struct
 363                     GNUNET_CADET_TunnelKeyExchangeAuthMessage *msg);
 364
 365
 366 /**
 367  * Handle encrypted message.
 368  *
 369  * @param ct connection/tunnel combo that received encrypted message
 370  * @param msg the encrypted message to decrypt
 371  */
 372 void
 373 GCT_handle_encrypted (struct CadetTConnection *ct,
 374                       const struct GNUNET_CADET_TunnelEncryptedMessage *msg);
 375
 376
 377 /**
 378  * Log all possible info about the tunnel state.
 379  *
 380  * @param t Tunnel to debug.
 381  * @param level Debug level to use.
 382  */
 383 void
 384 GCT_debug (const struct CadetTunnel *t,
 385            enum GNUNET_ErrorType level);
 386
 387
 388 #endif