src/include/gnunet_core_service.h

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