src/include/gnunet_core_service.h

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