src/cadet/gnunet-service-cadet_connection.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_connection.h
  23  * @brief cadet service; dealing with connections
  24  * @author Bartlomiej Polot
  25  *
  26  * All functions in this file use the prefix GCC (GNUnet Cadet Connection)
  27  */
  28
  29 #ifndef GNUNET_SERVICE_CADET_CONNECTION_H
  30 #define GNUNET_SERVICE_CADET_CONNECTION_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 "gnunet_util_lib.h"
  41
  42
  43 /**
  44  * All the states a connection can be in.
  45  */
  46 enum CadetConnectionState
  47 {
  48   /**
  49    * Uninitialized status, should never appear in operation.
  50    */
  51   CADET_CONNECTION_NEW,
  52
  53   /**
  54    * Connection create message sent, waiting for ACK.
  55    */
  56   CADET_CONNECTION_SENT,
  57
  58   /**
  59    * Connection ACK sent, waiting for ACK.
  60    */
  61   CADET_CONNECTION_ACK,
  62
  63   /**
  64    * Connection confirmed, ready to carry traffic.
  65    */
  66   CADET_CONNECTION_READY,
  67
  68   /**
  69    * Connection to be destroyed, just waiting to empty queues.
  70    */
  71   CADET_CONNECTION_DESTROYED,
  72
  73   /**
  74    * Connection to be destroyed because of a distant peer, same as DESTROYED.
  75    */
  76   CADET_CONNECTION_BROKEN,
  77 };
  78
  79
  80 /**
  81  * Struct containing all information regarding a connection to a peer.
  82  */
  83 struct CadetConnection;
  84
  85 /**
  86  * Handle for messages queued but not yet sent.
  87  */
  88 struct CadetConnectionQueue;
  89
  90 #include "cadet_path.h"
  91 #include "gnunet-service-cadet_channel.h"
  92 #include "gnunet-service-cadet_peer.h"
  93
  94
  95 /**
  96  * Check invariants for all connections using #check_neighbours().
  97  */
  98 void
  99 GCC_check_connections (void);
 100
 101
 102 /**
 103  * Callback called when a queued message is sent.
 104  *
 105  * @param cls Closure.
 106  * @param c Connection this message was on.
 107  * @param type Type of message sent.
 108  * @param fwd Was this a FWD going message?
 109  * @param size Size of the message.
 110  */
 111 typedef void
 112 (*GCC_sent) (void *cls,
 113              struct CadetConnection *c,
 114              struct CadetConnectionQueue *q,
 115              uint16_t type,
 116              int fwd,
 117              size_t size);
 118
 119
 120 /**
 121  * Handler for connection creation.
 122  *
 123  * @param peer Message sender (neighbor).
 124  * @param msg Message itself.
 125  */
 126 void
 127 GCC_handle_create (struct CadetPeer *peer,
 128                    const struct GNUNET_CADET_ConnectionCreate *msg);
 129
 130
 131 /**
 132  * Handler for connection confirmations.
 133  *
 134  * @param peer Message sender (neighbor).
 135  * @param msg Message itself.
 136  */
 137 void
 138 GCC_handle_confirm (struct CadetPeer *peer,
 139                     const struct GNUNET_CADET_ConnectionACK *msg);
 140
 141
 142 /**
 143  * Handler for notifications of broken connections.
 144  *
 145  * @param peer Message sender (neighbor).
 146  * @param msg Message itself.
 147  */
 148 void
 149 GCC_handle_broken (struct CadetPeer *peer,
 150                    const struct GNUNET_CADET_ConnectionBroken *msg);
 151
 152 /**
 153  * Handler for notifications of destroyed connections.
 154  *
 155  * @param peer Message sender (neighbor).
 156  * @param msg Message itself.
 157  */
 158 void
 159 GCC_handle_destroy (struct CadetPeer *peer,
 160                     const struct GNUNET_CADET_ConnectionDestroy *msg);
 161
 162 /**
 163  * Handler for cadet network traffic hop-by-hop acks.
 164  *
 165  * @param peer Message sender (neighbor).
 166  * @param msg Message itself.
 167  */
 168 void
 169 GCC_handle_ack (struct CadetPeer *peer,
 170                 const struct GNUNET_CADET_ACK *msg);
 171
 172 /**
 173  * Handler for cadet network traffic hop-by-hop data counter polls.
 174  *
 175  * @param peer Message sender (neighbor).
 176  * @param msg Message itself.
 177  */
 178 void
 179 GCC_handle_poll (struct CadetPeer *peer,
 180                  const struct GNUNET_CADET_Poll *msg);
 181
 182 /**
 183  * Handler for key exchange traffic (Axolotl KX).
 184  *
 185  * @param peer Message sender (neighbor).
 186  * @param msg Message itself.
 187  */
 188 void
 189 GCC_handle_kx (struct CadetPeer *peer,
 190                const struct GNUNET_CADET_KX *msg);
 191
 192 /**
 193  * Handler for encrypted cadet network traffic (channel mgmt, data).
 194  *
 195  * @param peer Message sender (neighbor).
 196  * @param msg Message itself.
 197  */
 198 void
 199 GCC_handle_encrypted (struct CadetPeer *peer,
 200                       const struct GNUNET_CADET_Encrypted *msg);
 201
 202 /**
 203  * Core handler for axolotl key exchange traffic.
 204  *
 205  * @param cls Closure (unused).
 206  * @param message Message received.
 207  * @param peer Neighbor who sent the message.
 208  *
 209  * @return GNUNET_OK, to keep the connection open.
 210  */
 211 int
 212 GCC_handle_ax_kx (void *cls, const struct GNUNET_PeerIdentity *peer,
 213                   const struct GNUNET_MessageHeader *message);
 214
 215 /**
 216  * Core handler for axolotl encrypted cadet network traffic.
 217  *
 218  * @param cls Closure (unused).
 219  * @param message Message received.
 220  * @param peer Neighbor who sent the message.
 221  *
 222  * @return GNUNET_OK, to keep the connection open.
 223  */
 224 int
 225 GCC_handle_ax (void *cls, const struct GNUNET_PeerIdentity *peer,
 226                struct GNUNET_MessageHeader *message);
 227
 228 /**
 229  * Core handler for cadet keepalives.
 230  *
 231  * @param cls closure
 232  * @param message message
 233  * @param peer peer identity this notification is about
 234  * @return GNUNET_OK to keep the connection open,
 235  *         GNUNET_SYSERR to close it (signal serious error)
 236  *
 237  * TODO: Check who we got this from, to validate route.
 238  */
 239 int
 240 GCC_handle_keepalive (void *cls, const struct GNUNET_PeerIdentity *peer,
 241                       const struct GNUNET_MessageHeader *message);
 242
 243 /**
 244  * Send an ACK on the appropriate connection/channel, depending on
 245  * the direction and the position of the peer.
 246  *
 247  * @param c Which connection to send the hop-by-hop ACK.
 248  * @param fwd Is this a fwd ACK? (will go dest->root).
 249  * @param force Send the ACK even if suboptimal (e.g. requested by POLL).
 250  */
 251 void
 252 GCC_send_ack (struct CadetConnection *c, int fwd, int force);
 253
 254 /**
 255  * Initialize the connections subsystem
 256  *
 257  * @param c Configuration handle.
 258  */
 259 void
 260 GCC_init (const struct GNUNET_CONFIGURATION_Handle *c);
 261
 262 /**
 263  * Shut down the connections subsystem.
 264  */
 265 void
 266 GCC_shutdown (void);
 267
 268 /**
 269  * Create a connection.
 270  *
 271  * @param cid Connection ID (either created locally or imposed remotely).
 272  * @param t Tunnel this connection belongs to (or NULL for transit connections);
 273  * @param path Path this connection has to use (copy is made).
 274  * @param own_pos Own position in the @c path path.
 275  *
 276  * @return Newly created connection.
 277  *         NULL in case of error: own id not in path, wrong neighbors, ...
 278  */
 279 struct CadetConnection *
 280 GCC_new (const struct GNUNET_CADET_Hash *cid,
 281          struct CadetTunnel *t,
 282          struct CadetPeerPath *path,
 283          unsigned int own_pos);
 284
 285 /**
 286  * Connection is no longer needed: destroy it.
 287  *
 288  * Cancels all pending traffic (including possible DESTROY messages), all
 289  * maintenance tasks and removes the connection from neighbor peers and tunnel.
 290  *
 291  * @param c Connection to destroy.
 292  */
 293 void
 294 GCC_destroy (struct CadetConnection *c);
 295
 296 /**
 297  * Get the connection ID.
 298  *
 299  * @param c Connection to get the ID from.
 300  *
 301  * @return ID of the connection.
 302  */
 303 const struct GNUNET_CADET_Hash *
 304 GCC_get_id (const struct CadetConnection *c);
 305
 306
 307 /**
 308  * Get a hash for the connection ID.
 309  *
 310  * @param c Connection to get the hash.
 311  *
 312  * @return Hash expanded from the ID of the connection.
 313  */
 314 const struct GNUNET_HashCode *
 315 GCC_get_h (const struct CadetConnection *c);
 316
 317
 318 /**
 319  * Get the connection path.
 320  *
 321  * @param c Connection to get the path from.
 322  *
 323  * @return path used by the connection.
 324  */
 325 const struct CadetPeerPath *
 326 GCC_get_path (const struct CadetConnection *c);
 327
 328 /**
 329  * Get the connection state.
 330  *
 331  * @param c Connection to get the state from.
 332  *
 333  * @return state of the connection.
 334  */
 335 enum CadetConnectionState
 336 GCC_get_state (const struct CadetConnection *c);
 337
 338 /**
 339  * Get the connection tunnel.
 340  *
 341  * @param c Connection to get the tunnel from.
 342  *
 343  * @return tunnel of the connection.
 344  */
 345 struct CadetTunnel *
 346 GCC_get_tunnel (const struct CadetConnection *c);
 347
 348 /**
 349  * Get free buffer space in a connection.
 350  *
 351  * @param c Connection.
 352  * @param fwd Is query about FWD traffic?
 353  *
 354  * @return Free buffer space [0 - max_msgs_queue/max_connections]
 355  */
 356 unsigned int
 357 GCC_get_buffer (struct CadetConnection *c, int fwd);
 358
 359 /**
 360  * Get how many messages have we allowed to send to us from a direction.
 361  *
 362  * @param c Connection.
 363  * @param fwd Are we asking about traffic from FWD (BCK messages)?
 364  *
 365  * @return last_ack_sent - last_pid_recv
 366  */
 367 unsigned int
 368 GCC_get_allowed (struct CadetConnection *c, int fwd);
 369
 370 /**
 371  * Get messages queued in a connection.
 372  *
 373  * @param c Connection.
 374  * @param fwd Is query about FWD traffic?
 375  *
 376  * @return Number of messages queued.
 377  */
 378 unsigned int
 379 GCC_get_qn (struct CadetConnection *c, int fwd);
 380
 381 /**
 382  * Get next PID to use.
 383  *
 384  * @param c Connection.
 385  * @param fwd Is query about FWD traffic?
 386  *
 387  * @return Next PID to use.
 388  */
 389 uint32_t
 390 GCC_get_pid (struct CadetConnection *c, int fwd);
 391
 392 /**
 393  * Allow the connection to advertise a buffer of the given size.
 394  *
 395  * The connection will send an @c fwd ACK message (so: in direction !fwd)
 396  * allowing up to last_pid_recv + buffer.
 397  *
 398  * @param c Connection.
 399  * @param buffer How many more messages the connection can accept.
 400  * @param fwd Is this about FWD traffic? (The ack will go dest->root).
 401  */
 402 void
 403 GCC_allow (struct CadetConnection *c, unsigned int buffer, int fwd);
 404
 405 /**
 406  * Send FWD keepalive packets for a connection.
 407  *
 408  * @param cls Closure (connection for which to send the keepalive).
 409  * @param tc Notification context.
 410  */
 411 void
 412 GCC_fwd_keepalive (void *cls, const struct GNUNET_SCHEDULER_TaskContext *tc);
 413
 414 /**
 415  * Send BCK keepalive packets for a connection.
 416  *
 417  * @param cls Closure (connection for which to send the keepalive).
 418  * @param tc Notification context.
 419  */
 420 void
 421 GCC_bck_keepalive (void *cls, const struct GNUNET_SCHEDULER_TaskContext *tc);
 422
 423
 424 /**
 425  * Notify other peers on a connection of a broken link. Mark connections
 426  * to destroy after all traffic has been sent.
 427  *
 428  * @param c Connection on which there has been a disconnection.
 429  * @param peer Peer that disconnected.
 430  */
 431 void
 432 GCC_neighbor_disconnected (struct CadetConnection *c, struct CadetPeer *peer);
 433
 434 /**
 435  * Is this peer the first one on the connection?
 436  *
 437  * @param c Connection.
 438  * @param fwd Is this about fwd traffic?
 439  *
 440  * @return #GNUNET_YES if origin, #GNUNET_NO if relay/terminal.
 441  */
 442 int
 443 GCC_is_origin (struct CadetConnection *c, int fwd);
 444
 445 /**
 446  * Is this peer the last one on the connection?
 447  *
 448  * @param c Connection.
 449  * @param fwd Is this about fwd traffic?
 450  *            Note that the ROOT is the terminal for BCK traffic!
 451  *
 452  * @return #GNUNET_YES if terminal, #GNUNET_NO if relay/origin.
 453  */
 454 int
 455 GCC_is_terminal (struct CadetConnection *c, int fwd);
 456
 457 /**
 458  * See if we are allowed to send by the next hop in the given direction.
 459  *
 460  * @param c Connection.
 461  * @param fwd Is this about fwd traffic?
 462  *
 463  * @return #GNUNET_YES in case it's OK to send.
 464  */
 465 int
 466 GCC_is_sendable (struct CadetConnection *c, int fwd);
 467
 468 /**
 469  * Check if this connection is a direct one (never trim a direct connection).
 470  *
 471  * @param c Connection.
 472  *
 473  * @return #GNUNET_YES in case it's a direct connection, #GNUNET_NO otherwise.
 474  */
 475 int
 476 GCC_is_direct (struct CadetConnection *c);
 477
 478 /**
 479  * Cancel a previously sent message while it's in the queue.
 480  *
 481  * ONLY can be called before the continuation given to the send function
 482  * is called. Once the continuation is called, the message is no longer in the
 483  * queue.
 484  *
 485  * @param q Handle to the queue.
 486  */
 487 void
 488 GCC_cancel (struct CadetConnectionQueue *q);
 489
 490 /**
 491  * Sends an already built message on a connection, properly registering
 492  * all used resources.
 493  *
 494  * @param message Message to send.
 495  * @param payload_type Type of payload, in case the message is encrypted.
 496  * @param payload_id ID of the payload (PID, ACK, ...).
 497  * @param c Connection on which this message is transmitted.
 498  * @param fwd Is this a fwd message?
 499  * @param force Force the connection to accept the message (buffer overfill).
 500  * @param cont Continuation called once message is sent. Can be NULL.
 501  * @param cont_cls Closure for @c cont.
 502  *
 503  * @return Handle to cancel the message before it's sent.
 504  *         NULL on error or if @c cont is NULL.
 505  *         Invalid on @c cont call.
 506  */
 507 struct CadetConnectionQueue *
 508 GCC_send_prebuilt_message (const struct GNUNET_MessageHeader *message,
 509                            uint16_t payload_type, uint32_t payload_id,
 510                            struct CadetConnection *c, int fwd, int force,
 511                            GCC_sent cont, void *cont_cls);
 512
 513 /**
 514  * Sends a CREATE CONNECTION message for a path to a peer.
 515  * Changes the connection and tunnel states if necessary.
 516  *
 517  * @param connection Connection to create.
 518  */
 519 void
 520 GCC_send_create (struct CadetConnection *connection);
 521
 522 /**
 523  * Send a message to all peers in this connection that the connection
 524  * is no longer valid.
 525  *
 526  * If some peer should not receive the message, it should be zero'ed out
 527  * before calling this function.
 528  *
 529  * @param c The connection whose peers to notify.
 530  */
 531 void
 532 GCC_send_destroy (struct CadetConnection *c);
 533
 534 /**
 535  * @brief Start a polling timer for the connection.
 536  *
 537  * When a neighbor does not accept more traffic on the connection it could be
 538  * caused by a simple congestion or by a lost ACK. Polling enables to check
 539  * for the lastest ACK status for a connection.
 540  *
 541  * @param c Connection.
 542  * @param fwd Should we poll in the FWD direction?
 543  */
 544 void
 545 GCC_start_poll (struct CadetConnection *c, int fwd);
 546
 547
 548 /**
 549  * @brief Stop polling a connection for ACKs.
 550  *
 551  * Once we have enough ACKs for future traffic, polls are no longer necessary.
 552  *
 553  * @param c Connection.
 554  * @param fwd Should we stop the poll in the FWD direction?
 555  */
 556 void
 557 GCC_stop_poll (struct CadetConnection *c, int fwd);
 558
 559 /**
 560  * Get a (static) string for a connection.
 561  *
 562  * @param c Connection.
 563  */
 564 const char *
 565 GCC_2s (const struct CadetConnection *c);
 566
 567 /**
 568  * Log all possible info about the connection state.
 569  *
 570  * @param c Connection to debug.
 571  * @param level Debug level to use.
 572  */
 573 void
 574 GCC_debug (const struct CadetConnection *c, enum GNUNET_ErrorType level);
 575
 576 #if 0                           /* keep Emacsens' auto-indent happy */
 577 {
 578 #endif
 579 #ifdef __cplusplus
 580 }
 581 #endif
 582
 583 /* ifndef GNUNET_SERVICE_CADET_CONNECTION_H */
 584 #endif
 585 /* end of gnunet-service-cadet_connection.h */