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