GNUnet  0.10.x
Macros | Typedefs | Enumerations | Functions
Core service

Encrypted direct communication between peers. 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 49 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 66 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 80 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 98 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 244 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 176 of file gnunet_core_service.h.

177 {
182 
187 
192 
199 
209 
215 
222 
231 
232 };
We've received the other peers session key.
This is not a state in a peer's state machine, but a special value used with the GNUNET_CORE_MonitorC...
The other peer has confirmed our session key + PING with a PONG message encrypted with their session ...
Last state of a KX (when it is being terminated).
We've sent our session key.
This is not a state in a peer's state machine, but a special value used with the GNUNET_CORE_MonitorC...
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 694 of file core_api.c.

700 {
701  struct GNUNET_CORE_Handle *h;
702 
703  h = GNUNET_new (struct GNUNET_CORE_Handle);
704  h->cfg = cfg;
705  h->cls = cls;
706  h->init = init;
707  h->connects = connects;
710  h->handlers = GNUNET_MQ_copy_handlers (handlers);
711  h->hcnt = GNUNET_MQ_count_handlers (handlers);
712  GNUNET_assert (h->hcnt <
713  (GNUNET_MAX_MESSAGE_SIZE - sizeof (struct InitMessage)) /
714  sizeof (uint16_t));
715  LOG (GNUNET_ERROR_TYPE_DEBUG, "Connecting to CORE service\n");
716  reconnect (h);
717  if (NULL == h->mq)
718  {
720  return NULL;
721  }
722  return h;
723 }
Context for the core service connection.
Definition: core_api.c:78
GNUNET_CORE_StartupCallback init
Function to call once we&#39;ve handshaked with the core service.
Definition: core_api.c:94
GNUNET_CORE_ConnectEventHandler connects
Function to call whenever we&#39;re notified about a peer connecting.
Definition: core_api.c:99
#define LOG(kind,...)
Definition: core_api.c:32
#define GNUNET_assert(cond)
Use this for fatal errors that cannot be handled.
struct GNUNET_MQ_MessageHandler * GNUNET_MQ_copy_handlers(const struct GNUNET_MQ_MessageHandler *handlers)
Copy an array of handlers.
Definition: mq.c:1193
void * cls
Closure for the various callbacks.
Definition: core_api.c:89
const struct GNUNET_CONFIGURATION_Handle * cfg
Configuration we&#39;re using.
Definition: core_api.c:84
#define GNUNET_NO
Definition: gnunet_common.h:81
#define GNUNET_new(type)
Allocate a struct or union of the given type.
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).
Message transmitted core clients to gnunet-service-core to start the interaction. ...
Definition: core.h:83
static struct GNUNET_ARM_Handle * h
Connection with ARM.
Definition: gnunet-arm.c:94
struct GNUNET_MQ_Handle * mq
Our message queue for transmissions to the service.
Definition: core_api.c:114
void * connects(void *cls, const struct GNUNET_PeerIdentity *peer, struct GNUNET_MQ_Handle *mq)
Definition: 010.c:2
unsigned int GNUNET_MQ_count_handlers(const struct GNUNET_MQ_MessageHandler *handlers)
Count the handlers in a handler array.
Definition: mq.c:1253
static struct GNUNET_CONFIGURATION_Handle * cfg
Our configuration.
Definition: gnunet-arm.c:104
void disconnects(void *cls, const struct GNUNET_PeerIdentity *peer)
Definition: 011.c:2
void GNUNET_CORE_disconnect(struct GNUNET_CORE_Handle *handle)
Disconnect from the core service.
Definition: core_api.c:732
struct GNUNET_MQ_MessageHandler * handlers
Function handlers for messages of particular type.
Definition: core_api.c:109
static char * init
Set to the name of a service to start.
Definition: gnunet-arm.c:69
#define GNUNET_MAX_MESSAGE_SIZE
Largest supported message (to be precise, one byte more than the largest possible message...
struct GNUNET_CONTAINER_MultiPeerMap * peers
Hash map listing all of the peers that we are currently connected to.
Definition: core_api.c:120
static void reconnect(struct GNUNET_CORE_Handle *h)
Our current client connection went down.
Definition: core_api.c:632
unsigned int hcnt
Number of entries in the handlers array.
Definition: core_api.c:140
GNUNET_CORE_DisconnectEventHandler disconnects
Function to call whenever we&#39;re notified about a peer disconnecting.
Definition: core_api.c:104

◆ 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 732 of file core_api.c.

References disconnect_and_free_peer_entry(), GNUNET_CONTAINER_multipeermap_destroy(), GNUNET_CONTAINER_multipeermap_iterate(), GNUNET_ERROR_TYPE_DEBUG, GNUNET_free, GNUNET_free_non_null, GNUNET_MQ_destroy(), GNUNET_SCHEDULER_cancel(), GNUNET_CORE_Handle::handlers, LOG, GNUNET_CORE_Handle::mq, GNUNET_CORE_Handle::peers, and GNUNET_CORE_Handle::reconnect_task.

Referenced by cleaning_task(), core_disconnect_adapter(), GCO_shutdown(), GDS_NEIGHBOURS_done(), GNUNET_CORE_connect(), oprelease_get_handle_core(), and shutdown_task().

733 {
734  LOG (GNUNET_ERROR_TYPE_DEBUG, "Disconnecting from CORE service\n");
737  handle);
739  handle->peers = NULL;
740  if (NULL != handle->reconnect_task)
741  {
743  handle->reconnect_task = NULL;
744  }
745  if (NULL != handle->mq)
746  {
747  GNUNET_MQ_destroy (handle->mq);
748  handle->mq = NULL;
749  }
750  GNUNET_free_non_null (handle->handlers);
751  GNUNET_free (handle);
752 }
#define LOG(kind,...)
Definition: core_api.c:32
#define GNUNET_free_non_null(ptr)
Free the memory pointed to by ptr if ptr is not NULL.
struct GNUNET_SCHEDULER_Task * reconnect_task
ID of reconnect task (if any).
Definition: core_api.c:130
void GNUNET_CONTAINER_multipeermap_destroy(struct GNUNET_CONTAINER_MultiPeerMap *map)
Destroy a hash map.
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:186
struct GNUNET_MQ_Handle * mq
Our message queue for transmissions to the service.
Definition: core_api.c:114
struct GNUNET_MQ_MessageHandler * handlers
Function handlers for messages of particular type.
Definition: core_api.c:109
struct GNUNET_CONTAINER_MultiPeerMap * peers
Hash map listing all of the peers that we are currently connected to.
Definition: core_api.c:120
int GNUNET_CONTAINER_multipeermap_iterate(struct GNUNET_CONTAINER_MultiPeerMap *map, GNUNET_CONTAINER_PeerMapIterator it, void *it_cls)
Iterate over all entries in the map.
void GNUNET_MQ_destroy(struct GNUNET_MQ_Handle *mq)
Destroy the message queue.
Definition: mq.c:824
#define GNUNET_free(ptr)
Wrapper around free.
void * GNUNET_SCHEDULER_cancel(struct GNUNET_SCHEDULER_Task *task)
Cancel the task with the specified identifier.
Definition: scheduler.c:965
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 763 of file core_api.c.

References GNUNET_CONTAINER_multipeermap_get(), PeerRecord::mq, and GNUNET_CORE_Handle::peers.

Referenced by occ_cache_get_handle_core_cb().

765 {
766  struct PeerRecord *pr;
767 
769  if (NULL == pr)
770  return NULL;
771  return pr->mq;
772 }
Information we track for each peer.
Definition: core_api.c:38
struct GNUNET_MQ_Handle * mq
Message queue for the peer.
Definition: core_api.c:49
struct GNUNET_CONTAINER_MultiPeerMap * peers
Hash map listing all of the peers that we are currently connected to.
Definition: core_api.c:120
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.
Here is the call graph for this function:
Here is the caller 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 159 of file core_api_monitor_peers.c.

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

Referenced by run().

162 {
164 
165  GNUNET_assert (NULL != peer_cb);
167  mh->cfg = cfg;
168  reconnect (mh);
169  mh->peer_cb = peer_cb;
170  mh->peer_cb_cls = peer_cb_cls;
171  if (NULL == mh->mq)
172  {
173  GNUNET_free (mh);
174  return NULL;
175  }
176  return mh;
177 }
const struct GNUNET_CONFIGURATION_Handle * cfg
Our configuration.
static void reconnect(struct GNUNET_CORE_MonitorHandle *mh)
Protocol error, reconnect to CORE service and notify client.
struct GNUNET_MQ_Handle * mq
Our connection to the service.
#define GNUNET_assert(cond)
Use this for fatal errors that cannot be handled.
static struct GNUNET_CADET_Handle * mh
Cadet handle.
Definition: gnunet-cadet.c:92
Handle to a CORE monitoring operation.
#define GNUNET_new(type)
Allocate a struct or union of the given type.
static struct GNUNET_CONFIGURATION_Handle * cfg
Our configuration.
Definition: gnunet-arm.c:104
void * peer_cb_cls
Closure for peer_cb.
GNUNET_CORE_MonitorCallback peer_cb
Function called with the peer.
#define GNUNET_free(ptr)
Wrapper around free.
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 186 of file core_api_monitor_peers.c.

References GNUNET_free, GNUNET_MQ_destroy(), and GNUNET_CORE_MonitorHandle::mq.

Referenced by shutdown_task().

187 {
188  if (NULL != mh->mq)
189  {
190  GNUNET_MQ_destroy (mh->mq);
191  mh->mq = NULL;
192  }
193  GNUNET_free (mh);
194 }
struct GNUNET_MQ_Handle * mq
Our connection to the service.
void GNUNET_MQ_destroy(struct GNUNET_MQ_Handle *mq)
Destroy the message queue.
Definition: mq.c:824
#define GNUNET_free(ptr)
Wrapper around free.
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 cirumstances (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