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