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  * Union to retrieve info about a channel.
 293  */
 294 union GNUNET_CADET_ChannelInfo
 295 {
 296   /**
 297    * #GNUNET_YES / #GNUNET_NO, for binary flags.
 298    */
 299   int yes_no;
 300
 301   /**
 302    * Peer on the other side of the channel
 303    */
 304   const struct GNUNET_PeerIdentity peer;
 305 };
 306
 307
 308 /**
 309  * Get information about a channel.
 310  *
 311  * @param channel Channel handle.
 312  * @param ... dependant on option, currently not used
 313  * @return Union with an answer to the query.
 314  */
 315 const union GNUNET_CADET_ChannelInfo *
 316 GNUNET_CADET_channel_get_info (struct GNUNET_CADET_Channel *channel,
 317                                enum GNUNET_CADET_ChannelInfoOption option,
 318                                ...);
 319
 320
 321 /******************************************************************************/
 322 /********************       MONITORING /DEBUG API     *************************/
 323 /******************************************************************************/
 324 /* The following calls are not useful for normal CADET operation, but for      */
 325 /* debug and monitoring of the cadet state. They can be safely ignored.        */
 326 /* The API can change at any point without notice.                            */
 327 /* Please contact the developer if you consider any of this calls useful for  */
 328 /* normal cadet applications.                                                  */
 329 /******************************************************************************/
 330
 331
 332 /**
 333  * Internal details about a channel.
 334  */
 335 struct GNUNET_CADET_ChannelInternals
 336 {
 337   /**
 338    * Root of the channel
 339    */
 340   struct GNUNET_PeerIdentity root;
 341
 342   /**
 343    * Destination of the channel
 344    */
 345   struct GNUNET_PeerIdentity dest;
 346
 347   // to be expanded!
 348 };
 349
 350
 351 /**
 352  * Method called to retrieve information about a specific channel the cadet peer
 353  * is aware of, including all transit nodes.
 354  *
 355  * @param cls Closure.
 356  * @param info internal details, NULL for end of list
 357  */
 358 typedef void (*GNUNET_CADET_ChannelCB) (
 359   void *cls,
 360   const struct GNUNET_CADET_ChannelInternals *info);
 361
 362
 363 /**
 364  * Operation handle.
 365  */
 366 struct GNUNET_CADET_ChannelMonitor;
 367
 368
 369 /**
 370  * Request information about channels to @a peer from the local peer.
 371  *
 372  * @param cfg configuration to use
 373  * @param peer ID of the other end of the channel.
 374  * @param callback Function to call with the requested data.
 375  * @param callback_cls Closure for @c callback.
 376  */
 377 struct GNUNET_CADET_ChannelMonitor *
 378 GNUNET_CADET_get_channel (const struct GNUNET_CONFIGURATION_Handle *cfg,
 379                           struct GNUNET_PeerIdentity *peer,
 380                           GNUNET_CADET_ChannelCB callback,
 381                           void *callback_cls);
 382
 383
 384 /**
 385  * Cancel a channel monitor request. The callback will not be called (anymore).
 386  *
 387  * @param h Cadet handle.
 388  * @return Closure that was given to #GNUNET_CADET_get_channel().
 389  */
 390 void *
 391 GNUNET_CADET_get_channel_cancel (struct GNUNET_CADET_ChannelMonitor *cm);
 392
 393
 394 /**
 395  * Information we return per peer.
 396  */
 397 struct GNUNET_CADET_PeerListEntry
 398 {
 399   /**
 400    * Which peer is the information about?
 401    */
 402   struct GNUNET_PeerIdentity peer;
 403
 404   /**
 405    * Do we have a tunnel to this peer?
 406    */
 407   int have_tunnel;
 408
 409   /**
 410    * Number of disjoint known paths to @e peer.
 411    */
 412   unsigned int n_paths;
 413
 414   /**
 415    * Length of the shortest path (0 = unknown, 1 = ourselves, 2 = direct neighbour).
 416    */
 417   unsigned int best_path_length;
 418 };
 419
 420
 421 /**
 422  * Method called to retrieve information about all peers in CADET, called
 423  * once per peer.
 424  *
 425  * After last peer has been reported, an additional call with NULL is done.
 426  *
 427  * @param cls Closure.
 428  * @param ple information about a peer, or NULL on "EOF".
 429  */
 430 typedef void (*GNUNET_CADET_PeersCB) (
 431   void *cls,
 432   const struct GNUNET_CADET_PeerListEntry *ple);
 433
 434
 435 /**
 436  * Operation handle.
 437  */
 438 struct GNUNET_CADET_PeersLister;
 439
 440
 441 /**
 442  * Request information about peers known to the running cadet service.
 443  * The callback will be called for every peer known to the service.
 444  * Only one info request (of any kind) can be active at once.
 445  *
 446  * @param cfg configuration to use
 447  * @param callback Function to call with the requested data.
 448  * @param callback_cls Closure for @c callback.
 449  * @return NULL on error
 450  */
 451 struct GNUNET_CADET_PeersLister *
 452 GNUNET_CADET_list_peers (const struct GNUNET_CONFIGURATION_Handle *cfg,
 453                          GNUNET_CADET_PeersCB callback,
 454                          void *callback_cls);
 455
 456
 457 /**
 458  * Cancel a peer info request. The callback will not be called (anymore).
 459  *
 460  * @param pl operation handle
 461  * @return Closure that was given to #GNUNET_CADET_list_peers().
 462  */
 463 void *
 464 GNUNET_CADET_list_peers_cancel (struct GNUNET_CADET_PeersLister *pl);
 465
 466
 467 /**
 468  * Detailed information we return per peer.
 469  */
 470 struct GNUNET_CADET_PeerPathDetail
 471 {
 472   /**
 473    * Peer this is about.
 474    */
 475   struct GNUNET_PeerIdentity peer;
 476
 477   /**
 478    * Offset of the target peer on the @e path.
 479    */
 480   unsigned int target_offset;
 481
 482   /**
 483    * Number of entries on the @e path.
 484    */
 485   unsigned int path_length;
 486
 487   /**
 488    * Array of PEER_IDs representing all paths to reach the peer.  Each
 489    * path starts with the first hop (local peer not included).  Each
 490    * path ends with the destination peer (given in @e peer).
 491    */
 492   const struct GNUNET_PeerIdentity *path;
 493 };
 494
 495
 496 /**
 497  * Method called to retrieve information about a specific path
 498  * known to the service.
 499  *
 500  * @param cls Closure.
 501  * @param ppd details about a path to the peer, NULL for end of information
 502  */
 503 typedef void (*GNUNET_CADET_PathCB) (
 504   void *cls,
 505   const struct GNUNET_CADET_PeerPathDetail *ppd);
 506
 507
 508 /**
 509  * Handle to cancel #GNUNET_CADET_get_path() operation.
 510  */
 511 struct GNUNET_CADET_GetPath;
 512
 513
 514 /**
 515  * Request information about a peer known to the running cadet peer.
 516  *
 517  * @param cfg configuration to use
 518  * @param id Peer whose paths we want to examine.
 519  * @param callback Function to call with the requested data.
 520  * @param callback_cls Closure for @c callback.
 521  * @return NULL on error
 522  */
 523 struct GNUNET_CADET_GetPath *
 524 GNUNET_CADET_get_path (const struct GNUNET_CONFIGURATION_Handle *cfg,
 525                        const struct GNUNET_PeerIdentity *id,
 526                        GNUNET_CADET_PathCB callback,
 527                        void *callback_cls);
 528
 529
 530 /**
 531  * Cancel @a gp operation.
 532  *
 533  * @param gp operation to cancel
 534  * @return closure from #GNUNET_CADET_get_path().
 535  */
 536 void *
 537 GNUNET_CADET_get_path_cancel (struct GNUNET_CADET_GetPath *gp);
 538
 539
 540 /**
 541  * Details about a tunnel managed by CADET.
 542  */
 543 struct GNUNET_CADET_TunnelDetails
 544 {
 545   /**
 546    * Target of the tunnel.
 547    */
 548   struct GNUNET_PeerIdentity peer;
 549
 550   /**
 551    * How many channels use the tunnel.
 552    */
 553   uint32_t channels;
 554
 555   /**
 556    * How many connections support the tunnel.
 557    */
 558   uint32_t connections;
 559
 560   /**
 561    * What is our encryption state?
 562    */
 563   uint16_t estate;
 564
 565   /**
 566    * What is our connectivity state?
 567    */
 568   uint16_t cstate;
 569 };
 570
 571
 572 /**
 573  * Method called to retrieve information about all tunnels in CADET, called
 574  * once per tunnel.
 575  *
 576  * After last tunnel has been reported, an additional call with NULL is done.
 577  *
 578  * @param cls Closure.
 579  * @param td tunnel details, NULL for end of list
 580  */
 581 typedef void (*GNUNET_CADET_TunnelsCB) (
 582   void *cls,
 583   const struct GNUNET_CADET_TunnelDetails *td);
 584
 585
 586 /**
 587  * Operation handle.
 588  */
 589 struct GNUNET_CADET_ListTunnels;
 590
 591
 592 /**
 593  * Request information about tunnels of the running cadet peer.
 594  * The callback will be called for every tunnel of the service.
 595  * Only one info request (of any kind) can be active at once.
 596  *
 597  * @param cfg configuration to use
 598  * @param callback Function to call with the requested data.
 599  * @param callback_cls Closure for @c callback.
 600  * @return NULL on error
 601  */
 602 struct GNUNET_CADET_ListTunnels *
 603 GNUNET_CADET_list_tunnels (const struct GNUNET_CONFIGURATION_Handle *cfg,
 604                            GNUNET_CADET_TunnelsCB callback,
 605                            void *callback_cls);
 606
 607
 608 /**
 609  * Cancel a monitor request. The monitor callback will not be called.
 610  *
 611  * @param lt operation handle
 612  * @return Closure given to #GNUNET_CADET_list_tunnels(), if any.
 613  */
 614 void *
 615 GNUNET_CADET_list_tunnels_cancel (struct GNUNET_CADET_ListTunnels *lt);
 616
 617
 618 #if 0 /* keep Emacsens' auto-indent happy */
 619 {
 620 #endif
 621 #ifdef __cplusplus
 622 }
 623 #endif
 624
 625 /* ifndef GNUNET_CADET_SERVICE_H */
 626 #endif
 627
 628 /** @} */ /* end of group */
 629
 630 /* end of gnunet_cadet_service.h */