src/include/gnunet_cadet_service.h

   1 /*
   2      This file is part of GNUnet.
   3      Copyright (C) 2009-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 /**
  19  * @author Christian Grothoff
  20  * @author Bart Polot
  21  *
  22  * @file
  23  * CADET service; establish channels to distant peers
  24  *
  25  * @defgroup cadet  CADET service
  26  * Confidential Ad-hoc Decentralized End-to-End Transport
  27  *
  28  * @see [Documentation](https://gnunet.org/cadet-subsystem)
  29  * @see [Paper](https://gnunet.org/cadet)
  30  *
  31  * @{
  32  */
  33 #ifndef GNUNET_CADET_SERVICE_H
  34 #define GNUNET_CADET_SERVICE_H
  35
  36 #ifdef __cplusplus
  37 extern "C"
  38 {
  39 #if 0                           /* keep Emacsens' auto-indent happy */
  40 }
  41 #endif
  42 #endif
  43
  44 #include "gnunet_util_lib.h"
  45 #include "gnunet_transport_service.h"
  46
  47 /**
  48  * Version number of GNUnet-cadet API.
  49  */
  50 #define GNUNET_CADET_VERSION 0x00000005
  51
  52
  53 /**
  54  * Opaque handle to the service.
  55  */
  56 struct GNUNET_CADET_Handle;
  57
  58 /**
  59  * Opaque handle to a channel.
  60  */
  61 struct GNUNET_CADET_Channel;
  62
  63 /**
  64  * Opaque handle to a port.
  65  */
  66 struct GNUNET_CADET_Port;
  67
  68
  69 /**
  70  * Hash uniquely identifying a connection below a tunnel.
  71  */
  72 struct GNUNET_CADET_ConnectionTunnelIdentifier
  73 {
  74   struct GNUNET_ShortHashCode connection_of_tunnel;
  75 };
  76
  77
  78 /**
  79  * Number identifying a CADET channel within a tunnel.
  80  */
  81 struct GNUNET_CADET_ChannelTunnelNumber
  82 {
  83   /**
  84    * Which number does this channel have that uniquely identfies
  85    * it within its tunnel, in network byte order.
  86    *
  87    * Given two peers, both may initiate channels over the same tunnel.
  88    * The @e cn must be greater or equal to 0x80000000 (high-bit set)
  89    * for tunnels initiated with the peer that has the larger peer
  90    * identity as compared using #GNUNET_CRYPTO_cmp_peer_identity().
  91    */
  92   uint32_t cn GNUNET_PACKED;
  93 };
  94
  95
  96 /**
  97  * Channel options.  Second line indicates filed in the
  98  * CadetChannelInfo union carrying the answer.
  99  */
 100 enum GNUNET_CADET_ChannelOption
 101 {
 102   /**
 103    * Default options: unreliable, default buffering, not out of order.
 104    */
 105   GNUNET_CADET_OPTION_DEFAULT    = 0x0,
 106
 107   /**
 108    * Disable buffering on intermediate nodes (for minimum latency).
 109    * Yes/No.
 110    */
 111   GNUNET_CADET_OPTION_NOBUFFER   = 0x1,
 112
 113   /**
 114    * Enable channel reliability, lost messages will be retransmitted.
 115    * Yes/No.
 116    */
 117   GNUNET_CADET_OPTION_RELIABLE   = 0x2,
 118
 119   /**
 120    * Enable out of order delivery of messages.
 121    * Set bit for out-of-order delivery.
 122    */
 123   GNUNET_CADET_OPTION_OUT_OF_ORDER = 0x4,
 124
 125   /**
 126    * Who is the peer at the other end of the channel.
 127    * Only for use in @c GNUNET_CADET_channel_get_info
 128    * struct GNUNET_PeerIdentity *peer
 129    */
 130   GNUNET_CADET_OPTION_PEER       = 0x8
 131
 132 };
 133
 134
 135 /**
 136  * Method called whenever a peer connects to a port in MQ-based CADET.
 137  *
 138  * @param cls Closure from #GNUNET_CADET_open_port.
 139  * @param channel New handle to the channel.
 140  * @param source Peer that started this channel.
 141  * @return Closure for the incoming @a channel. It's given to:
 142  *         - The #GNUNET_CADET_DisconnectEventHandler (given to
 143  *           #GNUNET_CADET_open_port) when the channel dies.
 144  *         - Each the #GNUNET_MQ_MessageCallback handlers for each message
 145  *           received on the @a channel.
 146  */
 147 typedef void *
 148 (*GNUNET_CADET_ConnectEventHandler) (void *cls,
 149                                      struct GNUNET_CADET_Channel *channel,
 150                                      const struct GNUNET_PeerIdentity *source);
 151
 152
 153 /**
 154  * Function called whenever an MQ-channel is destroyed, even if the destruction
 155  * was requested by #GNUNET_CADET_channel_destroy.
 156  * It must NOT call #GNUNET_CADET_channel_destroy on the channel.
 157  *
 158  * It should clean up any associated state, including cancelling any pending
 159  * transmission on this channel.
 160  *
 161  * @param cls Channel closure.
 162  * @param channel Connection to the other end (henceforth invalid).
 163  */
 164 typedef void
 165 (*GNUNET_CADET_DisconnectEventHandler) (void *cls,
 166                                         const struct GNUNET_CADET_Channel *channel);
 167
 168
 169 /**
 170  * Function called whenever an MQ-channel's transmission window size changes.
 171  *
 172  * The first callback in an outgoing channel will be with a non-zero value
 173  * and will mean the channel is connected to the destination.
 174  *
 175  * For an incoming channel it will be called immediately after the
 176  * #GNUNET_CADET_ConnectEventHandler, also with a non-zero value.
 177  *
 178  * @param cls Channel closure.
 179  * @param channel Connection to the other end --- FIXME: drop?
 180  * @param window_size New window size. If the is more messages than buffer size
 181  *                    this value will be negative. -- FIXME: make unsigned, we never call negative?
 182  */
 183 typedef void
 184 (*GNUNET_CADET_WindowSizeEventHandler) (void *cls,
 185                                         const struct GNUNET_CADET_Channel *channel,
 186                                         int window_size);
 187
 188
 189 /**
 190  * Connect to the MQ-based cadet service.
 191  *
 192  * @param cfg Configuration to use.
 193  * @return Handle to the cadet service NULL on error.
 194  */
 195 struct GNUNET_CADET_Handle *
 196 GNUNET_CADET_connect (const struct GNUNET_CONFIGURATION_Handle *cfg);
 197
 198
 199 /**
 200  * Disconnect from the cadet service. All channels will be destroyed. All channel
 201  * disconnect callbacks will be called on any still connected peers, notifying
 202  * about their disconnection. The registered inbound channel cleaner will be
 203  * called should any inbound channels still exist.
 204  *
 205  * @param handle connection to cadet to disconnect
 206  */
 207 void
 208 GNUNET_CADET_disconnect (struct GNUNET_CADET_Handle *handle);
 209
 210
 211 /**
 212  * Open a port to receive incomming MQ-based channels.
 213  *
 214  * @param h CADET handle.
 215  * @param port Hash identifying the port.
 216  * @param connects Function called when an incoming channel is connected.
 217  * @param connects_cls Closure for the @a connects handler.
 218  * @param window_changes Function called when the transmit window size changes.
 219  *                       Can be NULL.
 220  * @param disconnects Function called when a channel is disconnected.
 221  * @param handlers Callbacks for messages we care about, NULL-terminated.
 222  * @return Port handle, NULL if port is in use
 223  */
 224 struct GNUNET_CADET_Port *
 225 GNUNET_CADET_open_port (struct GNUNET_CADET_Handle *h,
 226                         const struct GNUNET_HashCode *port,
 227                         GNUNET_CADET_ConnectEventHandler connects,
 228                         void *connects_cls,
 229                         GNUNET_CADET_WindowSizeEventHandler window_changes,
 230                         GNUNET_CADET_DisconnectEventHandler disconnects,
 231                         const struct GNUNET_MQ_MessageHandler *handlers);
 232
 233
 234 /**
 235  * Close a port opened with @a GNUNET_CADET_open_port.
 236  * The @a new_channel callback will no longer be called.
 237  *
 238  * @param p Port handle.
 239  */
 240 void
 241 GNUNET_CADET_close_port (struct GNUNET_CADET_Port *p);
 242
 243
 244 /**
 245  * Create a new channel towards a remote peer.
 246  *
 247  * If the destination port is not open by any peer or the destination peer
 248  * does not accept the channel, @a disconnects will be called
 249  * for this channel.
 250  *
 251  * @param h CADET handle.
 252  * @param channel_cls Closure for the channel. It's given to:
 253  *                    - The management handler @a window_changes.
 254  *                    - The disconnect handler @a disconnects
 255  *                    - Each message type callback in @a handlers
 256  * @param destination Peer identity the channel should go to.
 257  * @param port Identification of the destination port.
 258  * @param options CadetOption flag field, with all desired option bits set to 1.
 259  * @param window_changes Function called when the transmit window size changes.
 260  *                       Can be NULL if this data is of no interest.
 261  * TODO                  Not yet implemented.
 262  * @param disconnects Function called when the channel is disconnected.
 263  * @param handlers Callbacks for messages we care about, NULL-terminated.
 264  * @return Handle to the channel.
 265  */
 266 struct GNUNET_CADET_Channel *
 267 GNUNET_CADET_channel_create (struct GNUNET_CADET_Handle *h,
 268                              void *channel_cls,
 269                              const struct GNUNET_PeerIdentity *destination,
 270                              const struct GNUNET_HashCode *port,
 271                              enum GNUNET_CADET_ChannelOption options,
 272                              GNUNET_CADET_WindowSizeEventHandler window_changes,
 273                              GNUNET_CADET_DisconnectEventHandler disconnects,
 274                              const struct GNUNET_MQ_MessageHandler *handlers);
 275
 276
 277 /**
 278  * Destroy an existing channel.
 279  *
 280  * The existing end callback for the channel will be called immediately.
 281  * Any pending outgoing messages will be sent but no incoming messages will be
 282  * accepted and no data callbacks will be called.
 283  *
 284  * @param channel Channel handle, becomes invalid after this call.
 285  */
 286 void
 287 GNUNET_CADET_channel_destroy (struct GNUNET_CADET_Channel *channel);
 288
 289
 290 /**
 291  * Obtain the message queue for a connected channel.
 292  *
 293  * @param channel The channel handle from which to get the MQ.
 294  * @return The message queue of the channel.
 295  */
 296 struct GNUNET_MQ_Handle *
 297 GNUNET_CADET_get_mq (const struct GNUNET_CADET_Channel *channel);
 298
 299
 300 /**
 301  * Indicate readiness to receive the next message on a channel.
 302  *
 303  * Should only be called once per handler called.
 304  *
 305  * @param channel Channel that will be allowed to call another handler.
 306  */
 307 void
 308 GNUNET_CADET_receive_done (struct GNUNET_CADET_Channel *channel);
 309
 310
 311 /******************************************************************************/
 312 /********************       MONITORING /DEBUG API     *************************/
 313 /******************************************************************************/
 314 /* The following calls are not useful for normal CADET operation, but for      */
 315 /* debug and monitoring of the cadet state. They can be safely ignored.        */
 316 /* The API can change at any point without notice.                            */
 317 /* Please contact the developer if you consider any of this calls useful for  */
 318 /* normal cadet applications.                                                  */
 319 /******************************************************************************/
 320
 321
 322 /**
 323  * Transitional function to convert an unsigned int port to a hash value.
 324  * WARNING: local static value returned, NOT reentrant!
 325  * WARNING: do not use this function for new code!
 326  *
 327  * @param port Numerical port (unsigned int format).
 328  *
 329  * @return A GNUNET_HashCode usable for the new CADET API.
 330  */
 331 const struct GNUNET_HashCode *
 332 GC_u2h (uint32_t port);
 333
 334
 335
 336 /**
 337  * Struct to retrieve info about a channel.
 338  */
 339 union GNUNET_CADET_ChannelInfo
 340 {
 341
 342   /**
 343    * #GNUNET_YES / #GNUNET_NO, for binary flags.
 344    */
 345   int yes_no;
 346
 347   /**
 348    * Peer on the other side of the channel
 349    */
 350   const struct GNUNET_PeerIdentity peer;
 351 };
 352
 353
 354 /**
 355  * Get information about a channel.
 356  *
 357  * @param channel Channel handle.
 358  * @param option Query type GNUNET_CADET_OPTION_*
 359  * @param ... dependant on option, currently not used
 360  * @return Union with an answer to the query.
 361  */
 362 const union GNUNET_CADET_ChannelInfo *
 363 GNUNET_CADET_channel_get_info (struct GNUNET_CADET_Channel *channel,
 364                               enum GNUNET_CADET_ChannelOption option,
 365                                ...);
 366
 367
 368 /**
 369  * Method called to retrieve information about a specific channel the cadet peer
 370  * is aware of, including all transit nodes.
 371  *
 372  * @param cls Closure.
 373  * @param root Root of the channel.
 374  * @param dest Destination of the channel.
 375  * @param port Destination port of the channel.
 376  * @param root_channel_number Local number for root, if known.
 377  * @param dest_channel_number Local number for dest, if known.
 378  * @param public_channel_numbe Number for P2P, always known.
 379  */
 380 typedef void
 381 (*GNUNET_CADET_ChannelCB) (void *cls,
 382                            const struct GNUNET_PeerIdentity *root,
 383                            const struct GNUNET_PeerIdentity *dest,
 384                            uint32_t /* UGH */ port,
 385                            uint32_t /* ugh */ root_channel_number,
 386                            uint32_t /* ugh */ dest_channel_number,
 387                            uint32_t /* ugh */ public_channel_number);
 388
 389 /**
 390  * Method called to retrieve information about all peers in CADET, called
 391  * once per peer.
 392  *
 393  * After last peer has been reported, an additional call with NULL is done.
 394  *
 395  * @param cls Closure.
 396  * @param peer Peer, or NULL on "EOF".
 397  * @param tunnel Do we have a tunnel towards this peer?
 398  * @param n_paths Number of known paths towards this peer.
 399  * @param best_path How long is the best path?
 400  *                  (0 = unknown, 1 = ourselves, 2 = neighbor)
 401  */
 402 typedef void
 403 (*GNUNET_CADET_PeersCB) (void *cls,
 404                          const struct GNUNET_PeerIdentity *peer,
 405                          int tunnel,
 406                          unsigned int n_paths,
 407                          unsigned int best_path);
 408
 409 /**
 410  * Method called to retrieve information about a specific peer
 411  * known to the service.
 412  *
 413  * @param cls Closure.
 414  * @param peer Peer ID.
 415  * @param tunnel Do we have a tunnel towards this peer? #GNUNET_YES/#GNUNET_NO
 416  * @param neighbor Is this a direct neighbor? #GNUNET_YES/#GNUNET_NO
 417  * @param n_paths Number of paths known towards peer.
 418  * @param paths Array of PEER_IDs representing all paths to reach the peer.
 419  *              Each path starts with the first hop (local peer not included).
 420  *              Each path ends with the destination peer (given in @c peer).
 421  */
 422 typedef void
 423 (*GNUNET_CADET_PeerCB) (void *cls,
 424                         const struct GNUNET_PeerIdentity *peer,
 425                         int tunnel,
 426                         int neighbor,
 427                         unsigned int n_paths,
 428                         const struct GNUNET_PeerIdentity *paths,
 429                         int offset,
 430                         int finished_with_paths);
 431
 432
 433 /**
 434  * Method called to retrieve information about all tunnels in CADET, called
 435  * once per tunnel.
 436  *
 437  * After last tunnel has been reported, an additional call with NULL is done.
 438  *
 439  * @param cls Closure.
 440  * @param peer Destination peer, or NULL on "EOF".
 441  * @param channels Number of channels.
 442  * @param connections Number of connections.
 443  * @param estate Encryption state.
 444  * @param cstate Connectivity state.
 445  */
 446 typedef void
 447 (*GNUNET_CADET_TunnelsCB) (void *cls,
 448                            const struct GNUNET_PeerIdentity *peer,
 449                            unsigned int channels,
 450                            unsigned int connections,
 451                            uint16_t estate,
 452                            uint16_t cstate);
 453
 454
 455 /**
 456  * Method called to retrieve information about a specific tunnel the cadet peer
 457  * has established, o`r is trying to establish.
 458  *
 459  * @param cls Closure.
 460  * @param peer Peer towards whom the tunnel is directed.
 461  * @param n_channels Number of channels.
 462  * @param n_connections Number of connections.
 463  * @param channels Channels.
 464  * @param connections Connections.
 465  * @param estate Encryption state.
 466  * @param cstate Connectivity state.
 467  */
 468 typedef void
 469 (*GNUNET_CADET_TunnelCB) (void *cls,
 470                           const struct GNUNET_PeerIdentity *peer,
 471                           unsigned int n_channels,
 472                           unsigned int n_connections,
 473                           const struct GNUNET_CADET_ChannelTunnelNumber *channels,
 474                           const struct GNUNET_CADET_ConnectionTunnelIdentifier *connections,
 475                           unsigned int estate,
 476                           unsigned int cstate);
 477
 478
 479 /**
 480  * Request information about a specific channel of the running cadet peer.
 481  *
 482  * WARNING: unstable API, likely to change in the future!
 483  *
 484  * @param h Handle to the cadet peer.
 485  * @param peer ID of the other end of the channel.
 486  * @param channel_number Channel number.
 487  * @param callback Function to call with the requested data.
 488  * @param callback_cls Closure for @c callback.
 489  */
 490 void
 491 GNUNET_CADET_get_channel (struct GNUNET_CADET_Handle *h,
 492                           struct GNUNET_PeerIdentity *peer,
 493                           uint32_t /* UGH */ channel_number,
 494                           GNUNET_CADET_ChannelCB callback,
 495                           void *callback_cls);
 496
 497
 498 /**
 499  * Request a debug dump on the service's STDERR.
 500  *
 501  * WARNING: unstable API, likely to change in the future!
 502  *
 503  * @param h cadet handle
 504  */
 505 void
 506 GNUNET_CADET_request_dump (struct GNUNET_CADET_Handle *h);
 507
 508
 509 /**
 510  * Request information about peers known to the running cadet service.
 511  * The callback will be called for every peer known to the service.
 512  * Only one info request (of any kind) can be active at once.
 513  *
 514  *
 515  * WARNING: unstable API, likely to change in the future!
 516  *
 517  * @param h Handle to the cadet peer.
 518  * @param callback Function to call with the requested data.
 519  * @param callback_cls Closure for @c callback.
 520  *
 521  * @return #GNUNET_OK / #GNUNET_SYSERR
 522  */
 523 int
 524 GNUNET_CADET_get_peers (struct GNUNET_CADET_Handle *h,
 525                         GNUNET_CADET_PeersCB callback,
 526                         void *callback_cls);
 527
 528
 529 /**
 530  * Cancel a peer info request. The callback will not be called (anymore).
 531  *
 532  * WARNING: unstable API, likely to change in the future!
 533  *
 534  * @param h Cadet handle.
 535  *
 536  * @return Closure that was given to #GNUNET_CADET_get_peers().
 537  */
 538 void *
 539 GNUNET_CADET_get_peers_cancel (struct GNUNET_CADET_Handle *h);
 540
 541
 542 /**
 543  * Request information about a peer known to the running cadet peer.
 544  * The callback will be called for the tunnel once.
 545  * Only one info request (of any kind) can be active at once.
 546  *
 547  * WARNING: unstable API, likely to change in the future!
 548  *
 549  * @param h Handle to the cadet peer.
 550  * @param id Peer whose tunnel to examine.
 551  * @param callback Function to call with the requested data.
 552  * @param callback_cls Closure for @c callback.
 553  *
 554  * @return #GNUNET_OK / #GNUNET_SYSERR
 555  */
 556 int
 557 GNUNET_CADET_get_peer (struct GNUNET_CADET_Handle *h,
 558                       const struct GNUNET_PeerIdentity *id,
 559                       GNUNET_CADET_PeerCB callback,
 560                       void *callback_cls);
 561
 562
 563 /**
 564  * Request information about tunnels of the running cadet peer.
 565  * The callback will be called for every tunnel of the service.
 566  * Only one info request (of any kind) can be active at once.
 567  *
 568  * WARNING: unstable API, likely to change in the future!
 569  *
 570  * @param h Handle to the cadet peer.
 571  * @param callback Function to call with the requested data.
 572  * @param callback_cls Closure for @c callback.
 573  *
 574  * @return #GNUNET_OK / #GNUNET_SYSERR
 575  */
 576 int
 577 GNUNET_CADET_get_tunnels (struct GNUNET_CADET_Handle *h,
 578                           GNUNET_CADET_TunnelsCB callback,
 579                           void *callback_cls);
 580
 581
 582 /**
 583  * Cancel a monitor request. The monitor callback will not be called.
 584  *
 585  * @param h Cadet handle.
 586  *
 587  * @return Closure given to #GNUNET_CADET_get_tunnels(), if any.
 588  */
 589 void *
 590 GNUNET_CADET_get_tunnels_cancel (struct GNUNET_CADET_Handle *h);
 591
 592
 593 /**
 594  * Request information about a tunnel of the running cadet peer.
 595  * The callback will be called for the tunnel once.
 596  * Only one info request (of any kind) can be active at once.
 597  *
 598  * WARNING: unstable API, likely to change in the future!
 599  *
 600  * @param h Handle to the cadet peer.
 601  * @param id Peer whose tunnel to examine.
 602  * @param callback Function to call with the requested data.
 603  * @param callback_cls Closure for @c callback.
 604  *
 605  * @return #GNUNET_OK / #GNUNET_SYSERR
 606  */
 607 int
 608 GNUNET_CADET_get_tunnel (struct GNUNET_CADET_Handle *h,
 609                          const struct GNUNET_PeerIdentity *id,
 610                          GNUNET_CADET_TunnelCB callback,
 611                          void *callback_cls);
 612
 613
 614
 615 #if 0                           /* keep Emacsens' auto-indent happy */
 616 {
 617 #endif
 618 #ifdef __cplusplus
 619 }
 620 #endif
 621
 622 /* ifndef GNUNET_CADET_SERVICE_H */
 623 #endif
 624
 625 /** @} */  /* end of group */
 626
 627 /* end of gnunet_cadet_service.h */