src/include/gnunet_core_service.h

   1 /*
   2      This file is part of GNUnet.
   3      Copyright (C) 2009-2017 GNUnet e.V.
   4
   5      GNUnet is free software: you can redistribute it and/or modify it
   6      under the terms of the GNU Affero General Public License as published
   7      by the Free Software Foundation, either version 3 of the License,
   8      or (at your 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      Affero General Public License for more details.
  14
  15      You should have received a copy of the GNU Affero General Public License
  16      along with this program.  If not, see <http://www.gnu.org/licenses/>.
  17 */
  18 /**
  19  * @author Christian Grothoff
  20  *
  21  * @file include/gnunet_core_service.h
  22  * Core service; the main API for encrypted P2P communications
  23  *
  24  * @defgroup core  Core service
  25  * Encrypted direct communication between peers
  26  *
  27  * @see [Documentation](https://gnunet.org/gnunet-core-subsystem)
  28  *
  29  * @{
  30  */
  31 #ifndef GNUNET_CORE_SERVICE_H
  32 #define GNUNET_CORE_SERVICE_H
  33
  34 #ifdef __cplusplus
  35 extern "C"
  36 {
  37 #if 0                           /* keep Emacsens' auto-indent happy */
  38 }
  39 #endif
  40 #endif
  41
  42 #include "gnunet_util_lib.h"
  43 #include "gnunet_transport_service.h"
  44
  45 /**
  46  * Version number of GNUnet-core API.
  47  */
  48 #define GNUNET_CORE_VERSION 0x00000001
  49
  50 /**
  51  * Traffic priorities.
  52  */
  53 enum GNUNET_CORE_Priority
  54 {
  55
  56   /**
  57    * Lowest priority, i.e. background traffic (i.e. fs)
  58    */
  59   GNUNET_CORE_PRIO_BACKGROUND = 0,
  60
  61   /**
  62    * Normal traffic (i.e. cadet/dv relay, DHT)
  63    */
  64   GNUNET_CORE_PRIO_BEST_EFFORT = 1,
  65
  66   /**
  67    * Urgent traffic (local peer, i.e. conversation).
  68    */
  69   GNUNET_CORE_PRIO_URGENT = 2,
  70
  71   /**
  72    * Highest priority, control traffic (i.e. NSE, Core/Cadet KX).
  73    */
  74   GNUNET_CORE_PRIO_CRITICAL_CONTROL = 3
  75
  76
  77 };
  78
  79
  80 /**
  81  * Opaque handle to the service.
  82  */
  83 struct GNUNET_CORE_Handle;
  84
  85
  86 /**
  87  * Method called whenever a given peer connects.
  88  *
  89  * @param cls closure
  90  * @param peer peer identity this notification is about
  91  * @return closure associated with @a peer. given to mq callbacks and
  92  *         #GNUNET_CORE_DisconnectEventHandler
  93  */
  94 typedef void *
  95 (*GNUNET_CORE_ConnectEventHandler) (void *cls,
  96                                     const struct GNUNET_PeerIdentity *peer,
  97                                     struct GNUNET_MQ_Handle *mq);
  98
  99
 100 /**
 101  * Method called whenever a peer disconnects.
 102  *
 103  * @param cls closure
 104  * @param peer peer identity this notification is about
 105  * @param peer_cls closure associated with peer. given in
 106  *        #GNUNET_CORE_ConnectEventHandler
 107  */
 108 typedef void
 109 (*GNUNET_CORE_DisconnectEventHandler) (void *cls,
 110                                        const struct GNUNET_PeerIdentity *peer,
 111                                        void *peer_cls);
 112
 113
 114 /**
 115  * Function called after #GNUNET_CORE_connect has succeeded (or failed
 116  * for good).  Note that the private key of the peer is intentionally
 117  * not exposed here; if you need it, your process should try to read
 118  * the private key file directly (which should work if you are
 119  * authorized...).  Implementations of this function must not call
 120  * #GNUNET_CORE_disconnect (other than by scheduling a new task to
 121  * do this later).
 122  *
 123  * @param cls closure
 124  * @param my_identity ID of this peer, NULL if we failed
 125  */
 126 typedef void
 127 (*GNUNET_CORE_StartupCallback) (void *cls,
 128                                 const struct GNUNET_PeerIdentity *my_identity);
 129
 130
 131 /**
 132  * Connect to the core service.  Note that the connection may complete
 133  * (or fail) asynchronously.  This function primarily causes the given
 134  * callback notification functions to be invoked whenever the
 135  * specified event happens.  The maximum number of queued
 136  * notifications (queue length) is per client; the queue is shared
 137  * across all types of notifications.  So a slow client that registers
 138  * for @a outbound_notify also risks missing @a inbound_notify messages.
 139  * Certain events (such as connect/disconnect notifications) are not
 140  * subject to queue size limitations.
 141  *
 142  * @param cfg configuration to use
 143  * @param cls closure for the various callbacks that follow (including handlers in the handlers array)
 144  * @param init callback to call once we have successfully
 145  *        connected to the core service
 146  * @param connects function to call on peer connect, can be NULL
 147  * @param disconnects function to call on peer disconnect / timeout, can be NULL
 148  * @param handlers callbacks for messages we care about, NULL-terminated
 149  *                note that the core is allowed to drop notifications about inbound
 150  *                messages if the client does not process them fast enough (for this
 151  *                notification type, a bounded queue is used)
 152  * @return handle to the core service (only useful for disconnect until @a init is called),
 153  *           NULL on error (in this case, init is never called)
 154  */
 155 struct GNUNET_CORE_Handle *
 156 GNUNET_CORE_connect (const struct GNUNET_CONFIGURATION_Handle *cfg,
 157                      void *cls,
 158                      GNUNET_CORE_StartupCallback init,
 159                      GNUNET_CORE_ConnectEventHandler connects,
 160                      GNUNET_CORE_DisconnectEventHandler disconnects,
 161                      const struct GNUNET_MQ_MessageHandler *handlers);
 162
 163
 164 /**
 165  * Disconnect from the core service.
 166  *
 167  * @param handle connection to core to disconnect
 168  */
 169 void
 170 GNUNET_CORE_disconnect (struct GNUNET_CORE_Handle *handle);
 171
 172
 173 /**
 174  * Inquire with CORE what options should be set for a message
 175  * so that it is transmitted with the given @a priority and
 176  * the given @a cork value.
 177  *
 178  * @param cork desired corking
 179  * @param priority desired message priority
 180  * @param[out] flags set to `flags` value for #GNUNET_MQ_set_options()
 181  * @return `extra` argument to give to #GNUNET_MQ_set_options()
 182  */
 183 const void *
 184 GNUNET_CORE_get_mq_options (int cork,
 185                             enum GNUNET_CORE_Priority priority,
 186                             uint64_t *flags);
 187
 188
 189 /**
 190  * Obtain the message queue for a connected peer.
 191  *
 192  * @param h the core handle
 193  * @param pid the identity of the peer
 194  * @return NULL if @a pid is not connected
 195  */
 196 struct GNUNET_MQ_Handle *
 197 GNUNET_CORE_get_mq (const struct GNUNET_CORE_Handle *h,
 198                     const struct GNUNET_PeerIdentity *pid);
 199
 200
 201 /**
 202  * Handle to a CORE monitoring operation.
 203  */
 204 struct GNUNET_CORE_MonitorHandle;
 205
 206
 207 /**
 208  * State machine for our P2P encryption handshake.  Everyone starts in
 209  * #GNUNET_CORE_KX_STATE_DOWN, if we receive the other peer's key
 210  * (other peer initiated) we start in state
 211  * #GNUNET_CORE_KX_STATE_KEY_RECEIVED (since we will immediately send
 212  * our own); otherwise we start in #GNUNET_CORE_KX_STATE_KEY_SENT.  If
 213  * we get back a PONG from within either state, we move up to
 214  * #GNUNET_CORE_KX_STATE_UP (the PONG will always be sent back
 215  * encrypted with the key we sent to the other peer).  Eventually,
 216  * we will try to rekey, for this we will enter
 217  * #GNUNET_CORE_KX_STATE_REKEY_SENT until the rekey operation is
 218  * confirmed by a PONG from the other peer.
 219  */
 220 enum GNUNET_CORE_KxState
 221 {
 222   /**
 223    * No handshake yet.
 224    */
 225   GNUNET_CORE_KX_STATE_DOWN = 0,
 226
 227   /**
 228    * We've sent our session key.
 229    */
 230   GNUNET_CORE_KX_STATE_KEY_SENT,
 231
 232   /**
 233    * We've received the other peers session key.
 234    */
 235   GNUNET_CORE_KX_STATE_KEY_RECEIVED,
 236
 237   /**
 238    * The other peer has confirmed our session key + PING with a PONG
 239    * message encrypted with their session key (which we got).  Key
 240    * exchange is done.
 241    */
 242   GNUNET_CORE_KX_STATE_UP,
 243
 244   /**
 245    * We're rekeying (or had a timeout), so we have sent the other peer
 246    * our new ephemeral key, but we did not get a matching PONG yet.
 247    * This is equivalent to being #GNUNET_CORE_KX_STATE_KEY_RECEIVED,
 248    * except that the session is marked as 'up' with sessions (as we
 249    * don't want to drop and re-establish P2P connections simply due to
 250    * rekeying).
 251    */
 252   GNUNET_CORE_KX_STATE_REKEY_SENT,
 253
 254   /**
 255    * Last state of a KX (when it is being terminated).  Set
 256    * just before CORE frees the internal state for this peer.
 257    */
 258   GNUNET_CORE_KX_PEER_DISCONNECT,
 259
 260   /**
 261    * This is not a state in a peer's state machine, but a special
 262    * value used with the #GNUNET_CORE_MonitorCallback to indicate
 263    * that we finished the initial iteration over the peers.
 264    */
 265   GNUNET_CORE_KX_ITERATION_FINISHED,
 266
 267   /**
 268    * This is not a state in a peer's state machine, but a special
 269    * value used with the #GNUNET_CORE_MonitorCallback to indicate
 270    * that we lost the connection to the CORE service (and will try
 271    * to reconnect).  If this happens, most likely the CORE service
 272    * crashed and thus all connection state should be assumed lost.
 273    */
 274   GNUNET_CORE_KX_CORE_DISCONNECT
 275
 276 };
 277
 278
 279 /**
 280  * Function called by the monitor callback whenever
 281  * a peer's connection status changes.
 282  *
 283  * @param cls closure
 284  * @param pid identity of the peer this update is about
 285  * @param state current key exchange state of the peer
 286  * @param timeout when does the current state expire
 287  */
 288 typedef void
 289 (*GNUNET_CORE_MonitorCallback)(void *cls,
 290                                const struct GNUNET_PeerIdentity *pid,
 291                                enum GNUNET_CORE_KxState state,
 292                                struct GNUNET_TIME_Absolute timeout);
 293
 294
 295 /**
 296  * Monitor connectivity and KX status of all peers known to CORE.
 297  * Calls @a peer_cb with the current status for each connected peer,
 298  * and then once with NULL to indicate that all peers that are
 299  * currently active have been handled.  After that, the iteration
 300  * continues until it is cancelled.  Normal users of the CORE API are
 301  * not expected to use this function.  It is different in that it
 302  * truly lists all connections (including those where the KX is in
 303  * progress), not just those relevant to the application.  This
 304  * function is used by special applications for diagnostics.
 305  *
 306  * @param cfg configuration handle
 307  * @param peer_cb function to call with the peer information
 308  * @param peer_cb_cls closure for @a peer_cb
 309  * @return NULL on error
 310  */
 311 struct GNUNET_CORE_MonitorHandle *
 312 GNUNET_CORE_monitor_start (const struct GNUNET_CONFIGURATION_Handle *cfg,
 313                            GNUNET_CORE_MonitorCallback peer_cb,
 314                            void *peer_cb_cls);
 315
 316
 317 /**
 318  * Stop monitoring CORE activity.
 319  *
 320  * @param mh monitor to stop
 321  */
 322 void
 323 GNUNET_CORE_monitor_stop (struct GNUNET_CORE_MonitorHandle *mh);
 324
 325
 326 /**
 327  * Check if the given peer is currently connected. This function is for special
 328  * cirumstances (GNUNET_TESTBED uses it), normal users of the CORE API are
 329  * expected to track which peers are connected based on the connect/disconnect
 330  * callbacks from #GNUNET_CORE_connect.  This function is NOT part of the
 331  * 'versioned', 'official' API.  This function returns
 332  * synchronously after looking in the CORE API cache.
 333  *
 334  * @param h the core handle
 335  * @param pid the identity of the peer to check if it has been connected to us
 336  * @return #GNUNET_YES if the peer is connected to us; #GNUNET_NO if not
 337  */
 338 int
 339 GNUNET_CORE_is_peer_connected_sync (const struct GNUNET_CORE_Handle *h,
 340                                     const struct GNUNET_PeerIdentity *pid);
 341
 342
 343 /**
 344  * Create a message queue for sending messages to a peer with CORE.
 345  * Messages may only be queued with #GNUNET_MQ_send once the init callback has
 346  * been called for the given handle.
 347  * There must only be one queue per peer for each core handle.
 348  * The message queue can only be used to transmit messages,
 349  * not to receive them.
 350  *
 351  * @param h the core handle
 352  * @param target the target peer for this queue, may not be NULL
 353  * @return a message queue for sending messages over the core handle
 354  *         to the target peer
 355  */
 356 struct GNUNET_MQ_Handle *
 357 GNUNET_CORE_mq_create (struct GNUNET_CORE_Handle *h,
 358                        const struct GNUNET_PeerIdentity *target);
 359
 360
 361 #if 0                           /* keep Emacsens' auto-indent happy */
 362 {
 363 #endif
 364 #ifdef __cplusplus
 365 }
 366 #endif
 367
 368 /* ifndef GNUNET_CORE_SERVICE_H */
 369 #endif
 370
 371 /** @} */  /* end of group core */
 372
 373 /* end of gnunet_core_service.h */