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