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 port is not open by any peer or the destination peer
 209  * does not accept the channel, @a disconnects will be called
 210  * for this channel.
 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  * TODO                  Not yet implemented.
 222  * @param disconnects Function called when the channel is disconnected.
 223  * @param handlers Callbacks for messages we care about, NULL-terminated.
 224  * @return Handle to the channel.
 225  */
 226 struct GNUNET_CADET_Channel *
 227 GNUNET_CADET_channel_create (struct GNUNET_CADET_Handle *h,
 228                              void *channel_cls,
 229                              const struct GNUNET_PeerIdentity *destination,
 230                              const struct GNUNET_HashCode *port,
 231                              GNUNET_CADET_WindowSizeEventHandler window_changes,
 232                              GNUNET_CADET_DisconnectEventHandler disconnects,
 233                              const struct GNUNET_MQ_MessageHandler *handlers);
 234
 235
 236 /**
 237  * Destroy an existing channel.
 238  *
 239  * The existing end callback for the channel will NOT be called.
 240  * Any pending outgoing messages will be sent but no incoming messages will be
 241  * accepted and no data callbacks will be called.
 242  *
 243  * @param channel Channel handle, becomes invalid after this call.
 244  */
 245 void
 246 GNUNET_CADET_channel_destroy (struct GNUNET_CADET_Channel *channel);
 247
 248
 249 /**
 250  * Obtain the message queue for a connected channel.
 251  *
 252  * @param channel The channel handle from which to get the MQ.
 253  * @return The message queue of the channel.
 254  */
 255 struct GNUNET_MQ_Handle *
 256 GNUNET_CADET_get_mq (const struct GNUNET_CADET_Channel *channel);
 257
 258
 259 /**
 260  * Indicate readiness to receive the next message on a channel.
 261  *
 262  * Should only be called once per handler called.
 263  *
 264  * @param channel Channel that will be allowed to call another handler.
 265  */
 266 void
 267 GNUNET_CADET_receive_done (struct GNUNET_CADET_Channel *channel);
 268
 269
 270 /**
 271  * Transitional function to convert an unsigned int port to a hash value.
 272  * WARNING: local static value returned, NOT reentrant!
 273  * WARNING: do not use this function for new code!
 274  *
 275  * @param port Numerical port (unsigned int format).
 276  *
 277  * @return A GNUNET_HashCode usable for the new CADET API.
 278  */
 279 const struct GNUNET_HashCode *
 280 GC_u2h (uint32_t port);
 281
 282 enum GNUNET_CADET_ChannelInfoOption
 283 {
 284   /**
 285    * Who is the peer at the other end of the channel.
 286    * Only for use in @c GNUNET_CADET_channel_get_info
 287    * struct GNUNET_PeerIdentity *peer
 288    */
 289   GNUNET_CADET_OPTION_PEER = 0x0
 290
 291 };
 292
 293 /**
 294  * Union to retrieve info about a channel.
 295  */
 296 union GNUNET_CADET_ChannelInfo
 297 {
 298
 299   /**
 300    * #GNUNET_YES / #GNUNET_NO, for binary flags.
 301    */
 302   int yes_no;
 303
 304   /**
 305    * Peer on the other side of the channel
 306    */
 307   const struct GNUNET_PeerIdentity peer;
 308 };
 309
 310
 311 /**
 312  * Get information about a channel.
 313  *
 314  * @param channel Channel handle.
 315  * @param ... dependant on option, currently not used
 316  * @return Union with an answer to the query.
 317  */
 318 const union GNUNET_CADET_ChannelInfo *
 319 GNUNET_CADET_channel_get_info (struct GNUNET_CADET_Channel *channel,
 320                                enum GNUNET_CADET_ChannelInfoOption option,
 321                                ...);
 322
 323
 324 /******************************************************************************/
 325 /********************       MONITORING /DEBUG API     *************************/
 326 /******************************************************************************/
 327 /* The following calls are not useful for normal CADET operation, but for      */
 328 /* debug and monitoring of the cadet state. They can be safely ignored.        */
 329 /* The API can change at any point without notice.                            */
 330 /* Please contact the developer if you consider any of this calls useful for  */
 331 /* normal cadet applications.                                                  */
 332 /******************************************************************************/
 333
 334
 335 /**
 336  * Internal details about a channel.
 337  */
 338 struct GNUNET_CADET_ChannelInternals
 339 {
 340   /**
 341    * Root of the channel
 342    */
 343   struct GNUNET_PeerIdentity root;
 344
 345   /**
 346    * Destination of the channel
 347    */
 348   struct GNUNET_PeerIdentity dest;
 349
 350   // to be expanded!
 351 };
 352
 353
 354 /**
 355  * Method called to retrieve information about a specific channel the cadet peer
 356  * is aware of, including all transit nodes.
 357  *
 358  * @param cls Closure.
 359  * @param info internal details, NULL for end of list
 360  */
 361 typedef void (*GNUNET_CADET_ChannelCB) (
 362   void *cls,
 363   const struct GNUNET_CADET_ChannelInternals *info);
 364
 365
 366 /**
 367  * Operation handle.
 368  */
 369 struct GNUNET_CADET_ChannelMonitor;
 370
 371
 372 /**
 373  * Request information about channels to @a peer from the local peer.
 374  *
 375  * @param cfg configuration to use
 376  * @param peer ID of the other end of the channel.
 377  * @param callback Function to call with the requested data.
 378  * @param callback_cls Closure for @c callback.
 379  */
 380 struct GNUNET_CADET_ChannelMonitor *
 381 GNUNET_CADET_get_channel (const struct GNUNET_CONFIGURATION_Handle *cfg,
 382                           struct GNUNET_PeerIdentity *peer,
 383                           GNUNET_CADET_ChannelCB callback,
 384                           void *callback_cls);
 385
 386
 387 /**
 388  * Cancel a channel monitor request. The callback will not be called (anymore).
 389  *
 390  * @param h Cadet handle.
 391  * @return Closure that was given to #GNUNET_CADET_get_channel().
 392  */
 393 void *
 394 GNUNET_CADET_get_channel_cancel (struct GNUNET_CADET_ChannelMonitor *cm);
 395
 396
 397 /**
 398  * Information we return per peer.
 399  */
 400 struct GNUNET_CADET_PeerListEntry
 401 {
 402   /**
 403    * Which peer is the information about?
 404    */
 405   struct GNUNET_PeerIdentity peer;
 406
 407   /**
 408    * Do we have a tunnel to this peer?
 409    */
 410   int have_tunnel;
 411
 412   /**
 413    * Number of disjoint known paths to @e peer.
 414    */
 415   unsigned int n_paths;
 416
 417   /**
 418    * Length of the shortest path (0 = unknown, 1 = ourselves, 2 = direct neighbour).
 419    */
 420   unsigned int best_path_length;
 421 };
 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 ple information about a peer, or NULL on "EOF".
 432  */
 433 typedef void (*GNUNET_CADET_PeersCB) (
 434   void *cls,
 435   const struct GNUNET_CADET_PeerListEntry *ple);
 436
 437
 438 /**
 439  * Operation handle.
 440  */
 441 struct GNUNET_CADET_PeersLister;
 442
 443
 444 /**
 445  * Request information about peers known to the running cadet service.
 446  * The callback will be called for every peer known to the service.
 447  * Only one info request (of any kind) can be active at once.
 448  *
 449  * @param cfg configuration to use
 450  * @param callback Function to call with the requested data.
 451  * @param callback_cls Closure for @c callback.
 452  * @return NULL on error
 453  */
 454 struct GNUNET_CADET_PeersLister *
 455 GNUNET_CADET_list_peers (const struct GNUNET_CONFIGURATION_Handle *cfg,
 456                          GNUNET_CADET_PeersCB callback,
 457                          void *callback_cls);
 458
 459
 460 /**
 461  * Cancel a peer info request. The callback will not be called (anymore).
 462  *
 463  * @param pl operation handle
 464  * @return Closure that was given to #GNUNET_CADET_list_peers().
 465  */
 466 void *
 467 GNUNET_CADET_list_peers_cancel (struct GNUNET_CADET_PeersLister *pl);
 468
 469
 470 /**
 471  * Detailed information we return per peer.
 472  */
 473 struct GNUNET_CADET_PeerPathDetail
 474 {
 475   /**
 476    * Peer this is about.
 477    */
 478   struct GNUNET_PeerIdentity peer;
 479
 480   /**
 481    * Offset of the target peer on the @e path.
 482    */
 483   unsigned int target_offset;
 484
 485   /**
 486    * Number of entries on the @e path.
 487    */
 488   unsigned int path_length;
 489
 490   /**
 491    * Array of PEER_IDs representing all paths to reach the peer.  Each
 492    * path starts with the first hop (local peer not included).  Each
 493    * path ends with the destination peer (given in @e peer).
 494    */
 495   const struct GNUNET_PeerIdentity *path;
 496 };
 497
 498
 499 /**
 500  * Method called to retrieve information about a specific path
 501  * known to the service.
 502  *
 503  * @param cls Closure.
 504  * @param ppd details about a path to the peer, NULL for end of information
 505  */
 506 typedef void (*GNUNET_CADET_PathCB) (
 507   void *cls,
 508   const struct GNUNET_CADET_PeerPathDetail *ppd);
 509
 510
 511 /**
 512  * Handle to cancel #GNUNET_CADET_get_path() operation.
 513  */
 514 struct GNUNET_CADET_GetPath;
 515
 516
 517 /**
 518  * Request information about a peer known to the running cadet peer.
 519  *
 520  * @param cfg configuration to use
 521  * @param id Peer whose paths we want to examine.
 522  * @param callback Function to call with the requested data.
 523  * @param callback_cls Closure for @c callback.
 524  * @return NULL on error
 525  */
 526 struct GNUNET_CADET_GetPath *
 527 GNUNET_CADET_get_path (const struct GNUNET_CONFIGURATION_Handle *cfg,
 528                        const struct GNUNET_PeerIdentity *id,
 529                        GNUNET_CADET_PathCB callback,
 530                        void *callback_cls);
 531
 532
 533 /**
 534  * Cancel @a gp operation.
 535  *
 536  * @param gp operation to cancel
 537  * @return closure from #GNUNET_CADET_get_path().
 538  */
 539 void *
 540 GNUNET_CADET_get_path_cancel (struct GNUNET_CADET_GetPath *gp);
 541
 542
 543 /**
 544  * Details about a tunnel managed by CADET.
 545  */
 546 struct GNUNET_CADET_TunnelDetails
 547 {
 548   /**
 549    * Target of the tunnel.
 550    */
 551   struct GNUNET_PeerIdentity peer;
 552
 553   /**
 554    * How many channels use the tunnel.
 555    */
 556   uint32_t channels;
 557
 558   /**
 559    * How many connections support the tunnel.
 560    */
 561   uint32_t connections;
 562
 563   /**
 564    * What is our encryption state?
 565    */
 566   uint16_t estate;
 567
 568   /**
 569    * What is our connectivity state?
 570    */
 571   uint16_t cstate;
 572 };
 573
 574
 575 /**
 576  * Method called to retrieve information about all tunnels in CADET, called
 577  * once per tunnel.
 578  *
 579  * After last tunnel has been reported, an additional call with NULL is done.
 580  *
 581  * @param cls Closure.
 582  * @param td tunnel details, NULL for end of list
 583  */
 584 typedef void (*GNUNET_CADET_TunnelsCB) (
 585   void *cls,
 586   const struct GNUNET_CADET_TunnelDetails *td);
 587
 588
 589 /**
 590  * Operation handle.
 591  */
 592 struct GNUNET_CADET_ListTunnels;
 593
 594
 595 /**
 596  * Request information about tunnels of the running cadet peer.
 597  * The callback will be called for every tunnel of the service.
 598  * Only one info request (of any kind) can be active at once.
 599  *
 600  * @param cfg configuration to use
 601  * @param callback Function to call with the requested data.
 602  * @param callback_cls Closure for @c callback.
 603  * @return NULL on error
 604  */
 605 struct GNUNET_CADET_ListTunnels *
 606 GNUNET_CADET_list_tunnels (const struct GNUNET_CONFIGURATION_Handle *cfg,
 607                            GNUNET_CADET_TunnelsCB callback,
 608                            void *callback_cls);
 609
 610
 611 /**
 612  * Cancel a monitor request. The monitor callback will not be called.
 613  *
 614  * @param lt operation handle
 615  * @return Closure given to #GNUNET_CADET_list_tunnels(), if any.
 616  */
 617 void *
 618 GNUNET_CADET_list_tunnels_cancel (struct GNUNET_CADET_ListTunnels *lt);
 619
 620
 621 #if 0 /* keep Emacsens' auto-indent happy */
 622 {
 623 #endif
 624 #ifdef __cplusplus
 625 }
 626 #endif
 627
 628 /* ifndef GNUNET_CADET_SERVICE_H */
 629 #endif
 630
 631 /** @} */ /* end of group */
 632
 633 /* end of gnunet_cadet_service.h */