2 This file is part of GNUnet.
3 (C) 2009-2014 Christian Grothoff (and other contributing authors)
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.
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.
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., 59 Temple Place - Suite 330,
18 Boston, MA 02111-1307, USA.
22 * @file include/gnunet_core_service.h
23 * @brief core service; this is the main API for encrypted P2P
25 * @author Christian Grothoff
26 * @defgroup core encrypted direct communication between peers
30 #ifndef GNUNET_CORE_SERVICE_H
31 #define GNUNET_CORE_SERVICE_H
36 #if 0 /* keep Emacsens' auto-indent happy */
41 #include "gnunet_util_lib.h"
42 #include "gnunet_transport_service.h"
45 * Version number of GNUnet-core API.
47 #define GNUNET_CORE_VERSION 0x00000001
52 enum GNUNET_CORE_Priority
56 * Lowest priority, i.e. background traffic (i.e. fs)
58 GNUNET_CORE_PRIO_BACKGROUND = 0,
61 * Normal traffic (i.e. cadet/dv relay, DHT)
63 GNUNET_CORE_PRIO_BEST_EFFORT = 1,
66 * Urgent traffic (local peer, i.e. conversation).
68 GNUNET_CORE_PRIO_URGENT = 2,
71 * Highest priority, control traffic (i.e. NSE, Core/Cadet KX).
73 GNUNET_CORE_PRIO_CRITICAL_CONTROL = 3
80 * Opaque handle to the service.
82 struct GNUNET_CORE_Handle;
86 * Method called whenever a given peer connects.
89 * @param peer peer identity this notification is about
92 (*GNUNET_CORE_ConnectEventHandler) (void *cls,
93 const struct GNUNET_PeerIdentity *peer);
97 * Method called whenever a peer disconnects.
100 * @param peer peer identity this notification is about
103 (*GNUNET_CORE_DisconnectEventHandler) (void *cls,
104 const struct GNUNET_PeerIdentity *peer);
108 * Functions with this signature are called whenever a message is
109 * received or transmitted.
111 * @param cls closure (set from #GNUNET_CORE_connect)
112 * @param peer the other peer involved (sender or receiver, NULL
113 * for loopback messages where we are both sender and receiver)
114 * @param message the actual message
115 * @return #GNUNET_OK to keep the connection open,
116 * #GNUNET_SYSERR to close connection to the peer (signal serious error)
119 (*GNUNET_CORE_MessageCallback) (void *cls,
120 const struct GNUNET_PeerIdentity *other,
121 const struct GNUNET_MessageHeader *message);
125 * Message handler. Each struct specifies how to handle on particular
126 * type of message received.
128 struct GNUNET_CORE_MessageHandler
131 * Function to call for messages of @e type.
133 GNUNET_CORE_MessageCallback callback;
136 * Type of the message this handler covers.
141 * Expected size of messages of this type. Use 0 for variable-size.
142 * If non-zero, messages of the given type will be discarded if they
143 * do not have the right size.
145 uint16_t expected_size;
151 * Function called after #GNUNET_CORE_connect has succeeded (or failed
152 * for good). Note that the private key of the peer is intentionally
153 * not exposed here; if you need it, your process should try to read
154 * the private key file directly (which should work if you are
155 * authorized...). Implementations of this function must not call
156 * #GNUNET_CORE_disconnect (other than by scheduling a new task to
160 * @param my_identity ID of this peer, NULL if we failed
163 (*GNUNET_CORE_StartupCallback) (void *cls,
164 const struct GNUNET_PeerIdentity *my_identity);
168 * Connect to the core service. Note that the connection may complete
169 * (or fail) asynchronously. This function primarily causes the given
170 * callback notification functions to be invoked whenever the
171 * specified event happens. The maximum number of queued
172 * notifications (queue length) is per client; the queue is shared
173 * across all types of notifications. So a slow client that registers
174 * for @a outbound_notify also risks missing @a inbound_notify messages.
175 * Certain events (such as connect/disconnect notifications) are not
176 * subject to queue size limitations.
178 * @param cfg configuration to use
179 * @param cls closure for the various callbacks that follow (including handlers in the handlers array)
180 * @param init callback to call once we have successfully
181 * connected to the core service
182 * @param connects function to call on peer connect, can be NULL
183 * @param disconnects function to call on peer disconnect / timeout, can be NULL
184 * @param inbound_notify function to call for all inbound messages, can be NULL
185 * note that the core is allowed to drop notifications about inbound
186 * messages if the client does not process them fast enough (for this
187 * notification type, a bounded queue is used)
188 * @param inbound_hdr_only set to #GNUNET_YES if @a inbound_notify will only read the
189 * `struct GNUNET_MessageHeader` and hence we do not need to give it the full message;
190 * can be used to improve efficiency, ignored if inbound_notify is NULL
191 * note that the core is allowed to drop notifications about inbound
192 * messages if the client does not process them fast enough (for this
193 * notification type, a bounded queue is used)
194 * @param outbound_notify function to call for all outbound messages, can be NULL;
195 * note that the core is allowed to drop notifications about outbound
196 * messages if the client does not process them fast enough (for this
197 * notification type, a bounded queue is used)
198 * @param outbound_hdr_only set to #GNUNET_YES if @a outbound_notify will only read the
199 * `struct GNUNET_MessageHeader` and hence we do not need to give it the full message
200 * can be used to improve efficiency, ignored if outbound_notify is NULL
201 * note that the core is allowed to drop notifications about outbound
202 * messages if the client does not process them fast enough (for this
203 * notification type, a bounded queue is used)
204 * @param handlers callbacks for messages we care about, NULL-terminated
205 * note that the core is allowed to drop notifications about inbound
206 * messages if the client does not process them fast enough (for this
207 * notification type, a bounded queue is used)
208 * @return handle to the core service (only useful for disconnect until @a init is called),
209 * NULL on error (in this case, init is never called)
211 struct GNUNET_CORE_Handle *
212 GNUNET_CORE_connect (const struct GNUNET_CONFIGURATION_Handle *cfg,
214 GNUNET_CORE_StartupCallback init,
215 GNUNET_CORE_ConnectEventHandler connects,
216 GNUNET_CORE_DisconnectEventHandler disconnects,
217 GNUNET_CORE_MessageCallback inbound_notify,
218 int inbound_hdr_only,
219 GNUNET_CORE_MessageCallback outbound_notify,
220 int outbound_hdr_only,
221 const struct GNUNET_CORE_MessageHandler *handlers);
225 * Disconnect from the core service. This function can only
226 * be called *after* all pending #GNUNET_CORE_notify_transmit_ready
227 * requests have been explicitly cancelled.
229 * @param handle connection to core to disconnect
232 GNUNET_CORE_disconnect (struct GNUNET_CORE_Handle *handle);
236 * Handle for a transmission request.
238 struct GNUNET_CORE_TransmitHandle;
242 * Ask the core to call @a notify once it is ready to transmit the
243 * given number of bytes to the specified @a target. Must only be
244 * called after a connection to the respective peer has been
245 * established (and the client has been informed about this). You may
246 * have one request of this type pending for each connected peer at
247 * any time. If a peer disconnects, the application MUST call
248 * #GNUNET_CORE_notify_transmit_ready_cancel on the respective
249 * transmission request, if one such request is pending.
251 * @param handle connection to core service
252 * @param cork is corking allowed for this transmission?
253 * @param priority how important is the message?
254 * @param maxdelay how long can the message wait? Only effective if @a cork is #GNUNET_YES
255 * @param target who should receive the message, never NULL (can be this peer's identity for loopback)
256 * @param notify_size how many bytes of buffer space does notify want?
257 * @param notify function to call when buffer space is available;
258 * will be called with NULL on timeout; clients MUST cancel
259 * all pending transmission requests DURING the disconnect
261 * @param notify_cls closure for @a notify
262 * @return non-NULL if the notify callback was queued,
263 * NULL if we can not even queue the request (request already pending);
264 * if NULL is returned, "notify" will NOT be called.
266 struct GNUNET_CORE_TransmitHandle *
267 GNUNET_CORE_notify_transmit_ready (struct GNUNET_CORE_Handle *handle,
269 enum GNUNET_CORE_Priority priority,
270 struct GNUNET_TIME_Relative maxdelay,
271 const struct GNUNET_PeerIdentity *target,
273 GNUNET_CONNECTION_TransmitReadyNotify notify,
278 * Cancel the specified transmission-ready notification.
280 * @param th handle that was returned by "notify_transmit_ready".
283 GNUNET_CORE_notify_transmit_ready_cancel (struct GNUNET_CORE_TransmitHandle *th);
287 * Handle to a CORE monitoring operation.
289 struct GNUNET_CORE_MonitorHandle;
293 * State machine for our P2P encryption handshake. Everyone starts in
294 * #GNUNET_CORE_KX_STATE_DOWN, if we receive the other peer's key
295 * (other peer initiated) we start in state
296 * #GNUNET_CORE_KX_STATE_KEY_RECEIVED (since we will immediately send
297 * our own); otherwise we start in #GNUNET_CORE_KX_STATE_KEY_SENT. If
298 * we get back a PONG from within either state, we move up to
299 * #GNUNET_CORE_KX_STATE_UP (the PONG will always be sent back
300 * encrypted with the key we sent to the other peer). Eventually,
301 * we will try to rekey, for this we will enter
302 * #GNUNET_CORE_KX_STATE_REKEY_SENT until the rekey operation is
303 * confirmed by a PONG from the other peer.
305 enum GNUNET_CORE_KxState
310 GNUNET_CORE_KX_STATE_DOWN,
313 * We've sent our session key.
315 GNUNET_CORE_KX_STATE_KEY_SENT,
318 * We've received the other peers session key.
320 GNUNET_CORE_KX_STATE_KEY_RECEIVED,
323 * The other peer has confirmed our session key + PING with a PONG
324 * message encrypted with his session key (which we got). Key
327 GNUNET_CORE_KX_STATE_UP,
330 * We're rekeying (or had a timeout), so we have sent the other peer
331 * our new ephemeral key, but we did not get a matching PONG yet.
332 * This is equivalent to being #GNUNET_CORE_KX_STATE_KEY_RECEIVED,
333 * except that the session is marked as 'up' with sessions (as we
334 * don't want to drop and re-establish P2P connections simply due to
337 GNUNET_CORE_KX_STATE_REKEY_SENT,
340 * Last state of a KX (when it is being terminated). Set
341 * just before CORE frees the internal state for this peer.
343 GNUNET_CORE_KX_PEER_DISCONNECT,
346 * This is not a state in a peer's state machine, but a special
347 * value used with the #GNUNET_CORE_MonitorCallback to indicate
348 * that we finished the initial iteration over the peers.
350 GNUNET_CORE_KX_ITERATION_FINISHED,
353 * This is not a state in a peer's state machine, but a special
354 * value used with the #GNUNET_CORE_MonitorCallback to indicate
355 * that we lost the connection to the CORE service (and will try
356 * to reconnect). If this happens, most likely the CORE service
357 * crashed and thus all connection state should be assumed lost.
359 GNUNET_CORE_KX_CORE_DISCONNECT
365 * Function called by the monitor callback whenever
366 * a peer's connection status changes.
369 * @param pid identity of the peer this update is about
370 * @param state current key exchange state of the peer
371 * @param timeout when does the current state expire
374 (*GNUNET_CORE_MonitorCallback)(void *cls,
375 const struct GNUNET_PeerIdentity *pid,
376 enum GNUNET_CORE_KxState state,
377 struct GNUNET_TIME_Absolute timeout);
381 * Monitor connectivity and KX status of all peers known to CORE.
382 * Calls @a peer_cb with the current status for each connected peer,
383 * and then once with NULL to indicate that all peers that are
384 * currently active have been handled. After that, the iteration
385 * continues until it is cancelled. Normal users of the CORE API are
386 * not expected to use this function. It is different in that it
387 * truly lists all connections (including those where the KX is in
388 * progress), not just those relevant to the application. This
389 * function is used by special applications for diagnostics.
391 * @param cfg configuration handle
392 * @param peer_cb function to call with the peer information
393 * @param peer_cb_cls closure for @a peer_cb
394 * @return NULL on error
396 struct GNUNET_CORE_MonitorHandle *
397 GNUNET_CORE_monitor_start (const struct GNUNET_CONFIGURATION_Handle *cfg,
398 GNUNET_CORE_MonitorCallback peer_cb,
403 * Stop monitoring CORE activity.
405 * @param mh monitor to stop
408 GNUNET_CORE_monitor_stop (struct GNUNET_CORE_MonitorHandle *mh);
412 * Check if the given peer is currently connected. This function is for special
413 * cirumstances (GNUNET_TESTBED uses it), normal users of the CORE API are
414 * expected to track which peers are connected based on the connect/disconnect
415 * callbacks from #GNUNET_CORE_connect. This function is NOT part of the
416 * 'versioned', 'official' API. This function returns
417 * synchronously after looking in the CORE API cache.
419 * @param h the core handle
420 * @param pid the identity of the peer to check if it has been connected to us
421 * @return #GNUNET_YES if the peer is connected to us; #GNUNET_NO if not
424 GNUNET_CORE_is_peer_connected_sync (const struct GNUNET_CORE_Handle *h,
425 const struct GNUNET_PeerIdentity *pid);
429 * Create a message queue for sending messages to a peer with CORE.
430 * Messages may only be queued with #GNUNET_MQ_send once the init callback has
431 * been called for the given handle.
432 * There must only be one queue per peer for each core handle.
433 * The message queue can only be used to transmit messages,
434 * not to receive them.
436 * @param h the core handle
437 * @param target the target peer for this queue, may not be NULL
438 * @return a message queue for sending messages over the core handle
441 struct GNUNET_MQ_Handle *
442 GNUNET_CORE_mq_create (struct GNUNET_CORE_Handle *h,
443 const struct GNUNET_PeerIdentity *target);
446 #if 0 /* keep Emacsens' auto-indent happy */
453 /** @} */ /* end of group core */
455 /* ifndef GNUNET_CORE_SERVICE_H */
457 /* end of gnunet_core_service.h */