GNUnet  0.20.0
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 
44 #include "gnunet_util_lib.h"
45 #include "gnunet_block_lib.h"
46 #include "gnunet_hello_lib.h"
47 
48 #ifdef __cplusplus
49 extern "C"
50 {
51 #if 0 /* keep Emacsens' auto-indent happy */
52 }
53 #endif
54 #endif
55 
56 
60 #define GNUNET_DHT_DEFAULT_REPUBLISH_FREQUENCY GNUNET_TIME_relative_multiply ( \
61  GNUNET_TIME_UNIT_MINUTES, 60)
62 
63 
67 #define GNUNET_DHT_MAXIMUM_REPLICATION_LEVEL 16
68 
69 
73 struct GNUNET_DHT_Handle;
74 
79 
83 struct GNUNET_DHT_FindPeerHandle;
84 
85 
90 {
95 
102 
108 
113 
118 
123  GNUNET_DHT_RO_LAST_HOP = 32768
124 };
125 
126 
128 
133 {
138 
143 
148 
153  struct GNUNET_PeerIdentity pred;
154 
158  struct GNUNET_PeerIdentity succ;
159 };
160 
161 
168 {
174 
185  struct GNUNET_PeerIdentity pred;
186 
187 };
188 
189 
191 
200 struct GNUNET_DHT_Handle *
202  unsigned int ht_len);
203 
204 
210 void
212 
213 
214 /* *************** Standard API: get and put ******************* */
215 
216 
220 struct GNUNET_DHT_PutHandle;
221 
222 
241 struct GNUNET_DHT_PutHandle *
243  const struct GNUNET_HashCode *key,
244  uint32_t desired_replication_level,
246  enum GNUNET_BLOCK_Type type,
247  size_t size,
248  const void *data,
249  struct GNUNET_TIME_Absolute exp,
251  void *cont_cls);
252 
253 
265 void
267 
268 
289 typedef void
290 (*GNUNET_DHT_GetIterator) (void *cls,
291  struct GNUNET_TIME_Absolute exp,
292  const struct GNUNET_HashCode *query_hash,
293  const struct GNUNET_PeerIdentity *trunc_peer,
294  const struct GNUNET_DHT_PathElement *get_path,
295  unsigned int get_path_length,
296  const struct GNUNET_DHT_PathElement *put_path,
297  unsigned int put_path_length,
298  enum GNUNET_BLOCK_Type type,
299  size_t size,
300  const void *data);
301 
302 
319 struct GNUNET_DHT_GetHandle *
321  enum GNUNET_BLOCK_Type type,
322  const struct GNUNET_HashCode *key,
323  uint32_t desired_replication_level,
325  const void *xquery,
326  size_t xquery_size,
328  void *iter_cls);
329 
330 
341 void
343  unsigned int num_results,
344  const struct GNUNET_HashCode *results);
345 
351 void
353 
354 
355 /* *************** Extended API: monitor ******************* */
356 
361 
372 typedef void
373 (*GNUNET_DHT_MonitorGetCB) (void *cls,
375  enum GNUNET_BLOCK_Type type,
376  uint32_t hop_count,
377  uint32_t desired_replication_level,
378  const struct GNUNET_HashCode *key);
379 
380 
398 typedef void
399 (*GNUNET_DHT_MonitorGetRespCB) (void *cls,
400  enum GNUNET_BLOCK_Type type,
401  const struct GNUNET_PeerIdentity *trunc_peer,
402  const struct GNUNET_DHT_PathElement *get_path,
403  unsigned int get_path_length,
404  const struct GNUNET_DHT_PathElement *put_path,
405  unsigned int put_path_length,
406  struct GNUNET_TIME_Absolute exp,
407  const struct GNUNET_HashCode *key,
408  const void *data,
409  size_t size);
410 
411 
430 typedef void
431 (*GNUNET_DHT_MonitorPutCB) (void *cls,
433  enum GNUNET_BLOCK_Type type,
434  uint32_t hop_count,
435  uint32_t desired_replication_level,
436  const struct GNUNET_PeerIdentity *trunc_peer,
437  unsigned int path_length,
438  const struct GNUNET_DHT_PathElement *path,
439  struct GNUNET_TIME_Absolute exp,
440  const struct GNUNET_HashCode *key,
441  const void *data,
442  size_t size);
443 
444 
459  enum GNUNET_BLOCK_Type type,
460  const struct GNUNET_HashCode *key,
464  void *cb_cls);
465 
466 
474 void
476 
477 
485 char *
486 GNUNET_DHT_pp2s (const struct GNUNET_DHT_PathElement *path,
487  unsigned int path_len);
488 
489 
510 unsigned int
511 GNUNET_DHT_verify_path (const void *data,
512  size_t data_size,
513  struct GNUNET_TIME_Absolute exp_time,
514  const struct GNUNET_PeerIdentity *trunc_peer,
515  const struct GNUNET_DHT_PathElement *put_path,
516  unsigned int put_path_len,
517  const struct GNUNET_DHT_PathElement *get_path,
518  unsigned int get_path_len,
519  const struct GNUNET_PeerIdentity *me);
520 
521 
526 
527 
534 typedef void
535 (*GNUNET_DHT_HelloGetCallback)(void *cls,
536  const char *hello_url);
537 
538 
550  void *cb_cls);
551 
552 
558 void
560 
561 
572 void
574  const char *url,
576  void *cb_cls);
577 
578 
579 #if 0 /* keep Emacsens' auto-indent happy */
580 {
581 #endif
582 #ifdef __cplusplus
583 }
584 #endif
585 
586 #endif
587  /* end of group dht */
589  /* end of group addition */
591  /* 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:68
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