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