src/include/gnunet_multicast_service.h

   1 /*
   2      This file is part of GNUnet.
   3      (C) 2012, 2013 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., 59 Temple Place - Suite 330,
  18      Boston, MA 02111-1307, USA.
  19 */
  20
  21 /**
  22  * @file include/gnunet_multicast_service.h
  23  * @brief multicast service; establish tunnels to distant peers
  24  * @author Christian Grothoff
  25  * @author tg(x)
  26  */
  27
  28 #ifndef GNUNET_MULTICAST_SERVICE_H
  29 #define GNUNET_MULTICAST_SERVICE_H
  30
  31 #ifdef __cplusplus
  32 extern "C"
  33 {
  34 #if 0                           /* keep Emacsens' auto-indent happy */
  35 }
  36 #endif
  37 #endif
  38
  39 #include "gnunet_util_lib.h"
  40 #include "gnunet_transport_service.h"
  41
  42 /**
  43  * Version number of GNUnet-multicast API.
  44  */
  45 #define GNUNET_MULTICAST_VERSION 0x00000000
  46
  47
  48 /**
  49  * Opaque handle for a multicast group member.
  50  */
  51 struct GNUNET_MULTICAST_Member;
  52
  53 /**
  54  * Handle for the origin of a multicast group.
  55  */
  56 struct GNUNET_MULTICAST_Origin;
  57
  58 /**
  59  * Group membership policies.
  60  */
  61 enum GNUNET_MULTICAST_JoinPolicy
  62 {
  63   /**
  64    * Anyone can join the group, without announcing his presence;
  65    * all messages are always public and can be distributed freely.
  66    * Joins may be announced, but this is not required.
  67    */
  68   GNUNET_MULTICAST_JP_ANONYMOUS = 0,
  69
  70   /**
  71    * Origin must approve membership to the group, messages must only be
  72    * distributed to current group members.  This includes the group
  73    * state as well as transient messages.
  74    */
  75   GNUNET_MULTICAST_JP_PRIVATE = 1,
  76
  77 #if IDEAS_FOR_FUTURE
  78   /**
  79    * Anyone can freely join the group (no approval required); however,
  80    * transient messages must only be distributed to current group
  81    * members, so the origin must still acknowledge that the member
  82    * joined before transient messages are delivered.  As approval is
  83    * guaranteed, the presistent group state can be synchronized freely
  84    * immediately, prior to origin confirmation.
  85    */
  86   GNUNET_MULTICAST_JP_OPEN = 2,
  87
  88   /**
  89    * Origin must approve membership to the group, but past messages can be
  90    * freely distributed to members.
  91    */
  92   GNUNET_MULTICAST_JP_CLOSED = 3,
  93 #endif
  94
  95 };
  96
  97
  98 /**
  99  * Opaque handle to a replay request from the multicast service.
 100  */
 101 struct GNUNET_MULTICAST_ReplayHandle;
 102
 103
 104 /**
 105  * Functions with this signature are called whenever the multicast
 106  * service needs a message to be replayed.  Implementations of this
 107  * function MUST call GNUNET_MULTICAST_replay() ONCE (with a message
 108  * or an error); however, if the origin is destroyed or the group is
 109  * left, the replay handle must no longer be used.
 110  *
 111  * @param cls Closure (set from GNUNET_MULTICAST_origin_start()
 112  *            or GNUNET_MULTICAST_member_join()).
 113  * @param message_id Which message should be replayed.
 114  * @param rh Handle to pass to message transmit function.
 115  */
 116 typedef void (*GNUNET_MULTICAST_ReplayCallback) (void *cls,
 117                                                  uint64_t message_id,
 118                                                  struct GNUNET_MULTICAST_ReplayHandle *rh);
 119
 120
 121 /**
 122  * Possible error codes during replay.
 123  */
 124 enum GNUNET_MULTICAST_ReplayErrorCode
 125 {
 126
 127   /**
 128    * Everything is fine.
 129    */
 130   GNUNET_MULTICAST_REC_OK = 0,
 131
 132   /**
 133    * Message has been discarded (likely transient message that was too old).
 134    */
 135   GNUNET_MULTICAST_REC_TRANSIENT_LOST = 1,
 136
 137   /**
 138    * Message ID counter was larger than the highest counter this
 139    * replay function has ever encountered; thus it is likely the
 140    * origin never sent it and we're at the HEAD of the multicast
 141    * stream as far as this node is concerned.
 142    */
 143   GNUNET_MULTICAST_REC_PAST_HEAD = 2,
 144
 145   /**
 146    * Internal error (i.e. database error).  Try some other peer.
 147    */
 148   GNUNET_MULTICAST_REC_INTERNAL_ERROR = 3
 149
 150 };
 151
 152
 153 GNUNET_NETWORK_STRUCT_BEGIN
 154
 155 /**
 156  * Header of a multicast message.
 157  *
 158  * This format is public as the replay mechanism must replay messages using the
 159  * same format.  This is needed as we want to integrity-check messages within
 160  * the multicast layer to avoid multicasting mal-formed messages.
 161  */
 162 struct GNUNET_MULTICAST_MessageHeader
 163 {
 164
 165   /**
 166    * Header for all multicast messages from the origin.
 167    */
 168   struct GNUNET_MessageHeader header;
 169
 170   /**
 171    * Number of hops this message has taken since the origin.
 172    *
 173    * Helpful to determine shortest paths to the origin for responses among
 174    * honest peers; updated at each hop and thus not signed and not secure.
 175    */
 176   uint32_t hop_counter GNUNET_PACKED;
 177
 178   /**
 179    * ECC signature of the message.
 180    *
 181    * Signature must match the public key of the multicast group.
 182    */
 183   struct GNUNET_CRYPTO_EccSignature signature;
 184
 185   /**
 186    * Signature of the multicast message.
 187    */
 188   struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
 189
 190   /**
 191    * Number of the message, monotonically increasing.
 192    */
 193   uint64_t message_id GNUNET_PACKED;
 194
 195   /**
 196    * Counter that monotonically increases whenever a member leaves the group.
 197    *
 198    * It has significance in case of replay requests: when a member has missed
 199    * messages and gets a replay request: in this case if the @a group_generation
 200    * is still the same before and after the missed messages, it means that no
 201    * @e join or @a leave operations happened during the missed messages.
 202    */
 203   uint64_t group_generation GNUNET_PACKED;
 204
 205   /**
 206    * Difference between the current @a message_id and the @a message_id of the
 207    * preceeding non-transient message.
 208    *
 209    * Zero for transient messages, @c UINT64_MAX for the first message, or any
 210    * other message creating a full state reset by the origin.  By subtracting
 211    * @a state_delta from @a message_id, it is possible to calculate the message
 212    * ID of the preceeding non-transient message and thus quickly traverse all
 213    * state changes up to the last full state reset by the origin.  This is
 214    * useful as it allows joining clients to quickly reassemble the state while
 215    * skipping over transient messages (and doing so without having to trust
 216    * intermediaries to do it right, as the indices in the chain are signed).  If
 217    * the state chain is getting too long, the origin can choose to originate a
 218    * state message with a state_delta of UINT64_MAX, thereby starting a new
 219    * chain.  The origin will then have to re-create the full state with state
 220    * update messages following the state reset message.
 221    *
 222    * Open question: needed in multicast, or just have this in PSYC; still might
 223    * be useful for selective fetching of messages.  Still, that again should
 224    * that not be done by PSYC?
 225    */
 226   uint64_t state_delta GNUNET_PACKED;
 227
 228   /**
 229    * Header for the message body.
 230    *
 231    * Three message types are specifically understood by multicast, namely "peer
 232    * join", "peer leave", and "group terminated".  Multicast will use those
 233    * messages to update its list of candidates for content distribution.  All
 234    * other message types are application-specific.
 235    */
 236   struct GNUNET_MessageHeader body;
 237
 238   /* followed by message body */
 239 };
 240
 241 GNUNET_NETWORK_STRUCT_END
 242
 243
 244 /**
 245  * Replay a message from the multicast group.
 246  *
 247  * @param rh Replay handle identifying which replay operation was requested.
 248  * @param msg Replayed message, NULL if unknown/error.
 249  * @param ec Error code.
 250  */
 251 void
 252 GNUNET_MULTICAST_replay (struct GNUNET_MULTICAST_ReplayHandle *rh,
 253                          const struct GNUNET_MULTICAST_MessageHeader *msg,
 254                          enum GNUNET_MULTICAST_ReplayErrorCode ec);
 255
 256
 257 /**
 258  * Handle that identifies a join request.
 259  *
 260  * Used to match calls to #GNUNET_MULTICAST_MembershipChangeCallback to the
 261  * corresponding calls to GNUNET_MULTICAST_join_decision().
 262  */
 263 struct GNUNET_MULTICAST_JoinHande;
 264
 265
 266 /**
 267  * Function to call with the decision made for a membership change request.
 268  *
 269  * Must be called once and only once in response to an invocation of the
 270  * #GNUNET_MULTICAST_MembershipChangeCallback.
 271  *
 272  * @param jh Join request handle.
 273  * @param join_response Message to send in response to the joining peer;
 274  *        can also be used to redirect the peer to a different group at the
 275  *        application layer; this response is to be transmitted to the
 276  *        peer that issued the request even if admission is denied.
 277  * @param is_admitted #GNUNET_OK if joining is approved,
 278  *        #GNUNET_SYSERR if it is disapproved;
 279  *        #GNUNET_NO for peers leaving.
 280  * @param relay_count Number of relays given.
 281  * @param relays Array of suggested peers that might be useful relays to use
 282  *        when joining the multicast group (essentially a list of peers that
 283  *        are already part of the multicast group and might thus be willing
 284  *        to help with routing).  If empty, only this local peer (which must
 285  *        be the multicast origin) is a good candidate for building the
 286  *        multicast tree.  Note that it is unnecessary to specify our own
 287  *        peer identity in this array.
 288  */
 289 void
 290 GNUNET_MULTICAST_join_decision (struct GNUNET_MULTICAST_JoinHandle *jh,
 291                                 const struct GNUNET_MessageHeader *join_response,
 292                                 int is_admitted,
 293                                 unsigned int relay_count,
 294                                 const struct GNUNET_PeerIdentity *relays);
 295
 296
 297 /**
 298  * Method called whenever another peer wants to join or has left a multicast
 299  * group.
 300  *
 301  * Implementations of this function must call GNUNET_MULTICAST_join_decision()
 302  * with the decision.
 303  *
 304  * @param cls Closure.
 305  * @param peer Identity of the peer that wants to join or leave.
 306  * @param join_req Application-dependent join message from the new user
 307  *        (might, for example, contain a user,
 308  *        bind user identity/pseudonym to peer identity, application-level
 309  *        message to origin, etc.).
 310  * @param is_joining #GNUNET_YES if the peer wants to join, #GNUNET_NO if the peer left.
 311  * @param jh Join handle to pass to GNUNET_MULTICAST_join_decison().
 312  */
 313 typedef void (*GNUNET_MULTICAST_MembershipChangeCallback)(void *cls,
 314                                                           const struct GNUNET_PeerIdentity *peer,
 315                                                           const struct GNUNET_MessageHeader *join_req,
 316                                                           int is_joining,
 317                                                           struct GNUNET_MULTICAST_JoinHandle *jh);
 318
 319
 320 /**
 321  * Handle to pass back for the answer of a membership test.
 322  */
 323 struct GNUNET_MULTICAST_MembershipTestHandle;
 324
 325
 326 /**
 327  * Call informing multicast about the decision taken for membership test.
 328  *
 329  * @param mth Handle that was given for the query.
 330  * @param decision #GNUNET_YES if peer was a member, #GNUNET_NO if peer was not a member,
 331  *         #GNUNET_SYSERR if we cannot answer the membership test.
 332  */
 333 void
 334 GNUNET_MULTICAST_membership_test_answer (struct GNUNET_MULTICAST_MembershipTestHandle *mth,
 335                                          int decision);
 336
 337
 338 /**
 339  * Method called to test if a member was in the group at a particular time.
 340  *
 341  * @param cls Closure.
 342  * @param peer Identity of the peer that we want to test.
 343  * @param message_id Message ID for which we want to do the test.
 344  * @param mth Handle to give to GNUNET_MULTICAST_membership_test_answer().
 345  */
 346 typedef void (*GNUNET_MULTICAST_MembershipTestCallback)(void *cls,
 347                                                         const struct GNUNET_PeerIdentity *peer,
 348                                                         uint64_t message_id,
 349                                                         struct GNUNET_MULTICAST_MembershipTestHandle *mth);
 350
 351
 352 /**
 353  * Function called whenever a group member has transmitted a message
 354  * to the origin (other than joining or leaving).
 355  *
 356  * @param cls Closure (set from GNUNET_MULTICAST_origin_start).
 357  * @param sender Identity of the sender.
 358  * @param response_id Unique counter for the response from this sender to this origin.
 359  * @param msg Message to the origin.
 360  */
 361 typedef void (*GNUNET_MULTICAST_ResponseCallback) (void *cls,
 362                                                    const struct GNUNET_PeerIdentity *sender,
 363                                                    uint64_t response_id,
 364                                                    const struct GNUNET_MessageHeader *msg);
 365
 366
 367 /**
 368  * Function called whenever a group member is receiving a message from
 369  * the origin.  If admission to the group is denied, this function is
 370  * called once with the response of the @e origin (as given to
 371  * GNUNET_MULTICAST_join_decision()) and then a second time with NULL
 372  * to indicate that the connection failed for good.
 373  *
 374  * @param cls Closure (set from GNUNET_MULTICAST_member_join())
 375  * @param message_id Unique number of the message, 0 for response to join request,
 376  *        normal message IDs in either direction start at 1.
 377  * @param msg Message from the origin, NULL if the origin shut down
 378  *        (or we were kicked out, and we should thus call
 379  *        GNUNET_MULTICAST_member_leave() next)
 380  */
 381 typedef void (*GNUNET_MULTICAST_MulticastMessageCallback) (void *cls,
 382                                                            uint64_t message_id,
 383                                                            const struct GNUNET_MULTICAST_MessageHeader *msg);
 384
 385
 386 /**
 387  * Start a multicast group.
 388  *
 389  * Will advertise the origin in the P2P overlay network under the respective
 390  * public key so that other peer can find this peer to join it.  Peers that
 391  * issue GNUNET_MULTICAST_member_join() can then transmit a join request to
 392  * either an existing group member (if the @a join_policy is permissive) or to
 393  * the origin.  If the joining is approved, the member is cleared for @e replay
 394  * and will begin to receive messages transmitted to the group.  If joining is
 395  * disapproved, the failed candidate will be given a response.  Members in the
 396  * group can send messages to the origin (one at a time).
 397  *
 398  * @param cfg Configuration to use.
 399  * @param cls Closure for the various callbacks that follow.
 400  * @param priv_key ECC key that will be used to sign messages for this
 401  *                 multicast session; public key is used to identify the
 402  *                 multicast group; FIXME: we'll likely want to use
 403  *                 NOT the p521 curve here, but a cheaper one in the future.
 404  * @param join_policy What is the membership policy of the group?
 405  * @param replay_cb Function that can be called to replay a message.
 406  * @param test_cb Function multicast can use to test group membership.
 407  * @param join_cb Function called to approve / disapprove joining of a peer,
 408  *                and to inform about a leaving member.
 409  * @param leave_cb Function called to inform about a leaving member.
 410  * @param response_cb Function called with messages from group members.
 411  * @return Handle for the origin, NULL on error.
 412  */
 413 struct GNUNET_MULTICAST_Origin *
 414 GNUNET_MULTICAST_origin_start (const struct GNUNET_CONFIGURATION_Handle *cfg,
 415                                void *cls,
 416                                const struct GNUNET_CRYPTO_EccPrivateKey *priv_key,
 417                                enum GNUNET_MULTICAST_JoinPolicy join_policy,
 418                                GNUNET_MULITCAST_ReplayCallback replay_cb,
 419                                GNUNET_MULITCAST_MembershipTestCallback test_cb,
 420                                GNUNET_MULTICAST_MembershipChangeCallback join_cb,
 421                                GNUNET_MULTICAST_ResponseCallback response_cb);
 422
 423
 424 /**
 425  * Handle for a request to send a message to all multicast group members
 426  * (from the origin).
 427  */
 428 struct GNUNET_MULTICAST_MulticastRequest;
 429
 430
 431 /**
 432  * Send a message to the multicast group.
 433  *
 434  * @param origin Handle to the multicast group.
 435  * @param size Number of bytes to transmit.
 436  * @param cb Function to call to get the message.
 437  * @param cb_cls Closure for @a cb.
 438  * @return NULL on error (i.e. request already pending).
 439  */
 440 struct GNUNET_MULTICAST_MulticastRequest *
 441 GNUNET_MULTICAST_origin_to_all (struct GNUNET_MULTICAST_Origin *origin,
 442                                 size_t size,
 443                                 GNUNET_CONNECTION_TransmitReadyNotify cb,
 444                                 void *cb_cls);
 445
 446
 447 /**
 448  * Cancel request for message transmission to multicast group.
 449  *
 450  * @param mr Request to cancel.
 451  */
 452 void
 453 GNUNET_MULTICAST_origin_to_all_cancel (struct GNUNET_MULTICAST_MulticastRequest *mr);
 454
 455
 456 /**
 457  * End a multicast group.
 458  *
 459  * @param origin multicast group to terminate
 460  */
 461 void
 462 GNUNET_MULTICAST_origin_end (struct GNUNET_MULTICAST_Origin *origin);
 463
 464
 465 /**
 466  * Join a multicast group.
 467  *
 468  * The entity joining is always the local peer.  Further information about the
 469  * candidate can be provided in the @a join_req message.  If the join fails, the
 470  * @a message_cb is invoked with a (failure) response and then with NULL.  If
 471  * the join succeeds, outstanding (state) messages and ongoing multicast
 472  * messages will be given to the @a message_cb until the member decides to leave
 473  * the group.  The @a test_cb and @a replay_cb functions may be called at
 474  * anytime by the multicast service to support relaying messages to other
 475  * members of the group.
 476  *
 477  * @param cfg Configuration to use.
 478  * @param cls Closure for callbacks.
 479  * @param pub_key ECC key that identifies the group.
 480  * @param max_known_message_id Largest known message ID to the replay service;
 481  *        all messages with IDs larger than this ID will be replayed if
 482  *        possible (lower IDs will be considered known and thus only
 483  *        be replayed upon explicit request).
 484  * @param max_known_state_message_id Largest known message ID with a non-zero
 485  *        value for the @e state_delta; state messages with
 486  *        larger IDs than this value will be replayed with high priority
 487  *        (lower IDs will be considered known and thus only
 488  *        be replayed upon explicit request).
 489  * @param replay_cb Function that can be called to replay messages
 490  *        this peer already knows from this group; NULL if this
 491  *        client is unable to support replay.
 492  * @param test_cb Function multicast can use to test group membership.
 493  * @param message_cb Function to be called for all messages we
 494  *        receive from the group, excluding those our @a replay_cb
 495  *        already has.
 496  * @param join_req Application-dependent join message to be passed to origin
 497  *        (might, for example, contain a user
 498  *        bind user identity/pseudonym to peer identity, application-level
 499  *        message to origin, etc.).
 500  * @return Handle for the member, NULL on error.
 501  */
 502 struct GNUNET_MULTICAST_Member *
 503 GNUNET_MULTICAST_member_join (const struct GNUNET_CONFIGURATION_Handle *cfg,
 504                               void *cls,
 505                               const struct GNUNET_CRYPTO_EccPublicKey *pub_key,
 506                               uint64_t max_known_message_id,
 507                               uint64_t max_known_state_message_id,
 508                               GNUNET_MULTICAST_ReplayCallback replay_cb,
 509                               GNUNET_MULITCAST_MembershipTestCallback test_cb,
 510                               GNUNET_MULTICAST_MulticastMessageCallback message_cb,
 511                               const struct GNUNET_MessageHeader *join_req);
 512
 513
 514 /**
 515  * Handle for a replay request.
 516  */
 517 struct GNUNET_MULTICAST_ReplayRequest;
 518
 519
 520 /**
 521  * Request a message to be replayed.
 522  *
 523  * Useful if messages below the @e max_known_*_id's given when joining are
 524  * needed and not known to the client.
 525  *
 526  * @param member Membership handle.
 527  * @param message_id ID of a message that this client would like to see replayed.
 528  * @param message_cb Function to be called for the replayed message.
 529  * @param message_cb_cls Closure for @a message_cb.
 530  * @return Replay request handle, NULL on error.
 531  */
 532 struct GNUNET_MULTICAST_ReplayRequest *
 533 GNUNET_MULTICAST_member_request_replay (struct GNUNET_MULTICAST_Member *member,
 534                                         uint64_t message_id,
 535                                         GNUNET_MULTICAST_MulticastMessageCallback message_cb,
 536                                         void *message_cb_cls);
 537
 538
 539 /**
 540  * Cancel a replay request.
 541  *
 542  * @param rr Request to cancel.
 543  */
 544 void
 545 GNUNET_MULTICAST_member_request_replay_cancel (struct GNUNET_MULTICAST_ReplayRequest *rr);
 546
 547
 548 /**
 549  * Leave a multicast group.
 550  *
 551  * @param member Membership handle.
 552  */
 553 void
 554 GNUNET_MULTICAST_member_leave (struct GNUNET_MULTICAST_Member *member);
 555
 556
 557 /**
 558  * Handle for a message to be delivered to the origin.
 559  */
 560 struct GNUNET_MULTICAST_ResponseRequest;
 561
 562
 563 /**
 564  * Send a message to the origin of the multicast group.
 565  *
 566  * @param member Membership handle.
 567  * @param size Number of bytes we want to send to origin.
 568  * @param cb Callback to call to get the message.
 569  * @param cb_cls Closure for @a cb.
 570  * @return Handle to cancel request, NULL on error (i.e. request already pending).
 571  */
 572 struct GNUNET_MULTICAST_ResponseRequest *
 573 GNUNET_MULTICAST_member_to_origin (struct GNUNET_MULTICAST_Member *member,
 574                                    size_t size,
 575                                    GNUNET_CONNECTION_TransmitReadyNotify cb,
 576                                    void *cb_cls);
 577
 578
 579 /**
 580  * Cancel request for message transmission to origin.
 581  *
 582  * @param rr Request to cancel.
 583  */
 584 void
 585 GNUNET_MULTICAST_member_to_origin_cancel (struct GNUNET_MULTICAST_ResponseRequest *rr);
 586
 587
 588
 589 #if 0                           /* keep Emacsens' auto-indent happy */
 590 {
 591 #endif
 592 #ifdef __cplusplus
 593 }
 594 #endif
 595
 596 /* ifndef GNUNET_MULTICAST_SERVICE_H */
 597 #endif
 598 /* end of gnunet_multicast_service.h */