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