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_ConnectionCreateMessage *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_ConnectionCreateAckMessage *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_ConnectionBrokenMessage *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_ConnectionDestroyMessage *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_ConnectionEncryptedAckMessage *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_ConnectionHopByHopPollMessage *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_TunnelKeyExchangeMessage *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_TunnelEncryptedMessage *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_ConnectionTunnelIdentifier *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_ConnectionTunnelIdentifier *
 304 GCC_get_id (const struct CadetConnection *c);
 305
 306
 307 /**
 308  * Get the connection path.
 309  *
 310  * @param c Connection to get the path from.
 311  *
 312  * @return path used by the connection.
 313  */
 314 const struct CadetPeerPath *
 315 GCC_get_path (const struct CadetConnection *c);
 316
 317 /**
 318  * Get the connection state.
 319  *
 320  * @param c Connection to get the state from.
 321  *
 322  * @return state of the connection.
 323  */
 324 enum CadetConnectionState
 325 GCC_get_state (const struct CadetConnection *c);
 326
 327 /**
 328  * Get the connection tunnel.
 329  *
 330  * @param c Connection to get the tunnel from.
 331  *
 332  * @return tunnel of the connection.
 333  */
 334 struct CadetTunnel *
 335 GCC_get_tunnel (const struct CadetConnection *c);
 336
 337 /**
 338  * Get free buffer space in a connection.
 339  *
 340  * @param c Connection.
 341  * @param fwd Is query about FWD traffic?
 342  *
 343  * @return Free buffer space [0 - max_msgs_queue/max_connections]
 344  */
 345 unsigned int
 346 GCC_get_buffer (struct CadetConnection *c, int fwd);
 347
 348 /**
 349  * Get how many messages have we allowed to send to us from a direction.
 350  *
 351  * @param c Connection.
 352  * @param fwd Are we asking about traffic from FWD (BCK messages)?
 353  *
 354  * @return last_ack_sent - last_pid_recv
 355  */
 356 unsigned int
 357 GCC_get_allowed (struct CadetConnection *c, int fwd);
 358
 359 /**
 360  * Get messages queued in a connection.
 361  *
 362  * @param c Connection.
 363  * @param fwd Is query about FWD traffic?
 364  *
 365  * @return Number of messages queued.
 366  */
 367 unsigned int
 368 GCC_get_qn (struct CadetConnection *c, int fwd);
 369
 370 /**
 371  * Get next PID to use.
 372  *
 373  * @param c Connection.
 374  * @param fwd Is query about FWD traffic?
 375  * @return Next PID to use.
 376  */
 377 struct CadetEncryptedMessageIdentifier
 378 GCC_get_pid (struct CadetConnection *c, int fwd);
 379
 380 /**
 381  * Allow the connection to advertise a buffer of the given size.
 382  *
 383  * The connection will send an @c fwd ACK message (so: in direction !fwd)
 384  * allowing up to last_pid_recv + buffer.
 385  *
 386  * @param c Connection.
 387  * @param buffer How many more messages the connection can accept.
 388  * @param fwd Is this about FWD traffic? (The ack will go dest->root).
 389  */
 390 void
 391 GCC_allow (struct CadetConnection *c, unsigned int buffer, int fwd);
 392
 393 /**
 394  * Send FWD keepalive packets for a connection.
 395  *
 396  * @param cls Closure (connection for which to send the keepalive).
 397  * @param tc Notification context.
 398  */
 399 void
 400 GCC_fwd_keepalive (void *cls, const struct GNUNET_SCHEDULER_TaskContext *tc);
 401
 402 /**
 403  * Send BCK keepalive packets for a connection.
 404  *
 405  * @param cls Closure (connection for which to send the keepalive).
 406  * @param tc Notification context.
 407  */
 408 void
 409 GCC_bck_keepalive (void *cls, const struct GNUNET_SCHEDULER_TaskContext *tc);
 410
 411
 412 /**
 413  * Notify other peers on a connection of a broken link. Mark connections
 414  * to destroy after all traffic has been sent.
 415  *
 416  * @param c Connection on which there has been a disconnection.
 417  * @param peer Peer that disconnected.
 418  */
 419 void
 420 GCC_neighbor_disconnected (struct CadetConnection *c, struct CadetPeer *peer);
 421
 422 /**
 423  * Is this peer the first one on the connection?
 424  *
 425  * @param c Connection.
 426  * @param fwd Is this about fwd traffic?
 427  *
 428  * @return #GNUNET_YES if origin, #GNUNET_NO if relay/terminal.
 429  */
 430 int
 431 GCC_is_origin (struct CadetConnection *c, int fwd);
 432
 433 /**
 434  * Is this peer the last one on the connection?
 435  *
 436  * @param c Connection.
 437  * @param fwd Is this about fwd traffic?
 438  *            Note that the ROOT is the terminal for BCK traffic!
 439  *
 440  * @return #GNUNET_YES if terminal, #GNUNET_NO if relay/origin.
 441  */
 442 int
 443 GCC_is_terminal (struct CadetConnection *c, int fwd);
 444
 445 /**
 446  * See if we are allowed to send by the next hop in the given direction.
 447  *
 448  * @param c Connection.
 449  * @param fwd Is this about fwd traffic?
 450  *
 451  * @return #GNUNET_YES in case it's OK to send.
 452  */
 453 int
 454 GCC_is_sendable (struct CadetConnection *c, int fwd);
 455
 456 /**
 457  * Check if this connection is a direct one (never trim a direct connection).
 458  *
 459  * @param c Connection.
 460  *
 461  * @return #GNUNET_YES in case it's a direct connection, #GNUNET_NO otherwise.
 462  */
 463 int
 464 GCC_is_direct (struct CadetConnection *c);
 465
 466 /**
 467  * Cancel a previously sent message while it's in the queue.
 468  *
 469  * ONLY can be called before the continuation given to the send function
 470  * is called. Once the continuation is called, the message is no longer in the
 471  * queue.
 472  *
 473  * @param q Handle to the queue.
 474  */
 475 void
 476 GCC_cancel (struct CadetConnectionQueue *q);
 477
 478 /**
 479  * Sends an already built message on a connection, properly registering
 480  * all used resources.
 481  *
 482  * @param message Message to send.
 483  * @param payload_type Type of payload, in case the message is encrypted.
 484  *                     0 for restransmissions (when type is no longer known)
 485  *                     UINT16_MAX when not applicable.
 486  * @param payload_id ID of the payload (PID, ACK, ...).
 487  * @param c Connection on which this message is transmitted.
 488  * @param fwd Is this a fwd message?
 489  * @param force Force the connection to accept the message (buffer overfill).
 490  * @param cont Continuation called once message is sent. Can be NULL.
 491  * @param cont_cls Closure for @c cont.
 492  *
 493  * @return Handle to cancel the message before it's sent.
 494  *         NULL on error.
 495  *         Invalid on @c cont call.
 496  */
 497 struct CadetConnectionQueue *
 498 GCC_send_prebuilt_message (const struct GNUNET_MessageHeader *message,
 499                            uint16_t payload_type,
 500                            struct CadetEncryptedMessageIdentifier payload_id,
 501                            struct CadetConnection *c, int fwd, int force,
 502                            GCC_sent cont, void *cont_cls);
 503
 504 /**
 505  * Sends a CREATE CONNECTION message for a path to a peer.
 506  * Changes the connection and tunnel states if necessary.
 507  *
 508  * @param connection Connection to create.
 509  */
 510 void
 511 GCC_send_create (struct CadetConnection *connection);
 512
 513 /**
 514  * Send a message to all peers in this connection that the connection
 515  * is no longer valid.
 516  *
 517  * If some peer should not receive the message, it should be zero'ed out
 518  * before calling this function.
 519  *
 520  * @param c The connection whose peers to notify.
 521  */
 522 void
 523 GCC_send_destroy (struct CadetConnection *c);
 524
 525 /**
 526  * @brief Start a polling timer for the connection.
 527  *
 528  * When a neighbor does not accept more traffic on the connection it could be
 529  * caused by a simple congestion or by a lost ACK. Polling enables to check
 530  * for the lastest ACK status for a connection.
 531  *
 532  * @param c Connection.
 533  * @param fwd Should we poll in the FWD direction?
 534  */
 535 void
 536 GCC_start_poll (struct CadetConnection *c, int fwd);
 537
 538
 539 /**
 540  * @brief Stop polling a connection for ACKs.
 541  *
 542  * Once we have enough ACKs for future traffic, polls are no longer necessary.
 543  *
 544  * @param c Connection.
 545  * @param fwd Should we stop the poll in the FWD direction?
 546  */
 547 void
 548 GCC_stop_poll (struct CadetConnection *c, int fwd);
 549
 550 /**
 551  * Get a (static) string for a connection.
 552  *
 553  * @param c Connection.
 554  */
 555 const char *
 556 GCC_2s (const struct CadetConnection *c);
 557
 558 /**
 559  * Log all possible info about the connection state.
 560  *
 561  * @param c Connection to debug.
 562  * @param level Debug level to use.
 563  */
 564 void
 565 GCC_debug (const struct CadetConnection *c, enum GNUNET_ErrorType level);
 566
 567 #if 0                           /* keep Emacsens' auto-indent happy */
 568 {
 569 #endif
 570 #ifdef __cplusplus
 571 }
 572 #endif
 573
 574 /* ifndef GNUNET_SERVICE_CADET_CONNECTION_H */
 575 #endif
 576 /* end of gnunet-service-cadet_connection.h */