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  */
  92 typedef void *
  93 (*GNUNET_CORE_ConnectEventHandler) (void *cls,
  94                                     const struct GNUNET_PeerIdentity *peer,
  95                                     struct GNUNET_MQ_Handle *mq);
  96
  97
  98 /**
  99  * Method called whenever a peer disconnects.
 100  *
 101  * @param cls closure
 102  * @param peer peer identity this notification is about
 103  */
 104 typedef void
 105 (*GNUNET_CORE_DisconnectEventHandler) (void *cls,
 106                                        const struct GNUNET_PeerIdentity *peer,
 107                                        void *peer_cls);
 108
 109
 110 /**
 111  * Function called after #GNUNET_CORE_connect has succeeded (or failed
 112  * for good).  Note that the private key of the peer is intentionally
 113  * not exposed here; if you need it, your process should try to read
 114  * the private key file directly (which should work if you are
 115  * authorized...).  Implementations of this function must not call
 116  * #GNUNET_CORE_disconnect (other than by scheduling a new task to
 117  * do this later).
 118  *
 119  * @param cls closure
 120  * @param my_identity ID of this peer, NULL if we failed
 121  */
 122 typedef void
 123 (*GNUNET_CORE_StartupCallback) (void *cls,
 124                                 const struct GNUNET_PeerIdentity *my_identity);
 125
 126
 127 /**
 128  * Connect to the core service.  Note that the connection may complete
 129  * (or fail) asynchronously.  This function primarily causes the given
 130  * callback notification functions to be invoked whenever the
 131  * specified event happens.  The maximum number of queued
 132  * notifications (queue length) is per client; the queue is shared
 133  * across all types of notifications.  So a slow client that registers
 134  * for @a outbound_notify also risks missing @a inbound_notify messages.
 135  * Certain events (such as connect/disconnect notifications) are not
 136  * subject to queue size limitations.
 137  *
 138  * @param cfg configuration to use
 139  * @param cls closure for the various callbacks that follow (including handlers in the handlers array)
 140  * @param init callback to call once we have successfully
 141  *        connected to the core service
 142  * @param connects function to call on peer connect, can be NULL
 143  * @param disconnects function to call on peer disconnect / timeout, can be NULL
 144  * @param handlers callbacks for messages we care about, NULL-terminated
 145  *                note that the core is allowed to drop notifications about inbound
 146  *                messages if the client does not process them fast enough (for this
 147  *                notification type, a bounded queue is used)
 148  * @return handle to the core service (only useful for disconnect until @a init is called),
 149  *           NULL on error (in this case, init is never called)
 150  */
 151 struct GNUNET_CORE_Handle *
 152 GNUNET_CORE_connect (const struct GNUNET_CONFIGURATION_Handle *cfg,
 153                      void *cls,
 154                      GNUNET_CORE_StartupCallback init,
 155                      GNUNET_CORE_ConnectEventHandler connects,
 156                      GNUNET_CORE_DisconnectEventHandler disconnects,
 157                      const struct GNUNET_MQ_MessageHandler *handlers);
 158
 159
 160 /**
 161  * Disconnect from the core service.
 162  *
 163  * @param handle connection to core to disconnect
 164  */
 165 void
 166 GNUNET_CORE_disconnect (struct GNUNET_CORE_Handle *handle);
 167
 168
 169 /**
 170  * Inquire with CORE what options should be set for a message
 171  * so that it is transmitted with the given @a priority and
 172  * the given @a cork value.
 173  *
 174  * @param cork desired corking
 175  * @param priority desired message priority
 176  * @param[out] flags set to `flags` value for #GNUNET_MQ_set_options()
 177  * @return `extra` argument to give to #GNUNET_MQ_set_options()
 178  */
 179 const void *
 180 GNUNET_CORE_get_mq_options (int cork,
 181                             enum GNUNET_CORE_Priority priority,
 182                             uint64_t *flags);
 183
 184
 185 /**
 186  * Obtain the message queue for a connected peer.
 187  *
 188  * @param h the core handle
 189  * @param pid the identity of the peer
 190  * @return NULL if @a pid is not connected
 191  */
 192 struct GNUNET_MQ_Handle *
 193 GNUNET_CORE_get_mq (const struct GNUNET_CORE_Handle *h,
 194                     const struct GNUNET_PeerIdentity *pid);
 195
 196
 197 /**
 198  * Handle to a CORE monitoring operation.
 199  */
 200 struct GNUNET_CORE_MonitorHandle;
 201
 202
 203 /**
 204  * State machine for our P2P encryption handshake.  Everyone starts in
 205  * #GNUNET_CORE_KX_STATE_DOWN, if we receive the other peer's key
 206  * (other peer initiated) we start in state
 207  * #GNUNET_CORE_KX_STATE_KEY_RECEIVED (since we will immediately send
 208  * our own); otherwise we start in #GNUNET_CORE_KX_STATE_KEY_SENT.  If
 209  * we get back a PONG from within either state, we move up to
 210  * #GNUNET_CORE_KX_STATE_UP (the PONG will always be sent back
 211  * encrypted with the key we sent to the other peer).  Eventually,
 212  * we will try to rekey, for this we will enter
 213  * #GNUNET_CORE_KX_STATE_REKEY_SENT until the rekey operation is
 214  * confirmed by a PONG from the other peer.
 215  */
 216 enum GNUNET_CORE_KxState
 217 {
 218   /**
 219    * No handshake yet.
 220    */
 221   GNUNET_CORE_KX_STATE_DOWN = 0,
 222
 223   /**
 224    * We've sent our session key.
 225    */
 226   GNUNET_CORE_KX_STATE_KEY_SENT,
 227
 228   /**
 229    * We've received the other peers session key.
 230    */
 231   GNUNET_CORE_KX_STATE_KEY_RECEIVED,
 232
 233   /**
 234    * The other peer has confirmed our session key + PING with a PONG
 235    * message encrypted with his session key (which we got).  Key
 236    * exchange is done.
 237    */
 238   GNUNET_CORE_KX_STATE_UP,
 239
 240   /**
 241    * We're rekeying (or had a timeout), so we have sent the other peer
 242    * our new ephemeral key, but we did not get a matching PONG yet.
 243    * This is equivalent to being #GNUNET_CORE_KX_STATE_KEY_RECEIVED,
 244    * except that the session is marked as 'up' with sessions (as we
 245    * don't want to drop and re-establish P2P connections simply due to
 246    * rekeying).
 247    */
 248   GNUNET_CORE_KX_STATE_REKEY_SENT,
 249
 250   /**
 251    * Last state of a KX (when it is being terminated).  Set
 252    * just before CORE frees the internal state for this peer.
 253    */
 254   GNUNET_CORE_KX_PEER_DISCONNECT,
 255
 256   /**
 257    * This is not a state in a peer's state machine, but a special
 258    * value used with the #GNUNET_CORE_MonitorCallback to indicate
 259    * that we finished the initial iteration over the peers.
 260    */
 261   GNUNET_CORE_KX_ITERATION_FINISHED,
 262
 263   /**
 264    * This is not a state in a peer's state machine, but a special
 265    * value used with the #GNUNET_CORE_MonitorCallback to indicate
 266    * that we lost the connection to the CORE service (and will try
 267    * to reconnect).  If this happens, most likely the CORE service
 268    * crashed and thus all connection state should be assumed lost.
 269    */
 270   GNUNET_CORE_KX_CORE_DISCONNECT
 271
 272 };
 273
 274
 275 /**
 276  * Function called by the monitor callback whenever
 277  * a peer's connection status changes.
 278  *
 279  * @param cls closure
 280  * @param pid identity of the peer this update is about
 281  * @param state current key exchange state of the peer
 282  * @param timeout when does the current state expire
 283  */
 284 typedef void
 285 (*GNUNET_CORE_MonitorCallback)(void *cls,
 286                                const struct GNUNET_PeerIdentity *pid,
 287                                enum GNUNET_CORE_KxState state,
 288                                struct GNUNET_TIME_Absolute timeout);
 289
 290
 291 /**
 292  * Monitor connectivity and KX status of all peers known to CORE.
 293  * Calls @a peer_cb with the current status for each connected peer,
 294  * and then once with NULL to indicate that all peers that are
 295  * currently active have been handled.  After that, the iteration
 296  * continues until it is cancelled.  Normal users of the CORE API are
 297  * not expected to use this function.  It is different in that it
 298  * truly lists all connections (including those where the KX is in
 299  * progress), not just those relevant to the application.  This
 300  * function is used by special applications for diagnostics.
 301  *
 302  * @param cfg configuration handle
 303  * @param peer_cb function to call with the peer information
 304  * @param peer_cb_cls closure for @a peer_cb
 305  * @return NULL on error
 306  */
 307 struct GNUNET_CORE_MonitorHandle *
 308 GNUNET_CORE_monitor_start (const struct GNUNET_CONFIGURATION_Handle *cfg,
 309                            GNUNET_CORE_MonitorCallback peer_cb,
 310                            void *peer_cb_cls);
 311
 312
 313 /**
 314  * Stop monitoring CORE activity.
 315  *
 316  * @param mh monitor to stop
 317  */
 318 void
 319 GNUNET_CORE_monitor_stop (struct GNUNET_CORE_MonitorHandle *mh);
 320
 321
 322 /**
 323  * Check if the given peer is currently connected. This function is for special
 324  * cirumstances (GNUNET_TESTBED uses it), normal users of the CORE API are
 325  * expected to track which peers are connected based on the connect/disconnect
 326  * callbacks from #GNUNET_CORE_connect.  This function is NOT part of the
 327  * 'versioned', 'official' API.  This function returns
 328  * synchronously after looking in the CORE API cache.
 329  *
 330  * @param h the core handle
 331  * @param pid the identity of the peer to check if it has been connected to us
 332  * @return #GNUNET_YES if the peer is connected to us; #GNUNET_NO if not
 333  */
 334 int
 335 GNUNET_CORE_is_peer_connected_sync (const struct GNUNET_CORE_Handle *h,
 336                                     const struct GNUNET_PeerIdentity *pid);
 337
 338
 339 /**
 340  * Create a message queue for sending messages to a peer with CORE.
 341  * Messages may only be queued with #GNUNET_MQ_send once the init callback has
 342  * been called for the given handle.
 343  * There must only be one queue per peer for each core handle.
 344  * The message queue can only be used to transmit messages,
 345  * not to receive them.
 346  *
 347  * @param h the core handle
 348  * @param target the target peer for this queue, may not be NULL
 349  * @return a message queue for sending messages over the core handle
 350  *         to the target peer
 351  */
 352 struct GNUNET_MQ_Handle *
 353 GNUNET_CORE_mq_create (struct GNUNET_CORE_Handle *h,
 354                        const struct GNUNET_PeerIdentity *target);
 355
 356
 357 #if 0                           /* keep Emacsens' auto-indent happy */
 358 {
 359 #endif
 360 #ifdef __cplusplus
 361 }
 362 #endif
 363
 364 /* ifndef GNUNET_CORE_SERVICE_H */
 365 #endif
 366
 367 /** @} */  /* end of group core */
 368
 369 /* end of gnunet_core_service.h */