src/include/gnunet_cadet_service.h

   1 /*
   2      This file is part of GNUnet.
   3      Copyright (C) 2009-2014 Christian Grothoff (and other contributing authors)
   4
   5      GNUnet is free software; you can redistribute it and/or modify
   6      it under the terms of the GNU General Public License as published
   7      by the Free Software Foundation; either version 3, or (at your
   8      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      General Public License for more details.
  14
  15      You should have received a copy of the GNU General Public License
  16      along with GNUnet; see the file COPYING.  If not, write to the
  17      Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  18      Boston, MA 02110-1301, USA.
  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 also:
  31  * - [CADET documentation](https://gnunet.org/cadet-subsystem)
  32  * - [CADET paper](https://gnunet.org/cadet)
  33  *
  34  * @{
  35  */
  36 #ifndef GNUNET_CADET_SERVICE_H
  37 #define GNUNET_CADET_SERVICE_H
  38
  39 #ifdef __cplusplus
  40 extern "C"
  41 {
  42 #if 0                           /* keep Emacsens' auto-indent happy */
  43 }
  44 #endif
  45 #endif
  46
  47 #include "gnunet_util_lib.h"
  48 #include "gnunet_transport_service.h"
  49
  50 /**
  51  * Version number of GNUnet-cadet API.
  52  */
  53 #define GNUNET_CADET_VERSION 0x00000003
  54
  55
  56 /**
  57  * Opaque handle to the service.
  58  */
  59 struct GNUNET_CADET_Handle;
  60
  61 /**
  62  * Opaque handle to a channel.
  63  */
  64 struct GNUNET_CADET_Channel;
  65
  66 /**
  67  * Hash to be used in Cadet communication. Only 256 bits needed,
  68  * instead of the 512 from `struct GNUNET_HashCode`.
  69  */
  70 struct GNUNET_CADET_Hash
  71 {
  72   unsigned char bits[256 / 8];
  73 };
  74
  75
  76 /**
  77  * Channel options.  Second line indicates filed in the
  78  * CadetChannelInfo union carrying the answer.
  79  */
  80 enum GNUNET_CADET_ChannelOption
  81 {
  82   /**
  83    * Default options: unreliable, default buffering, not out of order.
  84    */
  85   GNUNET_CADET_OPTION_DEFAULT    = 0x0,
  86
  87   /**
  88    * Disable buffering on intermediate nodes (for minimum latency).
  89    * Yes/No.
  90    */
  91   GNUNET_CADET_OPTION_NOBUFFER   = 0x1,
  92
  93   /**
  94    * Enable channel reliability, lost messages will be retransmitted.
  95    * Yes/No.
  96    */
  97   GNUNET_CADET_OPTION_RELIABLE   = 0x2,
  98
  99   /**
 100    * Enable out of order delivery of messages.
 101    * Yes/No.
 102    */
 103   GNUNET_CADET_OPTION_OOORDER    = 0x4,
 104
 105   /**
 106    * Who is the peer at the other end of the channel.
 107    * Only for use in @c GNUNET_CADET_channel_get_info
 108    * struct GNUNET_PeerIdentity *peer
 109    */
 110   GNUNET_CADET_OPTION_PEER       = 0x8
 111
 112 };
 113
 114
 115 /**
 116  * Functions with this signature are called whenever a message is
 117  * received.
 118  *
 119  * Each time the function must call #GNUNET_CADET_receive_done on the channel
 120  * in order to receive the next message. This doesn't need to be immediate:
 121  * can be delayed if some processing is done on the message.
 122  *
 123  * @param cls Closure (set from #GNUNET_CADET_connect).
 124  * @param channel Connection to the other end.
 125  * @param channel_ctx Place to store local state associated with the channel.
 126  * @param message The actual message.
 127  * @return #GNUNET_OK to keep the channel open,
 128  *         #GNUNET_SYSERR to close it (signal serious error).
 129  */
 130 typedef int
 131 (*GNUNET_CADET_MessageCallback) (void *cls,
 132                                  struct GNUNET_CADET_Channel *channel,
 133                                  void **channel_ctx,
 134                                  const struct GNUNET_MessageHeader *message);
 135
 136
 137 /**
 138  * Message handler.  Each struct specifies how to handle on particular
 139  * type of message received.
 140  */
 141 struct GNUNET_CADET_MessageHandler
 142 {
 143   /**
 144    * Function to call for messages of type @e type.
 145    */
 146   GNUNET_CADET_MessageCallback callback;
 147
 148   /**
 149    * Type of the message this handler covers.
 150    */
 151   uint16_t type;
 152
 153   /**
 154    * Expected size of messages of this type.  Use 0 for variable-size.
 155    * If non-zero, messages of the given type will be discarded if they
 156    * do not have the right size.
 157    */
 158   uint16_t expected_size;
 159 };
 160
 161
 162 /**
 163  * Method called whenever another peer has added us to a channel
 164  * the other peer initiated.
 165  * Only called (once) upon reception of data with a message type which was
 166  * subscribed to in #GNUNET_CADET_connect.
 167  *
 168  * A call to #GNUNET_CADET_channel_destroy causes te channel to be ignored. In
 169  * this case the handler MUST return NULL.
 170  *
 171  * @param cls closure
 172  * @param channel new handle to the channel
 173  * @param initiator peer that started the channel
 174  * @param port Port this channel is for.
 175  * @param options CadetOption flag field, with all active option bits set to 1.
 176  *
 177  * @return initial channel context for the channel
 178  *         (can be NULL -- that's not an error)
 179  */
 180 typedef void *
 181 (GNUNET_CADET_InboundChannelNotificationHandler) (void *cls,
 182                                                   struct GNUNET_CADET_Channel *channel,
 183                                                   const struct GNUNET_PeerIdentity *initiator,
 184                                                   uint32_t port,
 185                                                   enum GNUNET_CADET_ChannelOption options);
 186
 187
 188 /**
 189  * Function called whenever a channel is destroyed.  Should clean up
 190  * any associated state, including cancelling any pending transmission on this
 191  * channel.
 192  *
 193  * It must NOT call #GNUNET_CADET_channel_destroy on the channel.
 194  *
 195  * @param cls closure (set from #GNUNET_CADET_connect)
 196  * @param channel connection to the other end (henceforth invalid)
 197  * @param channel_ctx place where local state associated
 198  *                   with the channel is stored
 199  */
 200 typedef void
 201 (GNUNET_CADET_ChannelEndHandler) (void *cls,
 202                                   const struct GNUNET_CADET_Channel *channel,
 203                                   void *channel_ctx);
 204
 205
 206 /**
 207  * Connect to the cadet service.
 208  *
 209  * @param cfg Configuration to use.
 210  * @param cls Closure for the various callbacks that follow (including
 211  *            handlers in the handlers array).
 212  * @param new_channel Function called when an *incoming* channel is created.
 213  *                    Can be NULL if no inbound channels are desired.
 214  *                    See @a ports.
 215  * @param cleaner Function called when a channel is destroyed.
 216  *                It is called immediately if #GNUNET_CADET_channel_destroy
 217  *                is called on the channel.
 218  * @param handlers Callbacks for messages we care about, NULL-terminated. Each
 219  *                 one must call #GNUNET_CADET_receive_done on the channel to
 220  *                 receive the next message.  Messages of a type that is not
 221  *                 in the handlers array are ignored if received.
 222  * @param ports NULL or 0-terminated array of port numbers for incoming channels.
 223  *              See @a new_channel.
 224  *
 225  * @return handle to the cadet service NULL on error
 226  *         (in this case, init is never called)
 227  */
 228 struct GNUNET_CADET_Handle *
 229 GNUNET_CADET_connect (const struct GNUNET_CONFIGURATION_Handle *cfg,
 230                       void *cls,
 231                       GNUNET_CADET_InboundChannelNotificationHandler new_channel,
 232                       GNUNET_CADET_ChannelEndHandler cleaner,
 233                       const struct GNUNET_CADET_MessageHandler *handlers,
 234                       const uint32_t *ports);
 235
 236
 237 /**
 238  * Disconnect from the cadet service. All channels will be destroyed. All channel
 239  * disconnect callbacks will be called on any still connected peers, notifying
 240  * about their disconnection. The registered inbound channel cleaner will be
 241  * called should any inbound channels still exist.
 242  *
 243  * @param handle connection to cadet to disconnect
 244  */
 245 void
 246 GNUNET_CADET_disconnect (struct GNUNET_CADET_Handle *handle);
 247
 248
 249 /**
 250  * Create a new channel towards a remote peer.
 251  *
 252  * If the destination port is not open by any peer or the destination peer
 253  * does not accept the channel, #GNUNET_CADET_ChannelEndHandler will be called
 254  * for this channel.
 255  *
 256  * @param h cadet handle
 257  * @param channel_ctx client's channel context to associate with the channel
 258  * @param peer peer identity the channel should go to
 259  * @param port Port number.
 260  * @param options CadetOption flag field, with all desired option bits set to 1.
 261  *
 262  * @return handle to the channel
 263  */
 264 struct GNUNET_CADET_Channel *
 265 GNUNET_CADET_channel_create (struct GNUNET_CADET_Handle *h,
 266                              void *channel_ctx,
 267                              const struct GNUNET_PeerIdentity *peer,
 268                              uint32_t port,
 269                              enum GNUNET_CADET_ChannelOption options);
 270
 271
 272 /**
 273  * Destroy an existing channel.
 274  *
 275  * The existing end callback for the channel will be called immediately.
 276  * Any pending outgoing messages will be sent but no incoming messages will be
 277  * accepted and no data callbacks will be called.
 278  *
 279  * @param channel Channel handle, becomes invalid after this call.
 280  */
 281 void
 282 GNUNET_CADET_channel_destroy (struct GNUNET_CADET_Channel *channel);
 283
 284
 285 /**
 286  * Struct to retrieve info about a channel.
 287  */
 288 union GNUNET_CADET_ChannelInfo
 289 {
 290
 291   /**
 292    * #GNUNET_YES / #GNUNET_NO, for binary flags.
 293    */
 294   int yes_no;
 295
 296   /**
 297    * Peer on the other side of the channel
 298    */
 299   const struct GNUNET_PeerIdentity peer;
 300 };
 301
 302
 303 /**
 304  * Get information about a channel.
 305  *
 306  * @param channel Channel handle.
 307  * @param option Query type GNUNET_CADET_OPTION_*
 308  * @param ... dependant on option, currently not used
 309  * @return Union with an answer to the query.
 310  */
 311 const union GNUNET_CADET_ChannelInfo *
 312 GNUNET_CADET_channel_get_info (struct GNUNET_CADET_Channel *channel,
 313                               enum GNUNET_CADET_ChannelOption option, ...);
 314
 315
 316 /**
 317  * Handle for a transmission request.
 318  */
 319 struct GNUNET_CADET_TransmitHandle;
 320
 321
 322 /**
 323  * Ask the cadet to call @a notify once it is ready to transmit the
 324  * given number of bytes to the specified channel.
 325  * Only one call can be active at any time, to issue another request,
 326  * wait for the callback or cancel the current request.
 327  *
 328  * @param channel channel to use for transmission
 329  * @param cork is corking allowed for this transmission?
 330  * @param maxdelay how long can the message wait?
 331  * @param notify_size how many bytes of buffer space does notify want?
 332  * @param notify function to call when buffer space is available;
 333  *        will be called with NULL on timeout or if the overall queue
 334  *        for this peer is larger than queue_size and this is currently
 335  *        the message with the lowest priority
 336  * @param notify_cls closure for @a notify
 337  * @return non-NULL if the notify callback was queued,
 338  *         NULL if we can not even queue the request (insufficient
 339  *         memory); if NULL is returned, @a notify will NOT be called.
 340  */
 341 struct GNUNET_CADET_TransmitHandle *
 342 GNUNET_CADET_notify_transmit_ready (struct GNUNET_CADET_Channel *channel,
 343                                    int cork,
 344                                    struct GNUNET_TIME_Relative maxdelay,
 345                                    size_t notify_size,
 346                                    GNUNET_CONNECTION_TransmitReadyNotify notify,
 347                                    void *notify_cls);
 348
 349
 350 /**
 351  * Cancel the specified transmission-ready notification.
 352  *
 353  * @param th handle that was returned by "notify_transmit_ready".
 354  */
 355 void
 356 GNUNET_CADET_notify_transmit_ready_cancel (struct GNUNET_CADET_TransmitHandle *th);
 357
 358
 359 /**
 360  * Indicate readiness to receive the next message on a channel.
 361  *
 362  * Should only be called once per handler called.
 363  *
 364  * @param channel Channel that will be allowed to call another handler.
 365  */
 366 void
 367 GNUNET_CADET_receive_done (struct GNUNET_CADET_Channel *channel);
 368
 369
 370
 371 /******************************************************************************/
 372 /********************       MONITORING /DEBUG API     *************************/
 373 /******************************************************************************/
 374 /* The following calls are not useful for normal CADET operation, but for      */
 375 /* debug and monitoring of the cadet state. They can be safely ignored.        */
 376 /* The API can change at any point without notice.                            */
 377 /* Please contact the developer if you consider any of this calls useful for  */
 378 /* normal cadet applications.                                                  */
 379 /******************************************************************************/
 380
 381
 382 /**
 383  * Method called to retrieve information about a specific channel the cadet peer
 384  * is aware of, including all transit nodes.
 385  *
 386  * @param cls Closure.
 387  * @param root Root of the channel.
 388  * @param dest Destination of the channel.
 389  * @param port Destination port of the channel.
 390  * @param root_channel_number Local number for root, if known.
 391  * @param dest_channel_number Local number for dest, if known.
 392  * @param public_channel_numbe Number for P2P, always known.
 393  */
 394 typedef void
 395 (*GNUNET_CADET_ChannelCB) (void *cls,
 396                            const struct GNUNET_PeerIdentity *root,
 397                            const struct GNUNET_PeerIdentity *dest,
 398                            uint32_t port,
 399                            uint32_t root_channel_number,
 400                            uint32_t dest_channel_number,
 401                            uint32_t public_channel_number);
 402
 403 /**
 404  * Method called to retrieve information about all peers in CADET, called
 405  * once per peer.
 406  *
 407  * After last peer has been reported, an additional call with NULL is done.
 408  *
 409  * @param cls Closure.
 410  * @param peer Peer, or NULL on "EOF".
 411  * @param tunnel Do we have a tunnel towards this peer?
 412  * @param n_paths Number of known paths towards this peer.
 413  * @param best_path How long is the best path?
 414  *                  (0 = unknown, 1 = ourselves, 2 = neighbor)
 415  */
 416 typedef void
 417 (*GNUNET_CADET_PeersCB) (void *cls,
 418                          const struct GNUNET_PeerIdentity *peer,
 419                          int tunnel,
 420                          unsigned int n_paths,
 421                          unsigned int best_path);
 422
 423 /**
 424  * Method called to retrieve information about a specific peer
 425  * known to the service.
 426  *
 427  * @param cls Closure.
 428  * @param peer Peer ID.
 429  * @param tunnel Do we have a tunnel towards this peer? #GNUNET_YES/#GNUNET_NO
 430  * @param neighbor Is this a direct neighbor? #GNUNET_YES/#GNUNET_NO
 431  * @param n_paths Number of paths known towards peer.
 432  * @param paths Array of PEER_IDs representing all paths to reach the peer.
 433  *              Each path starts with the first hop (local peer not included).
 434  *              Each path ends with the destination peer (given in @c peer).
 435  */
 436 typedef void
 437 (*GNUNET_CADET_PeerCB) (void *cls,
 438                         const struct GNUNET_PeerIdentity *peer,
 439                         int tunnel,
 440                         int neighbor,
 441                         unsigned int n_paths,
 442                         struct GNUNET_PeerIdentity *paths);
 443
 444
 445 /**
 446  * Method called to retrieve information about all tunnels in CADET, called
 447  * once per tunnel.
 448  *
 449  * After last tunnel has been reported, an additional call with NULL is done.
 450  *
 451  * @param cls Closure.
 452  * @param peer Destination peer, or NULL on "EOF".
 453  * @param channels Number of channels.
 454  * @param connections Number of connections.
 455  * @param estate Encryption state.
 456  * @param cstate Connectivity state.
 457  */
 458 typedef void
 459 (*GNUNET_CADET_TunnelsCB) (void *cls,
 460                            const struct GNUNET_PeerIdentity *peer,
 461                            unsigned int channels,
 462                            unsigned int connections,
 463                            uint16_t estate,
 464                            uint16_t cstate);
 465
 466
 467 /**
 468  * Method called to retrieve information about a specific tunnel the cadet peer
 469  * has established, o`r is trying to establish.
 470  *
 471  * @param cls Closure.
 472  * @param peer Peer towards whom the tunnel is directed.
 473  * @param n_channels Number of channels.
 474  * @param n_connections Number of connections.
 475  * @param channels Channels.
 476  * @param connections Connections.
 477  * @param estate Encryption state.
 478  * @param cstate Connectivity state.
 479  */
 480 typedef void
 481 (*GNUNET_CADET_TunnelCB) (void *cls,
 482                           const struct GNUNET_PeerIdentity *peer,
 483                           unsigned int n_channels,
 484                           unsigned int n_connections,
 485                           uint32_t *channels,
 486                           struct GNUNET_CADET_Hash *connections,
 487                           unsigned int estate,
 488                           unsigned int cstate);
 489
 490
 491 /**
 492  * Request information about a specific channel of the running cadet peer.
 493  *
 494  * WARNING: unstable API, likely to change in the future!
 495  *
 496  * @param h Handle to the cadet peer.
 497  * @param peer ID of the other end of the channel.
 498  * @param channel_number Channel number.
 499  * @param callback Function to call with the requested data.
 500  * @param callback_cls Closure for @c callback.
 501  */
 502 void
 503 GNUNET_CADET_get_channel (struct GNUNET_CADET_Handle *h,
 504                           struct GNUNET_PeerIdentity *peer,
 505                           uint32_t channel_number,
 506                           GNUNET_CADET_ChannelCB callback,
 507                           void *callback_cls);
 508
 509
 510 /**
 511  * Request a debug dump on the service's STDERR.
 512  *
 513  * WARNING: unstable API, likely to change in the future!
 514  *
 515  * @param h cadet handle
 516  */
 517 void
 518 GNUNET_CADET_request_dump (struct GNUNET_CADET_Handle *h);
 519
 520
 521 /**
 522  * Request information about peers known to the running cadet service.
 523  * The callback will be called for every peer known to the service.
 524  * Only one info request (of any kind) can be active at once.
 525  *
 526  *
 527  * WARNING: unstable API, likely to change in the future!
 528  *
 529  * @param h Handle to the cadet peer.
 530  * @param callback Function to call with the requested data.
 531  * @param callback_cls Closure for @c callback.
 532  *
 533  * @return #GNUNET_OK / #GNUNET_SYSERR
 534  */
 535 int
 536 GNUNET_CADET_get_peers (struct GNUNET_CADET_Handle *h,
 537                         GNUNET_CADET_PeersCB callback,
 538                         void *callback_cls);
 539
 540
 541 /**
 542  * Cancel a peer info request. The callback will not be called (anymore).
 543  *
 544  * WARNING: unstable API, likely to change in the future!
 545  *
 546  * @param h Cadet handle.
 547  *
 548  * @return Closure that was given to #GNUNET_CADET_get_peers().
 549  */
 550 void *
 551 GNUNET_CADET_get_peers_cancel (struct GNUNET_CADET_Handle *h);
 552
 553
 554 /**
 555  * Request information about a peer known to the running cadet peer.
 556  * The callback will be called for the tunnel once.
 557  * Only one info request (of any kind) can be active at once.
 558  *
 559  * WARNING: unstable API, likely to change in the future!
 560  *
 561  * @param h Handle to the cadet peer.
 562  * @param id Peer whose tunnel to examine.
 563  * @param callback Function to call with the requested data.
 564  * @param callback_cls Closure for @c callback.
 565  *
 566  * @return #GNUNET_OK / #GNUNET_SYSERR
 567  */
 568 int
 569 GNUNET_CADET_get_peer (struct GNUNET_CADET_Handle *h,
 570                       const struct GNUNET_PeerIdentity *id,
 571                       GNUNET_CADET_PeerCB callback,
 572                       void *callback_cls);
 573
 574
 575 /**
 576  * Request information about tunnels of the running cadet peer.
 577  * The callback will be called for every tunnel of the service.
 578  * Only one info request (of any kind) can be active at once.
 579  *
 580  * WARNING: unstable API, likely to change in the future!
 581  *
 582  * @param h Handle to the cadet peer.
 583  * @param callback Function to call with the requested data.
 584  * @param callback_cls Closure for @c callback.
 585  *
 586  * @return #GNUNET_OK / #GNUNET_SYSERR
 587  */
 588 int
 589 GNUNET_CADET_get_tunnels (struct GNUNET_CADET_Handle *h,
 590                           GNUNET_CADET_TunnelsCB callback,
 591                           void *callback_cls);
 592
 593
 594 /**
 595  * Cancel a monitor request. The monitor callback will not be called.
 596  *
 597  * @param h Cadet handle.
 598  *
 599  * @return Closure given to #GNUNET_CADET_get_tunnels(), if any.
 600  */
 601 void *
 602 GNUNET_CADET_get_tunnels_cancel (struct GNUNET_CADET_Handle *h);
 603
 604
 605 /**
 606  * Request information about a tunnel of the running cadet peer.
 607  * The callback will be called for the tunnel once.
 608  * Only one info request (of any kind) can be active at once.
 609  *
 610  * WARNING: unstable API, likely to change in the future!
 611  *
 612  * @param h Handle to the cadet peer.
 613  * @param id Peer whose tunnel to examine.
 614  * @param callback Function to call with the requested data.
 615  * @param callback_cls Closure for @c callback.
 616  *
 617  * @return #GNUNET_OK / #GNUNET_SYSERR
 618  */
 619 int
 620 GNUNET_CADET_get_tunnel (struct GNUNET_CADET_Handle *h,
 621                          const struct GNUNET_PeerIdentity *id,
 622                          GNUNET_CADET_TunnelCB callback,
 623                          void *callback_cls);
 624
 625
 626 /**
 627  * Create a message queue for a cadet channel.
 628  * The message queue can only be used to transmit messages,
 629  * not to receive them.
 630  *
 631  * @param channel the channel to create the message qeue for
 632  * @return a message queue to messages over the channel
 633  */
 634 struct GNUNET_MQ_Handle *
 635 GNUNET_CADET_mq_create (struct GNUNET_CADET_Channel *channel);
 636
 637
 638 #if 0                           /* keep Emacsens' auto-indent happy */
 639 {
 640 #endif
 641 #ifdef __cplusplus
 642 }
 643 #endif
 644
 645 /* ifndef GNUNET_CADET_SERVICE_H */
 646 #endif
 647
 648 /** @} */  /* end of group */
 649
 650 /* end of gnunet_cadet_service.h */