src/cadet/gnunet-service-cadet_tunnel.h

   1 /*
   2      This file is part of GNUnet.
   3      Copyright (C) 2013 GNUnet e.V.
   4
   5      GNUnet is free software; you can redistribute it and/or modify
   6      it under the terms of the GNU General Public License as published
   7      by the Free Software Foundation; either version 3, or (at your
   8      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      General Public License for more details.
  14
  15      You should have received a copy of the GNU General Public License
  16      along with GNUnet; see the file COPYING.  If not, write to the
  17      Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  18      Boston, MA 02110-1301, USA.
  19 */
  20
  21 /**
  22  * @file cadet/gnunet-service-cadet_tunnel.h
  23  * @brief cadet service; dealing with tunnels and crypto
  24  * @author Bartlomiej Polot
  25  *
  26  * All functions in this file should use the prefix GMT (Gnunet Cadet Tunnel)
  27  */
  28
  29 #ifndef GNUNET_SERVICE_CADET_TUNNEL_H
  30 #define GNUNET_SERVICE_CADET_TUNNEL_H
  31
  32 #ifdef __cplusplus
  33 extern "C"
  34 {
  35 #if 0                           /* keep Emacsens' auto-indent happy */
  36 }
  37 #endif
  38 #endif
  39
  40 #include "platform.h"
  41 #include "gnunet_util_lib.h"
  42
  43 #define CONNECTIONS_PER_TUNNEL 3
  44
  45 /**
  46  * All the connectivity states a tunnel can be in.
  47  */
  48 enum CadetTunnelCState
  49 {
  50   /**
  51    * Uninitialized status, should never appear in operation.
  52    */
  53   CADET_TUNNEL_NEW,
  54
  55   /**
  56    * No path to the peer known yet.
  57    */
  58   CADET_TUNNEL_SEARCHING,
  59
  60   /**
  61    * Request sent, not yet answered.
  62    */
  63   CADET_TUNNEL_WAITING,
  64
  65   /**
  66    * Peer connected and ready to accept data.
  67    */
  68   CADET_TUNNEL_READY,
  69
  70   /**
  71    * Tunnel being shut down, don't try to keep it alive.
  72    */
  73   CADET_TUNNEL_SHUTDOWN
  74 };
  75
  76
  77 /**
  78  * All the encryption states a tunnel can be in.
  79  */
  80 enum CadetTunnelEState
  81 {
  82   /**
  83    * Uninitialized status, should never appear in operation.
  84    */
  85   CADET_TUNNEL_KEY_UNINITIALIZED,
  86
  87   /**
  88    * Ephemeral key sent, waiting for peer's key.
  89    */
  90   CADET_TUNNEL_KEY_SENT,
  91
  92   /**
  93    * In OTR: New ephemeral key and ping sent, waiting for pong.
  94    *
  95    * This means that we DO have the peer's ephemeral key, otherwise the
  96    * state would be KEY_SENT. We DO NOT have a valid session key (either no
  97    * previous key or previous key expired).
  98    *
  99    *
 100    * In Axolotl: Key sent and received but no deciphered traffic yet.
 101    *
 102    * This means that we can send traffic (otherwise we would never complete
 103    * the handshake), but we don't have complete confirmation. Since the first
 104    * traffic MUST be a complete channel creation 3-way handshake, no payload
 105    * will be sent before confirmation.
 106    */
 107   CADET_TUNNEL_KEY_PING,
 108
 109   /**
 110    * Handshake completed: session key available.
 111    */
 112   CADET_TUNNEL_KEY_OK,
 113
 114   /**
 115    * New ephemeral key and ping sent, waiting for pong. Unlike KEY_PING,
 116    * we still have a valid session key and therefore we *can* still send
 117    * traffic on the tunnel.
 118    */
 119   CADET_TUNNEL_KEY_REKEY
 120 };
 121
 122 /**
 123  * Struct containing all information regarding a given peer
 124  */
 125 struct CadetTunnel;
 126
 127
 128 #include "gnunet-service-cadet_channel.h"
 129 #include "gnunet-service-cadet_connection.h"
 130 #include "gnunet-service-cadet_peer.h"
 131
 132 /**
 133  * Handle for messages queued but not yet sent.
 134  */
 135 struct CadetTunnelQueue;
 136
 137 /**
 138  * Callback called when a queued message is sent.
 139  *
 140  * @param cls Closure.
 141  * @param t Tunnel this message was on.
 142  * @param type Type of message sent.
 143  * @param size Size of the message.
 144  */
 145 typedef void
 146 (*GCT_sent) (void *cls,
 147              struct CadetTunnel *t,
 148              struct CadetTunnelQueue *q,
 149              uint16_t type, size_t size);
 150
 151 typedef void
 152 (*GCT_conn_iter) (void *cls, struct CadetConnection *c);
 153
 154
 155 typedef void
 156 (*GCT_chan_iter) (void *cls, struct CadetChannel *ch);
 157
 158
 159 /******************************************************************************/
 160 /********************************    API    ***********************************/
 161 /******************************************************************************/
 162
 163 /**
 164  * Initialize tunnel subsystem.
 165  *
 166  * @param c Configuration handle.
 167  * @param key ECC private key, to derive all other keys and do crypto.
 168  */
 169 void
 170 GCT_init (const struct GNUNET_CONFIGURATION_Handle *c,
 171           const struct GNUNET_CRYPTO_EddsaPrivateKey *key);
 172
 173
 174 /**
 175  * Shut down the tunnel subsystem.
 176  */
 177 void
 178 GCT_shutdown (void);
 179
 180
 181 /**
 182  * Create a tunnel.
 183  *
 184  * @param destination Peer this tunnel is towards.
 185  */
 186 struct CadetTunnel *
 187 GCT_new (struct CadetPeer *destination);
 188
 189
 190 /**
 191  * Tunnel is empty: destroy it.
 192  *
 193  * Notifies all connections about the destruction.
 194  *
 195  * @param t Tunnel to destroy.
 196  */
 197 void
 198 GCT_destroy_empty (struct CadetTunnel *t);
 199
 200
 201 /**
 202  * Destroy tunnel if empty (no more channels).
 203  *
 204  * @param t Tunnel to destroy if empty.
 205  */
 206 void
 207 GCT_destroy_if_empty (struct CadetTunnel *t);
 208
 209
 210 /**
 211  * Destroy the tunnel.
 212  *
 213  * This function does not generate any warning traffic to clients or peers.
 214  *
 215  * Tasks:
 216  * Cancel messages belonging to this tunnel queued to neighbors.
 217  * Free any allocated resources linked to the tunnel.
 218  *
 219  * @param t The tunnel to destroy.
 220  */
 221 void
 222 GCT_destroy (struct CadetTunnel *t);
 223
 224
 225 /**
 226  * Change the tunnel's connection state.
 227  *
 228  * @param t Tunnel whose connection state to change.
 229  * @param cstate New connection state.
 230  */
 231 void
 232 GCT_change_cstate (struct CadetTunnel* t, enum CadetTunnelCState cstate);
 233
 234
 235 /**
 236  * Change the tunnel encryption state.
 237  *
 238  * @param t Tunnel whose encryption state to change.
 239  * @param state New encryption state.
 240  */
 241 void
 242 GCT_change_estate (struct CadetTunnel* t, enum CadetTunnelEState state);
 243
 244
 245 /**
 246  * Add a connection to a tunnel.
 247  *
 248  * @param t Tunnel.
 249  * @param c Connection.
 250  */
 251 void
 252 GCT_add_connection (struct CadetTunnel *t, struct CadetConnection *c);
 253
 254
 255 /**
 256  * Remove a connection from a tunnel.
 257  *
 258  * @param t Tunnel.
 259  * @param c Connection.
 260  */
 261 void
 262 GCT_remove_connection (struct CadetTunnel *t, struct CadetConnection *c);
 263
 264
 265 /**
 266  * Add a channel to a tunnel.
 267  *
 268  * @param t Tunnel.
 269  * @param ch Channel.
 270  */
 271 void
 272 GCT_add_channel (struct CadetTunnel *t, struct CadetChannel *ch);
 273
 274
 275 /**
 276  * Remove a channel from a tunnel.
 277  *
 278  * @param t Tunnel.
 279  * @param ch Channel.
 280  */
 281 void
 282 GCT_remove_channel (struct CadetTunnel *t, struct CadetChannel *ch);
 283
 284
 285 /**
 286  * Search for a channel by global ID.
 287  *
 288  * @param t Tunnel containing the channel.
 289  * @param chid Public channel number.
 290  *
 291  * @return channel handler, NULL if doesn't exist
 292  */
 293 struct CadetChannel *
 294 GCT_get_channel (struct CadetTunnel *t, CADET_ChannelNumber chid);
 295
 296
 297 /**
 298  * Decrypt and demultiplex by message type. Call appropriate handler
 299  * for a message towards a channel of a local tunnel.
 300  *
 301  * @param t Tunnel this message came on.
 302  * @param msg Message header.
 303  */
 304 void
 305 GCT_handle_encrypted (struct CadetTunnel *t,
 306                       const struct GNUNET_MessageHeader *msg);
 307
 308
 309 /**
 310  * Demultiplex an encapsulated KX message by message type.
 311  *
 312  * @param t Tunnel on which the message came.
 313  * @param message KX message itself.
 314  */
 315 void
 316 GCT_handle_kx (struct CadetTunnel *t,
 317                const struct GNUNET_MessageHeader *message);
 318
 319
 320 /**
 321  * @brief Use the given path for the tunnel.
 322  * Update the next and prev hops (and RCs).
 323  * (Re)start the path refresh in case the tunnel is locally owned.
 324  *
 325  * @param t Tunnel to update.
 326  * @param p Path to use.
 327  *
 328  * @return Connection created.
 329  */
 330 struct CadetConnection *
 331 GCT_use_path (struct CadetTunnel *t, struct CadetPeerPath *p);
 332
 333
 334 /**
 335  * Count all created connections of a tunnel. Not necessarily ready connections!
 336  *
 337  * @param t Tunnel on which to count.
 338  *
 339  * @return Number of connections created, either being established or ready.
 340  */
 341 unsigned int
 342 GCT_count_any_connections (struct CadetTunnel *t);
 343
 344
 345 /**
 346  * Count established (ready) connections of a tunnel.
 347  *
 348  * @param t Tunnel on which to count.
 349  *
 350  * @return Number of connections.
 351  */
 352 unsigned int
 353 GCT_count_connections (struct CadetTunnel *t);
 354
 355
 356 /**
 357  * Count channels of a tunnel.
 358  *
 359  * @param t Tunnel on which to count.
 360  *
 361  * @return Number of channels.
 362  */
 363 unsigned int
 364 GCT_count_channels (struct CadetTunnel *t);
 365
 366
 367 /**
 368  * Get the connectivity state of a tunnel.
 369  *
 370  * @param t Tunnel.
 371  *
 372  * @return Tunnel's connectivity state.
 373  */
 374 enum CadetTunnelCState
 375 GCT_get_cstate (struct CadetTunnel *t);
 376
 377
 378 /**
 379  * Get the encryption state of a tunnel.
 380  *
 381  * @param t Tunnel.
 382  *
 383  * @return Tunnel's encryption state.
 384  */
 385 enum CadetTunnelEState
 386 GCT_get_estate (struct CadetTunnel *t);
 387
 388
 389 /**
 390  * Get the maximum buffer space for a tunnel towards a local client.
 391  *
 392  * @param t Tunnel.
 393  *
 394  * @return Biggest buffer space offered by any channel in the tunnel.
 395  */
 396 unsigned int
 397 GCT_get_channels_buffer (struct CadetTunnel *t);
 398
 399
 400 /**
 401  * Get the total buffer space for a tunnel for P2P traffic.
 402  *
 403  * @param t Tunnel.
 404  *
 405  * @return Buffer space offered by all connections in the tunnel.
 406  */
 407 unsigned int
 408 GCT_get_connections_buffer (struct CadetTunnel *t);
 409
 410
 411 /**
 412  * Get the tunnel's destination.
 413  *
 414  * @param t Tunnel.
 415  *
 416  * @return ID of the destination peer.
 417  */
 418 const struct GNUNET_PeerIdentity *
 419 GCT_get_destination (struct CadetTunnel *t);
 420
 421
 422 /**
 423  * Get the tunnel's next free Channel ID.
 424  *
 425  * @param t Tunnel.
 426  *
 427  * @return ID of a channel free to use.
 428  */
 429 CADET_ChannelNumber
 430 GCT_get_next_chid (struct CadetTunnel *t);
 431
 432
 433 /**
 434  * Send ACK on one or more channels due to buffer in connections.
 435  *
 436  * @param t Channel which has some free buffer space.
 437  */
 438 void
 439 GCT_unchoke_channels (struct CadetTunnel *t);
 440
 441
 442 /**
 443  * Send ACK on one or more connections due to buffer space to the client.
 444  *
 445  * Iterates all connections of the tunnel and sends ACKs appropriately.
 446  *
 447  * @param t Tunnel which has some free buffer space.
 448  */
 449 void
 450 GCT_send_connection_acks (struct CadetTunnel *t);
 451
 452
 453 /**
 454  * Cancel a previously sent message while it's in the queue.
 455  *
 456  * ONLY can be called before the continuation given to the send function
 457  * is called. Once the continuation is called, the message is no longer in the
 458  * queue.
 459  *
 460  * @param q Handle to the queue.
 461  */
 462 void
 463 GCT_cancel (struct CadetTunnelQueue *q);
 464
 465
 466 /**
 467  * Check if the tunnel has queued traffic.
 468  *
 469  * @param t Tunnel to check.
 470  *
 471  * @return #GNUNET_YES if there is queued traffic
 472  *         #GNUNET_NO otherwise
 473  */
 474 int
 475 GCT_has_queued_traffic (struct CadetTunnel *t);
 476
 477 /**
 478  * Sends an already built message on a tunnel, encrypting it and
 479  * choosing the best connection.
 480  *
 481  * @param message Message to send. Function modifies it.
 482  * @param t Tunnel on which this message is transmitted.
 483  * @param c Connection to use (autoselect if NULL).
 484  * @param force Force the tunnel to take the message (buffer overfill).
 485  * @param cont Continuation to call once message is really sent.
 486  * @param cont_cls Closure for @c cont.
 487  *
 488  * @return Handle to cancel message. NULL if @c cont is NULL.
 489  */
 490 struct CadetTunnelQueue *
 491 GCT_send_prebuilt_message (const struct GNUNET_MessageHeader *message,
 492                            struct CadetTunnel *t, struct CadetConnection *c,
 493                            int force, GCT_sent cont, void *cont_cls);
 494
 495
 496 /**
 497  * Send an Axolotl KX message.
 498  *
 499  * @param t Tunnel on which to send it.
 500  * @param force_reply Force the other peer to reply with a KX message.
 501  */
 502 void
 503 GCT_send_ax_kx (struct CadetTunnel *t, int force_reply);
 504
 505
 506 /**
 507  * Is the tunnel directed towards the local peer?
 508  *
 509  * @param t Tunnel.
 510  *
 511  * @return #GNUNET_YES if it is loopback.
 512  */
 513 int
 514 GCT_is_loopback (const struct CadetTunnel *t);
 515
 516
 517 /**
 518  * Is the tunnel using this path already?
 519  *
 520  * @param t Tunnel.
 521  * @param p Path.
 522  *
 523  * @return #GNUNET_YES a connection uses this path.
 524  */
 525 int
 526 GCT_is_path_used (const struct CadetTunnel *t, const struct CadetPeerPath *p);
 527
 528
 529 /**
 530  * Get a cost of a path for a tunnel considering existing connections.
 531  *
 532  * @param t Tunnel.
 533  * @param path Candidate path.
 534  *
 535  * @return Cost of the path (path length + number of overlapping nodes)
 536  */
 537 unsigned int
 538 GCT_get_path_cost (const struct CadetTunnel *t,
 539                    const struct CadetPeerPath *path);
 540
 541
 542 /**
 543  * Get the static string for the peer this tunnel is directed.
 544  *
 545  * @param t Tunnel.
 546  *
 547  * @return Static string the destination peer's ID.
 548  */
 549 const char *
 550 GCT_2s (const struct CadetTunnel *t);
 551
 552
 553 /**
 554  * Log all possible info about the tunnel state.
 555  *
 556  * @param t Tunnel to debug.
 557  * @param level Debug level to use.
 558  */
 559 void
 560 GCT_debug (const struct CadetTunnel *t, enum GNUNET_ErrorType level);
 561
 562
 563 /**
 564  * Iterate all tunnels.
 565  *
 566  * @param iter Iterator.
 567  * @param cls Closure for @c iter.
 568  */
 569 void
 570 GCT_iterate_all (GNUNET_CONTAINER_PeerMapIterator iter, void *cls);
 571
 572
 573 /**
 574  * Count all tunnels.
 575  *
 576  * @return Number of tunnels to remote peers kept by this peer.
 577  */
 578 unsigned int
 579 GCT_count_all (void);
 580
 581
 582 /**
 583  * Iterate all connections of a tunnel.
 584  *
 585  * @param t Tunnel whose connections to iterate.
 586  * @param iter Iterator.
 587  * @param cls Closure for @c iter.
 588  */
 589 void
 590 GCT_iterate_connections (struct CadetTunnel *t, GCT_conn_iter iter, void *cls);
 591
 592
 593 /**
 594  * Iterate all channels of a tunnel.
 595  *
 596  * @param t Tunnel whose channels to iterate.
 597  * @param iter Iterator.
 598  * @param cls Closure for @c iter.
 599  */
 600 void
 601 GCT_iterate_channels (struct CadetTunnel *t,
 602                       GCT_chan_iter iter,
 603                       void *cls);
 604
 605
 606 #if 0                           /* keep Emacsens' auto-indent happy */
 607 {
 608 #endif
 609 #ifdef __cplusplus
 610 }
 611 #endif
 612
 613 /* ifndef GNUNET_CADET_SERVICE_TUNNEL_H */
 614 #endif
 615 /* end of gnunet-cadet-service_tunnel.h */