GNUnet 0.21.0
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...
 

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_HandleGNUNET_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_HandleGNUNET_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_MonitorHandleGNUNET_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_HandleGNUNET_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.

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
clsclosure
peerpeer identity this notification is about
Returns
closure associated with peer. given to mq callbacks and GNUNET_CORE_DisconnectEventHandler

Definition at line 185 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
clsclosure
peerpeer identity this notification is about
peer_clsclosure associated with peer. given in GNUNET_CORE_ConnectEventHandler

Definition at line 199 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
clsclosure
my_identityID of this peer, NULL if we failed

Definition at line 217 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
clsclosure
pididentity of the peer this update is about
statecurrent key exchange state of the peer
timeoutwhen does the current state expire

Definition at line 362 of file gnunet_core_service.h.

Enumeration Type Documentation

◆ 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 295 of file gnunet_core_service.h.

296{
301
306
311
318
328
334
341
350};
@ GNUNET_CORE_KX_PEER_DISCONNECT
Last state of a KX (when it is being terminated).
@ GNUNET_CORE_KX_STATE_UP
The other peer has confirmed our session key + PING with a PONG message encrypted with their session ...
@ GNUNET_CORE_KX_STATE_DOWN
No handshake yet.
@ 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_MonitorC...
@ 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_ITERATION_FINISHED
This is not a state in a peer's state machine, but a special value used with the GNUNET_CORE_MonitorC...
@ GNUNET_CORE_KX_STATE_REKEY_SENT
We're rekeying (or had a timeout), so we have sent the other peer our new ephemeral key,...

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
cfgconfiguration to use
clsclosure for the various callbacks that follow (including handlers in the handlers array)
initcallback to call once we have successfully connected to the core service
connectsfunction to call on peer connect, can be NULL
disconnectsfunction to call on peer disconnect / timeout, can be NULL
handlerscallbacks 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
cfgconfiguration to use
clsclosure for the various callbacks that follow (including handlers in the handlers array)
initcallback to call once we have successfully connected to the core service
connectsfunction to call on peer connect, can be NULL
disconnectsfunction to call on peer disconnect / timeout, can be NULL
handlerscallbacks 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.

697{
698 struct GNUNET_CORE_Handle *h;
699
701 h->cfg = cfg;
702 h->cls = cls;
703 h->init = init;
704 h->connects = connects;
705 h->disconnects = disconnects;
707 h->handlers = GNUNET_MQ_copy_handlers (handlers);
709 GNUNET_assert (h->hcnt <
710 (GNUNET_MAX_MESSAGE_SIZE - sizeof(struct InitMessage))
711 / sizeof(uint16_t));
712 LOG (GNUNET_ERROR_TYPE_DEBUG, "Connecting to CORE service\n");
713 reconnect (h);
714 if (NULL == h->mq)
715 {
717 return NULL;
718 }
719 return h;
720}
struct GNUNET_MQ_MessageHandlers handlers[]
Definition: 003.c:1
void * connects(void *cls, const struct GNUNET_PeerIdentity *peer, struct GNUNET_MQ_Handle *mq)
Definition: 010.c:2
void disconnects(void *cls, const struct GNUNET_PeerIdentity *peer)
Definition: 011.c:2
static void reconnect(struct GNUNET_CORE_Handle *h)
Our current client connection went down.
Definition: core_api.c:629
#define LOG(kind,...)
Definition: core_api.c:32
static struct GNUNET_ARM_Handle * h
Connection with ARM.
Definition: gnunet-arm.c:99
static struct GNUNET_CONFIGURATION_Handle * cfg
Our configuration.
Definition: gnunet-arm.c:109
static char * init
Set to the name of a service to start.
Definition: gnunet-arm.c:74
#define GNUNET_MAX_MESSAGE_SIZE
Largest supported message (to be precise, one byte more than the largest possible message,...
void GNUNET_CORE_disconnect(struct GNUNET_CORE_Handle *handle)
Disconnect from the core service.
Definition: core_api.c:729
struct GNUNET_CONTAINER_MultiPeerMap * GNUNET_CONTAINER_multipeermap_create(unsigned int len, int do_not_copy_keys)
Create a multi peer map (hash map for public keys of peers).
@ GNUNET_NO
#define GNUNET_assert(cond)
Use this for fatal errors that cannot be handled.
@ GNUNET_ERROR_TYPE_DEBUG
#define GNUNET_new(type)
Allocate a struct or union of the given type.
struct GNUNET_MQ_MessageHandler * GNUNET_MQ_copy_handlers(const struct GNUNET_MQ_MessageHandler *handlers)
Copy an array of handlers.
Definition: mq.c:957
unsigned int GNUNET_MQ_count_handlers(const struct GNUNET_MQ_MessageHandler *handlers)
Count the handlers in a handler array.
Definition: mq.c:1000
struct GNUNET_MQ_Handle * mq
Our connection to the ARM service.
Definition: arm_api.c:107
const struct GNUNET_CONFIGURATION_Handle * cfg
The configuration that we are using.
Definition: arm_api.c:112
Context for the core service connection.
Definition: core_api.c:78
void * cls
Closure for the various callbacks.
Definition: core_api.c:87
Message transmitted core clients to gnunet-service-core to start the interaction.
Definition: core.h:82

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
handleconnection to core to disconnect

Definition at line 729 of file core_api.c.

730{
731 LOG (GNUNET_ERROR_TYPE_DEBUG, "Disconnecting from CORE service\n");
734 handle);
736 handle->peers = NULL;
737 if (NULL != handle->reconnect_task)
738 {
739 GNUNET_SCHEDULER_cancel (handle->reconnect_task);
740 handle->reconnect_task = NULL;
741 }
742 if (NULL != handle->mq)
743 {
745 handle->mq = NULL;
746 }
747 GNUNET_free (handle->handlers);
749}
static int disconnect_and_free_peer_entry(void *cls, const struct GNUNET_PeerIdentity *key, void *value)
Notify clients about disconnect and free the entry for connected peer.
Definition: core_api.c:183
static struct GNUNET_VPN_Handle * handle
Handle to vpn service.
Definition: gnunet-vpn.c:35
void GNUNET_CONTAINER_multipeermap_destroy(struct GNUNET_CONTAINER_MultiPeerMap *map)
Destroy a hash map.
int GNUNET_CONTAINER_multipeermap_iterate(struct GNUNET_CONTAINER_MultiPeerMap *map, GNUNET_CONTAINER_PeerMapIterator it, void *it_cls)
Iterate over all entries in the map.
#define GNUNET_free(ptr)
Wrapper around free.
void GNUNET_MQ_destroy(struct GNUNET_MQ_Handle *mq)
Destroy the message queue.
Definition: mq.c:683
void * GNUNET_SCHEDULER_cancel(struct GNUNET_SCHEDULER_Task *task)
Cancel the task with the specified identifier.
Definition: scheduler.c:975
struct GNUNET_MQ_Handle * mq
Connection to VPN service.
Definition: vpn_api.c:44

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
hthe core handle
pidthe identity of the peer
Returns
NULL if pid is not connected
Parameters
hthe core handle
pidthe 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.

762{
763 struct PeerRecord *pr;
764
766 if (NULL == pr)
767 return NULL;
768 return pr->mq;
769}
static struct GNUNET_PeerIdentity pid
Identity of the peer we transmit to / connect to.
void * GNUNET_CONTAINER_multipeermap_get(const struct GNUNET_CONTAINER_MultiPeerMap *map, const struct GNUNET_PeerIdentity *key)
Given a key find a value in the map matching the key.
Information we track for each peer.
Definition: core_api.c:39
struct GNUNET_MQ_Handle * mq
Message queue for the peer.
Definition: core_api.c:48

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
cfgconfiguration handle
peer_cbfunction to call with the peer information
peer_cb_clsclosure for peer_cb
Returns
NULL on error

Definition at line 158 of file core_api_monitor_peers.c.

161{
163
164 GNUNET_assert (NULL != peer_cb);
166 mh->cfg = cfg;
167 reconnect (mh);
168 mh->peer_cb = peer_cb;
169 mh->peer_cb_cls = peer_cb_cls;
170 if (NULL == mh->mq)
171 {
172 GNUNET_free (mh);
173 return NULL;
174 }
175 return mh;
176}
static void reconnect(struct GNUNET_CORE_MonitorHandle *mh)
Protocol error, reconnect to CORE service and notify client.
static struct GNUNET_CADET_Handle * mh
Cadet handle.
Definition: gnunet-cadet.c:92
const struct GNUNET_CONFIGURATION_Handle * cfg
Configuration given by the client, in case of reconnection.
Definition: cadet_api.c:63
struct GNUNET_MQ_Handle * mq
Message queue.
Definition: cadet_api.c:43
Handle to a CORE monitoring operation.
GNUNET_CORE_MonitorCallback peer_cb
Function called with the peer.
void * peer_cb_cls
Closure for peer_cb.

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
mhmonitor to stop

Definition at line 185 of file core_api_monitor_peers.c.

186{
187 if (NULL != mh->mq)
188 {
190 mh->mq = NULL;
191 }
192 GNUNET_free (mh);
193}

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
hthe core handle
pidthe 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
hthe core handle
targetthe target peer for this queue, may not be NULL
Returns
a message queue for sending messages over the core handle to the target peer