Core service

Encrypted direct communication between peers. More...

Collaboration diagram for Core service:

Data Structures
struct	EphemeralKeyMessage
	Message transmitted with the signed ephemeral key of a peer. More...
struct	PingMessage
	We're sending an (encrypted) PING to the other peer to check if it can decrypt. More...
struct	PongMessage
	Response to a PING. More...

Macros
#define	GNUNET_CORE_VERSION   0x00000001
	Version number of GNUnet-core API. More...
#define	CONG_CRYPTO_ENABLED   0
	Enable XChaCha20-Poly1305 crypto https://bugs.gnunet.org/view.php?id=8630. More...

Typedefs
typedef void *(*	GNUNET_CORE_ConnectEventHandler) (void *cls, const struct GNUNET_PeerIdentity *peer, struct GNUNET_MQ_Handle *mq)
	Method called whenever a given peer connects. More...
typedef void(*	GNUNET_CORE_DisconnectEventHandler) (void *cls, const struct GNUNET_PeerIdentity *peer, void *peer_cls)
	Method called whenever a peer disconnects. More...
typedef void(*	GNUNET_CORE_StartupCallback) (void *cls, const struct GNUNET_PeerIdentity *my_identity)
	Function called after GNUNET_CORE_connect has succeeded (or failed for good). More...
typedef void(*	GNUNET_CORE_MonitorCallback) (void *cls, const struct GNUNET_PeerIdentity *pid, enum GNUNET_CORE_KxState state, struct GNUNET_TIME_Absolute timeout)
	Function called by the monitor callback whenever a peer's connection status changes. More...

Enumerations
enum	GNUNET_CORE_KxState {   GNUNET_CORE_KX_STATE_DOWN = 0 , GNUNET_CORE_KX_STATE_KEY_SENT , GNUNET_CORE_KX_STATE_KEY_RECEIVED , GNUNET_CORE_KX_STATE_UP ,   GNUNET_CORE_KX_STATE_REKEY_SENT , GNUNET_CORE_KX_PEER_DISCONNECT , GNUNET_CORE_KX_ITERATION_FINISHED , GNUNET_CORE_KX_CORE_DISCONNECT }
	State machine for our P2P encryption handshake. More...

Functions
struct GNUNET_CORE_Handle *	GNUNET_CORE_connect (const struct GNUNET_CONFIGURATION_Handle *cfg, void *cls, GNUNET_CORE_StartupCallback init, GNUNET_CORE_ConnectEventHandler connects, GNUNET_CORE_DisconnectEventHandler disconnects, const struct GNUNET_MQ_MessageHandler *handlers)
	Connect to the core service. More...
void	GNUNET_CORE_disconnect (struct GNUNET_CORE_Handle *handle)
	Disconnect from the core service. More...
struct GNUNET_MQ_Handle *	GNUNET_CORE_get_mq (const struct GNUNET_CORE_Handle *h, const struct GNUNET_PeerIdentity *pid)
	Obtain the message queue for a connected peer. More...
struct GNUNET_CORE_MonitorHandle *	GNUNET_CORE_monitor_start (const struct GNUNET_CONFIGURATION_Handle *cfg, GNUNET_CORE_MonitorCallback peer_cb, void *peer_cb_cls)
	Monitor connectivity and KX status of all peers known to CORE. More...
void	GNUNET_CORE_monitor_stop (struct GNUNET_CORE_MonitorHandle *mh)
	Stop monitoring CORE activity. More...
int	GNUNET_CORE_is_peer_connected_sync (const struct GNUNET_CORE_Handle *h, const struct GNUNET_PeerIdentity *pid)
	Check if the given peer is currently connected. More...
struct GNUNET_MQ_Handle *	GNUNET_CORE_mq_create (struct GNUNET_CORE_Handle *h, const struct GNUNET_PeerIdentity *target)
	Create a message queue for sending messages to a peer with CORE. More...

Detailed Description

Encrypted direct communication between peers.

See also

Documentation

Macro Definition Documentation

GNUNET_CORE_VERSION

#define GNUNET_CORE_VERSION   0x00000001

Version number of GNUnet-core API.

Definition at line 52 of file gnunet_core_service.h.

CONG_CRYPTO_ENABLED

#define CONG_CRYPTO_ENABLED   0

Enable XChaCha20-Poly1305 crypto https://bugs.gnunet.org/view.php?id=8630.

Definition at line 56 of file gnunet_core_service.h.

Typedef Documentation

GNUNET_CORE_ConnectEventHandler

typedef void *(* GNUNET_CORE_ConnectEventHandler) (void *cls, const struct GNUNET_PeerIdentity *peer, struct GNUNET_MQ_Handle *mq)

Method called whenever a given peer connects.

Parameters

cls	closure
peer	peer identity this notification is about

Returns

closure associated with peer. given to mq callbacks and GNUNET_CORE_DisconnectEventHandler

Definition at line 275 of file gnunet_core_service.h.

GNUNET_CORE_DisconnectEventHandler

typedef void(* GNUNET_CORE_DisconnectEventHandler) (void *cls, const struct GNUNET_PeerIdentity *peer, void *peer_cls)

Method called whenever a peer disconnects.

Parameters

cls	closure
peer	peer identity this notification is about
peer_cls	closure associated with peer. given in GNUNET_CORE_ConnectEventHandler

Definition at line 289 of file gnunet_core_service.h.

GNUNET_CORE_StartupCallback

typedef void(* GNUNET_CORE_StartupCallback) (void *cls, const struct GNUNET_PeerIdentity *my_identity)

Function called after GNUNET_CORE_connect has succeeded (or failed for good).

Note that the private key of the peer is intentionally not exposed here; if you need it, your process should try to read the private key file directly (which should work if you are authorized...). Implementations of this function must not call GNUNET_CORE_disconnect (other than by scheduling a new task to do this later).

Parameters

cls	closure
my_identity	ID of this peer, NULL if we failed

Definition at line 307 of file gnunet_core_service.h.

GNUNET_CORE_MonitorCallback

typedef void(* GNUNET_CORE_MonitorCallback) (void *cls, const struct GNUNET_PeerIdentity *pid, enum GNUNET_CORE_KxState state, struct GNUNET_TIME_Absolute timeout)

Function called by the monitor callback whenever a peer's connection status changes.

Parameters

cls	closure
pid	identity of the peer this update is about
state	current key exchange state of the peer
timeout	when does the current state expire

Definition at line 452 of file gnunet_core_service.h.

Enumeration Type Documentation

GNUNET_CORE_KxState

enum GNUNET_CORE_KxState

State machine for our P2P encryption handshake.

Everyone starts in GNUNET_CORE_KX_STATE_DOWN, if we receive the other peer's key (other peer initiated) we start in state GNUNET_CORE_KX_STATE_KEY_RECEIVED (since we will immediately send our own); otherwise we start in GNUNET_CORE_KX_STATE_KEY_SENT. If we get back a PONG from within either state, we move up to GNUNET_CORE_KX_STATE_UP (the PONG will always be sent back encrypted with the key we sent to the other peer). Eventually, we will try to rekey, for this we will enter GNUNET_CORE_KX_STATE_REKEY_SENT until the rekey operation is confirmed by a PONG from the other peer.

Enumerator
GNUNET_CORE_KX_STATE_DOWN	No handshake yet.
GNUNET_CORE_KX_STATE_KEY_SENT	We've sent our session key.
GNUNET_CORE_KX_STATE_KEY_RECEIVED	We've received the other peers session key.
GNUNET_CORE_KX_STATE_UP	The other peer has confirmed our session key + PING with a PONG message encrypted with their session key (which we got). Key exchange is done.
GNUNET_CORE_KX_STATE_REKEY_SENT	We're rekeying (or had a timeout), so we have sent the other peer our new ephemeral key, but we did not get a matching PONG yet. This is equivalent to being GNUNET_CORE_KX_STATE_KEY_RECEIVED, except that the session is marked as 'up' with sessions (as we don't want to drop and re-establish P2P connections simply due to rekeying).
GNUNET_CORE_KX_PEER_DISCONNECT	Last state of a KX (when it is being terminated). Set just before CORE frees the internal state for this peer.
GNUNET_CORE_KX_ITERATION_FINISHED	This is not a state in a peer's state machine, but a special value used with the GNUNET_CORE_MonitorCallback to indicate that we finished the initial iteration over the peers.
GNUNET_CORE_KX_CORE_DISCONNECT	This is not a state in a peer's state machine, but a special value used with the GNUNET_CORE_MonitorCallback to indicate that we lost the connection to the CORE service (and will try to reconnect). If this happens, most likely the CORE service crashed and thus all connection state should be assumed lost.

Definition at line 385 of file gnunet_core_service.h.

{
  GNUNET_CORE_KX_STATE_DOWN = 0,
 
  GNUNET_CORE_KX_STATE_KEY_SENT,
 
  GNUNET_CORE_KX_STATE_KEY_RECEIVED,
 
  GNUNET_CORE_KX_STATE_UP,
 
  GNUNET_CORE_KX_STATE_REKEY_SENT,
 
  GNUNET_CORE_KX_PEER_DISCONNECT,
 
  GNUNET_CORE_KX_ITERATION_FINISHED,
 
  GNUNET_CORE_KX_CORE_DISCONNECT
};

Function Documentation

GNUNET_CORE_connect()

struct GNUNET_CORE_Handle * GNUNET_CORE_connect	(	const struct GNUNET_CONFIGURATION_Handle *	cfg,
		void *	cls,
		GNUNET_CORE_StartupCallback	init,
		GNUNET_CORE_ConnectEventHandler	connects,
		GNUNET_CORE_DisconnectEventHandler	disconnects,
		const struct GNUNET_MQ_MessageHandler *	handlers
	)

Connect to the core service.

Note that the connection may complete (or fail) asynchronously. This function primarily causes the given callback notification functions to be invoked whenever the specified event happens. The maximum number of queued notifications (queue length) is per client; the queue is shared across all types of notifications. So a slow client that registers for outbound_notify also risks missing inbound_notify messages. Certain events (such as connect/disconnect notifications) are not subject to queue size limitations.

Parameters

cfg	configuration to use
cls	closure for the various callbacks that follow (including handlers in the handlers array)
init	callback to call once we have successfully connected to the core service
connects	function to call on peer connect, can be NULL
disconnects	function to call on peer disconnect / timeout, can be NULL
handlers	callbacks for messages we care about, NULL-terminated note that the core is allowed to drop notifications about inbound messages if the client does not process them fast enough (for this notification type, a bounded queue is used)

Returns

handle to the core service (only useful for disconnect until init is called), NULL on error (in this case, init is never called)

Note that the connection may complete (or fail) asynchronously.

Parameters

cfg	configuration to use
cls	closure for the various callbacks that follow (including handlers in the handlers array)
init	callback to call once we have successfully connected to the core service
connects	function to call on peer connect, can be NULL
disconnects	function to call on peer disconnect / timeout, can be NULL
handlers	callbacks for messages we care about, NULL-terminated

Returns

handle to the core service (only useful for disconnect until init is called); NULL on error (in this case, init is never called)

Definition at line 691 of file core_api.c.

{
  struct GNUNET_CORE_Handle *h;
 
  h = GNUNET_new (struct GNUNET_CORE_Handle);
  h->cfg = cfg;
  h->cls = cls;
  h->init = init;
  h->connects = connects;
  h->disconnects = disconnects;
  h->peers = GNUNET_CONTAINER_multipeermap_create (128, GNUNET_NO);
  h->handlers = GNUNET_MQ_copy_handlers (handlers);
  h->hcnt = GNUNET_MQ_count_handlers (handlers);
  GNUNET_assert (h->hcnt <
                 (GNUNET_MAX_MESSAGE_SIZE - sizeof(struct InitMessage))
                 / sizeof(uint16_t));
  LOG (GNUNET_ERROR_TYPE_DEBUG, "Connecting to CORE service\n");
  reconnect (h);
  if (NULL == h->mq)
  {
    GNUNET_CORE_disconnect (h);
    return NULL;
  }
  return h;
}

References cfg, GNUNET_ARM_Handle::cfg, GNUNET_CORE_Handle::cls, connects(), disconnects(), GNUNET_assert, GNUNET_CONTAINER_multipeermap_create(), GNUNET_CORE_disconnect(), GNUNET_ERROR_TYPE_DEBUG, GNUNET_MAX_MESSAGE_SIZE, GNUNET_MQ_copy_handlers(), GNUNET_MQ_count_handlers(), GNUNET_new, GNUNET_NO, h, handlers, init, LOG, GNUNET_ARM_Handle::mq, and reconnect().

Referenced by DHTU_gnunet_init(), GCO_init(), main_init(), and run().

Here is the call graph for this function:

Here is the caller graph for this function:

GNUNET_CORE_disconnect()

void GNUNET_CORE_disconnect

(

struct GNUNET_CORE_Handle *

handle

)

Disconnect from the core service.

Parameters

handle

connection to core to disconnect

Definition at line 729 of file core_api.c.

{
  LOG (GNUNET_ERROR_TYPE_DEBUG, "Disconnecting from CORE service\n");
  GNUNET_CONTAINER_multipeermap_iterate (handle->peers,
                                         &disconnect_and_free_peer_entry,
                                         handle);
  GNUNET_CONTAINER_multipeermap_destroy (handle->peers);
  handle->peers = NULL;
  if (NULL != handle->reconnect_task)
  {
    GNUNET_SCHEDULER_cancel (handle->reconnect_task);
    handle->reconnect_task = NULL;
  }
  if (NULL != handle->mq)
  {
    GNUNET_MQ_destroy (handle->mq);
    handle->mq = NULL;
  }
  GNUNET_free (handle->handlers);
  GNUNET_free (handle);
}

References disconnect_and_free_peer_entry(), GNUNET_CONTAINER_multipeermap_destroy(), GNUNET_CONTAINER_multipeermap_iterate(), GNUNET_ERROR_TYPE_DEBUG, GNUNET_free, GNUNET_MQ_destroy(), GNUNET_SCHEDULER_cancel(), handle, LOG, and GNUNET_VPN_Handle::mq.

Referenced by cleaning_task(), DHTU_gnunet_done(), GCO_shutdown(), GNUNET_CORE_connect(), and shutdown_task().

Here is the call graph for this function:

Here is the caller graph for this function:

GNUNET_CORE_get_mq()

struct GNUNET_MQ_Handle * GNUNET_CORE_get_mq	(	const struct GNUNET_CORE_Handle *	h,
		const struct GNUNET_PeerIdentity *	pid
	)

Obtain the message queue for a connected peer.

Parameters

h	the core handle
pid	the identity of the peer

Returns

NULL if pid is not connected

Parameters

h	the core handle
pid	the identity of the peer to check if it has been connected to us

Returns

NULL if peer is not connected

Definition at line 760 of file core_api.c.

{
  struct PeerRecord *pr;
 
  pr = GNUNET_CONTAINER_multipeermap_get (h->peers, pid);
  if (NULL == pr)
    return NULL;
  return pr->mq;
}

References GNUNET_CONTAINER_multipeermap_get(), h, PeerRecord::mq, and pid.

Here is the call graph for this function:

GNUNET_CORE_monitor_start()

struct GNUNET_CORE_MonitorHandle * GNUNET_CORE_monitor_start	(	const struct GNUNET_CONFIGURATION_Handle *	cfg,
		GNUNET_CORE_MonitorCallback	peer_cb,
		void *	peer_cb_cls
	)

Monitor connectivity and KX status of all peers known to CORE.

Calls peer_cb with the current status for each connected peer, and then once with NULL to indicate that all peers that are currently active have been handled. After that, the iteration continues until it is cancelled. Normal users of the CORE API are not expected to use this function. It is different in that it truly lists all connections (including those where the KX is in progress), not just those relevant to the application. This function is used by special applications for diagnostics.

Parameters

cfg	configuration handle
peer_cb	function to call with the peer information
peer_cb_cls	closure for peer_cb

Returns

NULL on error

Definition at line 158 of file core_api_monitor_peers.c.

{
  struct GNUNET_CORE_MonitorHandle *mh;
 
  GNUNET_assert (NULL != peer_cb);
  mh = GNUNET_new (struct GNUNET_CORE_MonitorHandle);
  mh->cfg = cfg;
  reconnect (mh);
  mh->peer_cb = peer_cb;
  mh->peer_cb_cls = peer_cb_cls;
  if (NULL == mh->mq)
  {
    GNUNET_free (mh);
    return NULL;
  }
  return mh;
}

References cfg, GNUNET_CADET_Handle::cfg, GNUNET_assert, GNUNET_free, GNUNET_new, mh, GNUNET_CADET_Handle::mq, GNUNET_CORE_MonitorHandle::peer_cb, GNUNET_CORE_MonitorHandle::peer_cb_cls, and reconnect().

Referenced by run().

Here is the call graph for this function:

Here is the caller graph for this function:

GNUNET_CORE_monitor_stop()

void GNUNET_CORE_monitor_stop

(

struct GNUNET_CORE_MonitorHandle *

mh

)

Stop monitoring CORE activity.

Parameters

mh	monitor to stop

Definition at line 185 of file core_api_monitor_peers.c.

{
  if (NULL != mh->mq)
  {
    GNUNET_MQ_destroy (mh->mq);
    mh->mq = NULL;
  }
  GNUNET_free (mh);
}

References GNUNET_free, GNUNET_MQ_destroy(), mh, and GNUNET_CADET_Handle::mq.

Referenced by shutdown_task().

Here is the call graph for this function:

Here is the caller graph for this function:

GNUNET_CORE_is_peer_connected_sync()

int GNUNET_CORE_is_peer_connected_sync	(	const struct GNUNET_CORE_Handle *	h,
		const struct GNUNET_PeerIdentity *	pid
	)

Check if the given peer is currently connected.

This function is for special circumstances (GNUNET_TESTBED uses it), normal users of the CORE API are expected to track which peers are connected based on the connect/disconnect callbacks from GNUNET_CORE_connect. This function is NOT part of the 'versioned', 'official' API. This function returns synchronously after looking in the CORE API cache.

Parameters

h	the core handle
pid	the identity of the peer to check if it has been connected to us

Returns

GNUNET_YES if the peer is connected to us; GNUNET_NO if not

GNUNET_CORE_mq_create()

struct GNUNET_MQ_Handle * GNUNET_CORE_mq_create	(	struct GNUNET_CORE_Handle *	h,
		const struct GNUNET_PeerIdentity *	target
	)

Create a message queue for sending messages to a peer with CORE.

Messages may only be queued with GNUNET_MQ_send once the init callback has been called for the given handle. There must only be one queue per peer for each core handle. The message queue can only be used to transmit messages, not to receive them.

Parameters

h	the core handle
target	the target peer for this queue, may not be NULL

Returns

a message queue for sending messages over the core handle to the target peer