src/include/gnunet_core_service.h

   1 /*
   2      This file is part of GNUnet.
   3      (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., 59 Temple Place - Suite 330,
  18      Boston, MA 02111-1307, USA.
  19 */
  20
  21 /**
  22  * @file include/gnunet_core_service.h
  23  * @brief core service; this is the main API for encrypted P2P
  24  *        communications
  25  * @author Christian Grothoff
  26  * @defgroup core encrypted direct communication between peers
  27  * @{
  28  */
  29 #ifndef GNUNET_CORE_SERVICE_H
  30 #define GNUNET_CORE_SERVICE_H
  31
  32 #ifdef __cplusplus
  33 extern "C"
  34 {
  35 #if 0                           /* keep Emacsens' auto-indent happy */
  36 }
  37 #endif
  38 #endif
  39
  40 #include "gnunet_util_lib.h"
  41 #include "gnunet_transport_service.h"
  42
  43 /**
  44  * Version number of GNUnet-core API.
  45  */
  46 #define GNUNET_CORE_VERSION 0x00000001
  47
  48 /**
  49  * Traffic priorities.
  50  */
  51 enum GNUNET_CORE_Priority
  52 {
  53
  54   /**
  55    * Lowest priority, i.e. background traffic (i.e. fs)
  56    */
  57   GNUNET_CORE_PRIO_BACKGROUND = 0,
  58
  59   /**
  60    * Normal traffic (i.e. cadet/dv relay, DHT)
  61    */
  62   GNUNET_CORE_PRIO_BEST_EFFORT = 1,
  63
  64   /**
  65    * Urgent traffic (local peer, i.e. conversation).
  66    */
  67   GNUNET_CORE_PRIO_URGENT = 2,
  68
  69   /**
  70    * Highest priority, control traffic (i.e. NSE, Core/Cadet KX).
  71    */
  72   GNUNET_CORE_PRIO_CRITICAL_CONTROL = 3
  73
  74
  75 };
  76
  77
  78 /**
  79  * Opaque handle to the service.
  80  */
  81 struct GNUNET_CORE_Handle;
  82
  83
  84 /**
  85  * Method called whenever a given peer connects.
  86  *
  87  * @param cls closure
  88  * @param peer peer identity this notification is about
  89  */
  90 typedef void
  91 (*GNUNET_CORE_ConnectEventHandler) (void *cls,
  92                                     const struct GNUNET_PeerIdentity *peer);
  93
  94
  95 /**
  96  * Method called whenever a peer disconnects.
  97  *
  98  * @param cls closure
  99  * @param peer peer identity this notification is about
 100  */
 101 typedef void
 102 (*GNUNET_CORE_DisconnectEventHandler) (void *cls,
 103                                        const struct GNUNET_PeerIdentity *peer);
 104
 105
 106 /**
 107  * Functions with this signature are called whenever a message is
 108  * received or transmitted.
 109  *
 110  * @param cls closure (set from #GNUNET_CORE_connect)
 111  * @param peer the other peer involved (sender or receiver, NULL
 112  *        for loopback messages where we are both sender and receiver)
 113  * @param message the actual message
 114  * @return #GNUNET_OK to keep the connection open,
 115  *         #GNUNET_SYSERR to close connection to the peer (signal serious error)
 116  */
 117 typedef int
 118 (*GNUNET_CORE_MessageCallback) (void *cls,
 119                                 const struct GNUNET_PeerIdentity *other,
 120                                 const struct GNUNET_MessageHeader *message);
 121
 122
 123 /**
 124  * Message handler.  Each struct specifies how to handle on particular
 125  * type of message received.
 126  */
 127 struct GNUNET_CORE_MessageHandler
 128 {
 129   /**
 130    * Function to call for messages of @e type.
 131    */
 132   GNUNET_CORE_MessageCallback callback;
 133
 134   /**
 135    * Type of the message this handler covers.
 136    */
 137   uint16_t type;
 138
 139   /**
 140    * Expected size of messages of this type.  Use 0 for variable-size.
 141    * If non-zero, messages of the given type will be discarded if they
 142    * do not have the right size.
 143    */
 144   uint16_t expected_size;
 145
 146 };
 147
 148
 149 /**
 150  * Function called after #GNUNET_CORE_connect has succeeded (or failed
 151  * for good).  Note that the private key of the peer is intentionally
 152  * not exposed here; if you need it, your process should try to read
 153  * the private key file directly (which should work if you are
 154  * authorized...).  Implementations of this function must not call
 155  * #GNUNET_CORE_disconnect (other than by scheduling a new task to
 156  * do this later).
 157  *
 158  * @param cls closure
 159  * @param my_identity ID of this peer, NULL if we failed
 160  */
 161 typedef void
 162 (*GNUNET_CORE_StartupCallback) (void *cls,
 163                                 const struct GNUNET_PeerIdentity *my_identity);
 164
 165
 166 /**
 167  * Connect to the core service.  Note that the connection may complete
 168  * (or fail) asynchronously.  This function primarily causes the given
 169  * callback notification functions to be invoked whenever the
 170  * specified event happens.  The maximum number of queued
 171  * notifications (queue length) is per client; the queue is shared
 172  * across all types of notifications.  So a slow client that registers
 173  * for @a outbound_notify also risks missing @a inbound_notify messages.
 174  * Certain events (such as connect/disconnect notifications) are not
 175  * subject to queue size limitations.
 176  *
 177  * @param cfg configuration to use
 178  * @param cls closure for the various callbacks that follow (including handlers in the handlers array)
 179  * @param init callback to call once we have successfully
 180  *        connected to the core service
 181  * @param connects function to call on peer connect, can be NULL
 182  * @param disconnects function to call on peer disconnect / timeout, can be NULL
 183  * @param inbound_notify function to call for all inbound messages, can be NULL
 184  *                note that the core is allowed to drop notifications about inbound
 185  *                messages if the client does not process them fast enough (for this
 186  *                notification type, a bounded queue is used)
 187  * @param inbound_hdr_only set to #GNUNET_YES if @a inbound_notify will only read the
 188  *                `struct GNUNET_MessageHeader` and hence we do not need to give it the full message;
 189  *                can be used to improve efficiency, ignored if inbound_notify is NULL
 190  *                note that the core is allowed to drop notifications about inbound
 191  *                messages if the client does not process them fast enough (for this
 192  *                notification type, a bounded queue is used)
 193  * @param outbound_notify function to call for all outbound messages, can be NULL;
 194  *                note that the core is allowed to drop notifications about outbound
 195  *                messages if the client does not process them fast enough (for this
 196  *                notification type, a bounded queue is used)
 197  * @param outbound_hdr_only set to #GNUNET_YES if @a outbound_notify will only read the
 198  *                `struct GNUNET_MessageHeader` and hence we do not need to give it the full message
 199  *                can be used to improve efficiency, ignored if outbound_notify is NULL
 200  *                note that the core is allowed to drop notifications about outbound
 201  *                messages if the client does not process them fast enough (for this
 202  *                notification type, a bounded queue is used)
 203  * @param handlers callbacks for messages we care about, NULL-terminated
 204  *                note that the core is allowed to drop notifications about inbound
 205  *                messages if the client does not process them fast enough (for this
 206  *                notification type, a bounded queue is used)
 207  * @return handle to the core service (only useful for disconnect until @a init is called),
 208  *           NULL on error (in this case, init is never called)
 209  */
 210 struct GNUNET_CORE_Handle *
 211 GNUNET_CORE_connect (const struct GNUNET_CONFIGURATION_Handle *cfg,
 212                      void *cls,
 213                      GNUNET_CORE_StartupCallback init,
 214                      GNUNET_CORE_ConnectEventHandler connects,
 215                      GNUNET_CORE_DisconnectEventHandler disconnects,
 216                      GNUNET_CORE_MessageCallback inbound_notify,
 217                      int inbound_hdr_only,
 218                      GNUNET_CORE_MessageCallback outbound_notify,
 219                      int outbound_hdr_only,
 220                      const struct GNUNET_CORE_MessageHandler *handlers);
 221
 222
 223 /**
 224  * Disconnect from the core service.    This function can only
 225  * be called *after* all pending #GNUNET_CORE_notify_transmit_ready
 226  * requests have been explicitly cancelled.
 227  *
 228  * @param handle connection to core to disconnect
 229  */
 230 void
 231 GNUNET_CORE_disconnect (struct GNUNET_CORE_Handle *handle);
 232
 233
 234 /**
 235  * Handle for a transmission request.
 236  */
 237 struct GNUNET_CORE_TransmitHandle;
 238
 239
 240 /**
 241  * Ask the core to call @a notify once it is ready to transmit the
 242  * given number of bytes to the specified @a target.  Must only be
 243  * called after a connection to the respective peer has been
 244  * established (and the client has been informed about this).  You may
 245  * have one request of this type pending for each connected peer at
 246  * any time.  If a peer disconnects, the application MUST call
 247  * #GNUNET_CORE_notify_transmit_ready_cancel() on the respective
 248  * transmission request, if one such request is pending.
 249  *
 250  * @param handle connection to core service
 251  * @param cork is corking allowed for this transmission?
 252  * @param priority how important is the message?
 253  * @param maxdelay how long can the message wait? Only effective if @a cork is #GNUNET_YES
 254  * @param target who should receive the message, never NULL (can be this peer's identity for loopback)
 255  * @param notify_size how many bytes of buffer space does @a notify want?
 256  * @param notify function to call when buffer space is available;
 257  *        will be called with NULL on timeout; clients MUST cancel
 258  *        all pending transmission requests DURING the disconnect
 259  *        handler
 260  * @param notify_cls closure for @a notify
 261  * @return non-NULL if the notify callback was queued,
 262  *         NULL if we can not even queue the request (request already pending);
 263  *         if NULL is returned, @a notify will NOT be called.
 264  */
 265 struct GNUNET_CORE_TransmitHandle *
 266 GNUNET_CORE_notify_transmit_ready (struct GNUNET_CORE_Handle *handle,
 267                                    int cork,
 268                                    enum GNUNET_CORE_Priority priority,
 269                                    struct GNUNET_TIME_Relative maxdelay,
 270                                    const struct GNUNET_PeerIdentity *target,
 271                                    size_t notify_size,
 272                                    GNUNET_CONNECTION_TransmitReadyNotify notify,
 273                                    void *notify_cls);
 274
 275
 276 /**
 277  * Cancel the specified transmission-ready notification.
 278  *
 279  * @param th handle that was returned by "notify_transmit_ready".
 280  */
 281 void
 282 GNUNET_CORE_notify_transmit_ready_cancel (struct GNUNET_CORE_TransmitHandle *th);
 283
 284
 285 /**
 286  * Handle to a CORE monitoring operation.
 287  */
 288 struct GNUNET_CORE_MonitorHandle;
 289
 290
 291 /**
 292  * State machine for our P2P encryption handshake.  Everyone starts in
 293  * #GNUNET_CORE_KX_STATE_DOWN, if we receive the other peer's key
 294  * (other peer initiated) we start in state
 295  * #GNUNET_CORE_KX_STATE_KEY_RECEIVED (since we will immediately send
 296  * our own); otherwise we start in #GNUNET_CORE_KX_STATE_KEY_SENT.  If
 297  * we get back a PONG from within either state, we move up to
 298  * #GNUNET_CORE_KX_STATE_UP (the PONG will always be sent back
 299  * encrypted with the key we sent to the other peer).  Eventually,
 300  * we will try to rekey, for this we will enter
 301  * #GNUNET_CORE_KX_STATE_REKEY_SENT until the rekey operation is
 302  * confirmed by a PONG from the other peer.
 303  */
 304 enum GNUNET_CORE_KxState
 305 {
 306   /**
 307    * No handshake yet.
 308    */
 309   GNUNET_CORE_KX_STATE_DOWN,
 310
 311   /**
 312    * We've sent our session key.
 313    */
 314   GNUNET_CORE_KX_STATE_KEY_SENT,
 315
 316   /**
 317    * We've received the other peers session key.
 318    */
 319   GNUNET_CORE_KX_STATE_KEY_RECEIVED,
 320
 321   /**
 322    * The other peer has confirmed our session key + PING with a PONG
 323    * message encrypted with his session key (which we got).  Key
 324    * exchange is done.
 325    */
 326   GNUNET_CORE_KX_STATE_UP,
 327
 328   /**
 329    * We're rekeying (or had a timeout), so we have sent the other peer
 330    * our new ephemeral key, but we did not get a matching PONG yet.
 331    * This is equivalent to being #GNUNET_CORE_KX_STATE_KEY_RECEIVED,
 332    * except that the session is marked as 'up' with sessions (as we
 333    * don't want to drop and re-establish P2P connections simply due to
 334    * rekeying).
 335    */
 336   GNUNET_CORE_KX_STATE_REKEY_SENT,
 337
 338   /**
 339    * Last state of a KX (when it is being terminated).  Set
 340    * just before CORE frees the internal state for this peer.
 341    */
 342   GNUNET_CORE_KX_PEER_DISCONNECT,
 343
 344   /**
 345    * This is not a state in a peer's state machine, but a special
 346    * value used with the #GNUNET_CORE_MonitorCallback to indicate
 347    * that we finished the initial iteration over the peers.
 348    */
 349   GNUNET_CORE_KX_ITERATION_FINISHED,
 350
 351   /**
 352    * This is not a state in a peer's state machine, but a special
 353    * value used with the #GNUNET_CORE_MonitorCallback to indicate
 354    * that we lost the connection to the CORE service (and will try
 355    * to reconnect).  If this happens, most likely the CORE service
 356    * crashed and thus all connection state should be assumed lost.
 357    */
 358   GNUNET_CORE_KX_CORE_DISCONNECT
 359
 360 };
 361
 362
 363 /**
 364  * Function called by the monitor callback whenever
 365  * a peer's connection status changes.
 366  *
 367  * @param cls closure
 368  * @param pid identity of the peer this update is about
 369  * @param state current key exchange state of the peer
 370  * @param timeout when does the current state expire
 371  */
 372 typedef void
 373 (*GNUNET_CORE_MonitorCallback)(void *cls,
 374                                const struct GNUNET_PeerIdentity *pid,
 375                                enum GNUNET_CORE_KxState state,
 376                                struct GNUNET_TIME_Absolute timeout);
 377
 378
 379 /**
 380  * Monitor connectivity and KX status of all peers known to CORE.
 381  * Calls @a peer_cb with the current status for each connected peer,
 382  * and then once with NULL to indicate that all peers that are
 383  * currently active have been handled.  After that, the iteration
 384  * continues until it is cancelled.  Normal users of the CORE API are
 385  * not expected to use this function.  It is different in that it
 386  * truly lists all connections (including those where the KX is in
 387  * progress), not just those relevant to the application.  This
 388  * function is used by special applications for diagnostics.
 389  *
 390  * @param cfg configuration handle
 391  * @param peer_cb function to call with the peer information
 392  * @param peer_cb_cls closure for @a peer_cb
 393  * @return NULL on error
 394  */
 395 struct GNUNET_CORE_MonitorHandle *
 396 GNUNET_CORE_monitor_start (const struct GNUNET_CONFIGURATION_Handle *cfg,
 397                            GNUNET_CORE_MonitorCallback peer_cb,
 398                            void *peer_cb_cls);
 399
 400
 401 /**
 402  * Stop monitoring CORE activity.
 403  *
 404  * @param mh monitor to stop
 405  */
 406 void
 407 GNUNET_CORE_monitor_stop (struct GNUNET_CORE_MonitorHandle *mh);
 408
 409
 410 /**
 411  * Check if the given peer is currently connected. This function is for special
 412  * cirumstances (GNUNET_TESTBED uses it), normal users of the CORE API are
 413  * expected to track which peers are connected based on the connect/disconnect
 414  * callbacks from #GNUNET_CORE_connect.  This function is NOT part of the
 415  * 'versioned', 'official' API.  This function returns
 416  * synchronously after looking in the CORE API cache.
 417  *
 418  * @param h the core handle
 419  * @param pid the identity of the peer to check if it has been connected to us
 420  * @return #GNUNET_YES if the peer is connected to us; #GNUNET_NO if not
 421  */
 422 int
 423 GNUNET_CORE_is_peer_connected_sync (const struct GNUNET_CORE_Handle *h,
 424                                     const struct GNUNET_PeerIdentity *pid);
 425
 426
 427 /**
 428  * Create a message queue for sending messages to a peer with CORE.
 429  * Messages may only be queued with #GNUNET_MQ_send once the init callback has
 430  * been called for the given handle.
 431  * There must only be one queue per peer for each core handle.
 432  * The message queue can only be used to transmit messages,
 433  * not to receive them.
 434  *
 435  * @param h the core handle
 436  * @param target the target peer for this queue, may not be NULL
 437  * @return a message queue for sending messages over the core handle
 438  *         to the target peer
 439  */
 440 struct GNUNET_MQ_Handle *
 441 GNUNET_CORE_mq_create (struct GNUNET_CORE_Handle *h,
 442                        const struct GNUNET_PeerIdentity *target);
 443
 444
 445 #if 0                           /* keep Emacsens' auto-indent happy */
 446 {
 447 #endif
 448 #ifdef __cplusplus
 449 }
 450 #endif
 451
 452 /** @} */ /* end of group core */
 453
 454 /* ifndef GNUNET_CORE_SERVICE_H */
 455 #endif
 456 /* end of gnunet_core_service.h */