GNUnet  0.17.6
gnunet_dht_service.h
Go to the documentation of this file.
1 /*
2  This file is part of GNUnet
3  Copyright (C) 2004-2013, 2016, 2022 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 
40 #ifndef GNUNET_DHT_SERVICE_H
41 #define GNUNET_DHT_SERVICE_H
42 
43 #include "gnunet_util_lib.h"
44 #include "gnunet_block_lib.h"
45 #include "gnunet_hello_lib.h"
46 
47 #ifdef __cplusplus
48 extern "C"
49 {
50 #if 0 /* keep Emacsens' auto-indent happy */
51 }
52 #endif
53 #endif
54 
55 
59 #define GNUNET_DHT_DEFAULT_REPUBLISH_FREQUENCY GNUNET_TIME_relative_multiply ( \
60  GNUNET_TIME_UNIT_MINUTES, 60)
61 
62 
66 #define GNUNET_DHT_MAXIMUM_REPLICATION_LEVEL 16
67 
68 
72 struct GNUNET_DHT_Handle;
73 
78 
82 struct GNUNET_DHT_FindPeerHandle;
83 
84 
89 {
94 
101 
107 
112 
117 
122  GNUNET_DHT_RO_LAST_HOP = 32768
123 };
124 
125 
127 
132 {
137 
142 
147 
152  struct GNUNET_PeerIdentity pred;
153 
157  struct GNUNET_PeerIdentity succ;
158 };
159 
160 
167 {
173 
184  struct GNUNET_PeerIdentity pred;
185 
186 };
187 
188 
190 
199 struct GNUNET_DHT_Handle *
201  unsigned int ht_len);
202 
203 
209 void
211 
212 
213 /* *************** Standard API: get and put ******************* */
214 
215 
219 struct GNUNET_DHT_PutHandle;
220 
221 
240 struct GNUNET_DHT_PutHandle *
242  const struct GNUNET_HashCode *key,
243  uint32_t desired_replication_level,
245  enum GNUNET_BLOCK_Type type,
246  size_t size,
247  const void *data,
248  struct GNUNET_TIME_Absolute exp,
250  void *cont_cls);
251 
252 
264 void
266 
267 
288 typedef void
289 (*GNUNET_DHT_GetIterator) (void *cls,
290  struct GNUNET_TIME_Absolute exp,
291  const struct GNUNET_HashCode *query_hash,
292  const struct GNUNET_PeerIdentity *trunc_peer,
293  const struct GNUNET_DHT_PathElement *get_path,
294  unsigned int get_path_length,
295  const struct GNUNET_DHT_PathElement *put_path,
296  unsigned int put_path_length,
297  enum GNUNET_BLOCK_Type type,
298  size_t size,
299  const void *data);
300 
301 
318 struct GNUNET_DHT_GetHandle *
320  enum GNUNET_BLOCK_Type type,
321  const struct GNUNET_HashCode *key,
322  uint32_t desired_replication_level,
324  const void *xquery,
325  size_t xquery_size,
327  void *iter_cls);
328 
329 
340 void
342  unsigned int num_results,
343  const struct GNUNET_HashCode *results);
344 
350 void
352 
353 
354 /* *************** Extended API: monitor ******************* */
355 
360 
371 typedef void
372 (*GNUNET_DHT_MonitorGetCB) (void *cls,
374  enum GNUNET_BLOCK_Type type,
375  uint32_t hop_count,
376  uint32_t desired_replication_level,
377  const struct GNUNET_HashCode *key);
378 
379 
397 typedef void
398 (*GNUNET_DHT_MonitorGetRespCB) (void *cls,
399  enum GNUNET_BLOCK_Type type,
400  const struct GNUNET_PeerIdentity *trunc_peer,
401  const struct GNUNET_DHT_PathElement *get_path,
402  unsigned int get_path_length,
403  const struct GNUNET_DHT_PathElement *put_path,
404  unsigned int put_path_length,
405  struct GNUNET_TIME_Absolute exp,
406  const struct GNUNET_HashCode *key,
407  const void *data,
408  size_t size);
409 
410 
429 typedef void
430 (*GNUNET_DHT_MonitorPutCB) (void *cls,
432  enum GNUNET_BLOCK_Type type,
433  uint32_t hop_count,
434  uint32_t desired_replication_level,
435  const struct GNUNET_PeerIdentity *trunc_peer,
436  unsigned int path_length,
437  const struct GNUNET_DHT_PathElement *path,
438  struct GNUNET_TIME_Absolute exp,
439  const struct GNUNET_HashCode *key,
440  const void *data,
441  size_t size);
442 
443 
458  enum GNUNET_BLOCK_Type type,
459  const struct GNUNET_HashCode *key,
463  void *cb_cls);
464 
465 
473 void
475 
476 
484 char *
485 GNUNET_DHT_pp2s (const struct GNUNET_DHT_PathElement *path,
486  unsigned int path_len);
487 
488 
509 unsigned int
510 GNUNET_DHT_verify_path (const void *data,
511  size_t data_size,
512  struct GNUNET_TIME_Absolute exp_time,
513  const struct GNUNET_PeerIdentity *trunc_peer,
514  const struct GNUNET_DHT_PathElement *put_path,
515  unsigned int put_path_len,
516  const struct GNUNET_DHT_PathElement *get_path,
517  unsigned int get_path_len,
518  const struct GNUNET_PeerIdentity *me);
519 
520 
525 
526 
533 typedef void
534 (*GNUNET_DHT_HelloGetCallback)(void *cls,
535  const char *hello_url);
536 
537 
549  void *cb_cls);
550 
551 
557 void
559 
560 
571 void
573  const char *url,
575  void *cb_cls);
576 
577 
578 #if 0 /* keep Emacsens' auto-indent happy */
579 {
580 #endif
581 #ifdef __cplusplus
582 }
583 #endif
584 
585 #endif
586  /* end of group dht */
588  /* end of group addition */
590  /* end of group addition */
struct GNUNET_GETOPT_CommandLineOption options[]
Definition: 002.c:5
dht_handle
Definition: 018.c:1
GNUNET_BLOCK_Type
WARNING: This header is generated! In order to add DHT block types, you must register them in GANA,...
static const struct GNUNET_CONFIGURATION_Handle * cfg
Configuration we are using.
Definition: gnunet-abd.c:36
static size_t data_size
Number of bytes in data.
Definition: gnunet-abd.c:187
static struct GNUNET_ATS_PerformanceHandle * ph
ATS performance handle used.
Definition: gnunet-ats.c:116
static GNUNET_NETWORK_STRUCT_END struct GNUNET_PeerIdentity me
Our own peer identity.
static struct GNUNET_DHT_GetHandle * get_handle
Handle for the get request.
struct GNUNET_HashCode key
The key used in the DHT.
static struct GNUNET_DNS_Handle * handle
Handle to transport service.
uint32_t data
The data value.
static unsigned int results
Library for data block manipulation.
Helper library for handling HELLOs.
void GNUNET_DHT_put_cancel(struct GNUNET_DHT_PutHandle *ph)
Cancels a DHT PUT operation.
Definition: dht_api.c:1148
GNUNET_DHT_RouteOption
Options for routing.
char * GNUNET_DHT_pp2s(const struct GNUNET_DHT_PathElement *path, unsigned int path_len)
Convert a peer path to a human-readable string.
Definition: dht_api.c:1330
struct GNUNET_DHT_MonitorHandle * GNUNET_DHT_monitor_start(struct GNUNET_DHT_Handle *handle, enum GNUNET_BLOCK_Type type, const struct GNUNET_HashCode *key, GNUNET_DHT_MonitorGetCB get_cb, GNUNET_DHT_MonitorGetRespCB get_resp_cb, GNUNET_DHT_MonitorPutCB put_cb, void *cb_cls)
Start monitoring the local DHT service.
Definition: dht_api.c:1270
void GNUNET_DHT_hello_get_cancel(struct GNUNET_DHT_HelloGetHandle *hgh)
Cancel hello get operation.
Definition: dht_api.c:1468
void GNUNET_DHT_get_stop(struct GNUNET_DHT_GetHandle *get_handle)
Stop async DHT-get.
Definition: dht_api.c:1237
void GNUNET_DHT_get_filter_known_results(struct GNUNET_DHT_GetHandle *get_handle, unsigned int num_results, const struct GNUNET_HashCode *results)
Tell the DHT not to return any of the following known results to this client.
Definition: dht_api.c:1213
void(* GNUNET_DHT_GetIterator)(void *cls, struct GNUNET_TIME_Absolute exp, const struct GNUNET_HashCode *query_hash, const struct GNUNET_PeerIdentity *trunc_peer, const struct GNUNET_DHT_PathElement *get_path, unsigned int get_path_length, const struct GNUNET_DHT_PathElement *put_path, unsigned int put_path_length, enum GNUNET_BLOCK_Type type, size_t size, const void *data)
Iterator called on each result obtained for a DHT operation that expects a reply.
struct GNUNET_DHT_Handle * GNUNET_DHT_connect(const struct GNUNET_CONFIGURATION_Handle *cfg, unsigned int ht_len)
Initialize the connection with the DHT service.
Definition: dht_api.c:1039
void(* GNUNET_DHT_MonitorGetRespCB)(void *cls, enum GNUNET_BLOCK_Type type, const struct GNUNET_PeerIdentity *trunc_peer, const struct GNUNET_DHT_PathElement *get_path, unsigned int get_path_length, const struct GNUNET_DHT_PathElement *put_path, unsigned int put_path_length, struct GNUNET_TIME_Absolute exp, const struct GNUNET_HashCode *key, const void *data, size_t size)
Callback called on each GET reply going through the DHT.
void(* GNUNET_DHT_MonitorGetCB)(void *cls, enum GNUNET_DHT_RouteOption options, enum GNUNET_BLOCK_Type type, uint32_t hop_count, uint32_t desired_replication_level, const struct GNUNET_HashCode *key)
Callback called on each GET request going through the DHT.
void(* GNUNET_DHT_HelloGetCallback)(void *cls, const char *hello_url)
Signature called with the result of a HELLO GET operation.
struct GNUNET_DHT_PutHandle * GNUNET_DHT_put(struct GNUNET_DHT_Handle *handle, const struct GNUNET_HashCode *key, uint32_t desired_replication_level, enum GNUNET_DHT_RouteOption options, enum GNUNET_BLOCK_Type type, size_t size, const void *data, struct GNUNET_TIME_Absolute exp, GNUNET_SCHEDULER_TaskCallback cont, void *cont_cls)
Perform a PUT operation storing data in the DHT.
Definition: dht_api.c:1090
struct GNUNET_DHT_HelloGetHandle * GNUNET_DHT_hello_get(struct GNUNET_DHT_Handle *dht_handle, GNUNET_DHT_HelloGetCallback cb, void *cb_cls)
Obtain HELLO URL of the DHT identified by dht_handle.
Definition: dht_api.c:1444
void GNUNET_DHT_disconnect(struct GNUNET_DHT_Handle *handle)
Shutdown connection with the DHT service.
Definition: dht_api.c:1062
void GNUNET_DHT_hello_offer(struct GNUNET_DHT_Handle *dht_handle, const char *url, GNUNET_SCHEDULER_TaskCallback cb, void *cb_cls)
Offer HELLO URL of the DHT identified by dht_handle.
Definition: dht_api.c:1480
void(* GNUNET_DHT_MonitorPutCB)(void *cls, enum GNUNET_DHT_RouteOption options, enum GNUNET_BLOCK_Type type, uint32_t hop_count, uint32_t desired_replication_level, const struct GNUNET_PeerIdentity *trunc_peer, unsigned int path_length, const struct GNUNET_DHT_PathElement *path, struct GNUNET_TIME_Absolute exp, const struct GNUNET_HashCode *key, const void *data, size_t size)
Callback called on each PUT request going through the DHT.
struct GNUNET_DHT_GetHandle * GNUNET_DHT_get_start(struct GNUNET_DHT_Handle *handle, enum GNUNET_BLOCK_Type type, const struct GNUNET_HashCode *key, uint32_t desired_replication_level, enum GNUNET_DHT_RouteOption options, const void *xquery, size_t xquery_size, GNUNET_DHT_GetIterator iter, void *iter_cls)
Perform an asynchronous GET operation on the DHT identified.
Definition: dht_api.c:1164
unsigned int GNUNET_DHT_verify_path(const void *data, size_t data_size, struct GNUNET_TIME_Absolute exp_time, const struct GNUNET_PeerIdentity *trunc_peer, const struct GNUNET_DHT_PathElement *put_path, unsigned int put_path_len, const struct GNUNET_DHT_PathElement *get_path, unsigned int get_path_len, const struct GNUNET_PeerIdentity *me)
Verify signatures on a path consisting of put_path and get_path in reverse order (starting at the las...
Definition: dht_api.c:1353
void GNUNET_DHT_monitor_stop(struct GNUNET_DHT_MonitorHandle *handle)
Stop monitoring.
Definition: dht_api.c:1302
@ GNUNET_DHT_RO_TRUNCATED
Flag set if the path was truncated.
@ GNUNET_DHT_RO_NONE
Default.
@ GNUNET_DHT_RO_RECORD_ROUTE
We should keep track of the route that the message took in the P2P network.
@ GNUNET_DHT_RO_LAST_HOP
Flag given to monitors if this was the last hop for a GET/PUT.
@ GNUNET_DHT_RO_FIND_APPROXIMATE
Approximate results are fine.
@ GNUNET_DHT_RO_DEMULTIPLEX_EVERYWHERE
Each peer along the way should process the request (otherwise only peers locally closest to the key w...
#define GNUNET_NETWORK_STRUCT_BEGIN
Define as empty, GNUNET_PACKED should suffice, but this won't work on W32.
#define GNUNET_NETWORK_STRUCT_END
Define as empty, GNUNET_PACKED should suffice, but this won't work on W32;.
#define GNUNET_PACKED
gcc-ism to get packed structs.
void(* GNUNET_SCHEDULER_TaskCallback)(void *cls)
Signature of the main function of a task.
static unsigned int size
Size of the "table".
Definition: peer.c:67
static enum GNUNET_GenericReturnValue get_cb(void *cls, const struct GNUNET_HashCode *key, void *value)
Function called during GET to find matching blocks.
static enum GNUNET_GenericReturnValue put_cb(void *cls, const struct GNUNET_HashCode *key, void *value)
Function called during PUT to detect if an equivalent block already exists.
header of what an ECC signature signs this must be followed by "size - 8" bytes of the actual signed ...
an ECC signature using EdDSA.
Handle to a GET request.
Definition: dht_api.c:81
GNUNET_DHT_GetIterator iter
Iterator to call on data receipt.
Definition: dht_api.c:85
void * iter_cls
Closure for iter.
Definition: dht_api.c:90
size_t xquery_size
Size of the extended query, allocated at the end of this struct.
Definition: dht_api.c:116
uint32_t desired_replication_level
Desired replication level.
Definition: dht_api.c:121
Connection to the DHT service.
Definition: dht_api.c:237
Handle to get a HELLO URL from the DHT for manual bootstrapping.
Definition: dht_api.c:203
GNUNET_DHT_HelloGetCallback cb
Function to call with the result.
Definition: dht_api.c:218
void * cb_cls
Closure for cb.
Definition: dht_api.c:223
Message signed by a peer when doing path tracking.
struct GNUNET_HashCode h_data
Hash over the payload of the block.
struct GNUNET_CRYPTO_EccSignaturePurpose purpose
Must be GNUNET_SIGNATURE_PURPOSE_DHT_HOP.
struct GNUNET_TIME_AbsoluteNBO expiration_time
Expiration time of the block.
struct GNUNET_PeerIdentity pred
Previous hop the message was received from.
struct GNUNET_PeerIdentity succ
Next hop the message was forwarded to.
Handle to a monitoring request.
Definition: dht_api.c:151
GNUNET_DHT_MonitorGetRespCB get_resp_cb
Callback for each received message of type get response.
Definition: dht_api.c:185
void * cb_cls
Closure for get_cb, put_cb and get_resp_cb.
Definition: dht_api.c:195
A (signed) path tracking a block's flow through the DHT is represented by an array of path elements,...
struct GNUNET_PeerIdentity pred
Previous peer on the path (matches "pred" in the signed field).
struct GNUNET_CRYPTO_EddsaSignature sig
Signature affirming the hop of type GNUNET_SIGNATURE_PURPOSE_DHT_HOP.
Handle to a PUT request.
Definition: dht_api.c:45
void * cont_cls
Closure for cont.
Definition: dht_api.c:69
GNUNET_SCHEDULER_TaskCallback cont
Continuation to call when done.
Definition: dht_api.c:59
A 512-bit hashcode.
The identity of the host (wraps the signing key of the peer).
Time for absolute time used by GNUnet, in microseconds and in network byte order.
Time for absolute times used by GNUnet, in microseconds.
enum GNUNET_TESTBED_UnderlayLinkModelType type
the type of this model