diff options
Diffstat (limited to 'src/include/gnunet_block_lib.h')
-rw-r--r-- | src/include/gnunet_block_lib.h | 261 |
1 files changed, 76 insertions, 185 deletions
diff --git a/src/include/gnunet_block_lib.h b/src/include/gnunet_block_lib.h index 73b51252e..fdccbab78 100644 --- a/src/include/gnunet_block_lib.h +++ b/src/include/gnunet_block_lib.h | |||
@@ -1,6 +1,6 @@ | |||
1 | /* | 1 | /* |
2 | This file is part of GNUnet. | 2 | This file is part of GNUnet. |
3 | Copyright (C) 2010 GNUnet e.V. | 3 | Copyright (C) 2010, 2022 GNUnet e.V. |
4 | 4 | ||
5 | GNUnet is free software: you can redistribute it and/or modify it | 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 | 6 | under the terms of the GNU Affero General Public License as published |
@@ -19,6 +19,9 @@ | |||
19 | */ | 19 | */ |
20 | 20 | ||
21 | /** | 21 | /** |
22 | * @addtogroup dht_libs DHT and support libraries | ||
23 | * @{ | ||
24 | * | ||
22 | * @author Christian Grothoff | 25 | * @author Christian Grothoff |
23 | * | 26 | * |
24 | * @file | 27 | * @file |
@@ -31,7 +34,10 @@ | |||
31 | #ifndef GNUNET_BLOCK_LIB_H | 34 | #ifndef GNUNET_BLOCK_LIB_H |
32 | #define GNUNET_BLOCK_LIB_H | 35 | #define GNUNET_BLOCK_LIB_H |
33 | 36 | ||
37 | |||
34 | #include "gnunet_util_lib.h" | 38 | #include "gnunet_util_lib.h" |
39 | #include "gnunet_dht_block_types.h" | ||
40 | |||
35 | #ifdef __cplusplus | 41 | #ifdef __cplusplus |
36 | extern "C" | 42 | extern "C" |
37 | { | 43 | { |
@@ -42,181 +48,36 @@ extern "C" | |||
42 | 48 | ||
43 | 49 | ||
44 | /** | 50 | /** |
45 | * Blocks in the datastore and the datacache must have a unique type. | ||
46 | */ | ||
47 | enum GNUNET_BLOCK_Type | ||
48 | { | ||
49 | /** | ||
50 | * Any type of block, used as a wildcard when searching. Should | ||
51 | * never be attached to a specific block. | ||
52 | */ | ||
53 | GNUNET_BLOCK_TYPE_ANY = 0, | ||
54 | |||
55 | /** | ||
56 | * Data block (leaf) in the CHK tree. | ||
57 | */ | ||
58 | GNUNET_BLOCK_TYPE_FS_DBLOCK = 1, | ||
59 | |||
60 | /** | ||
61 | * Inner block in the CHK tree. | ||
62 | */ | ||
63 | GNUNET_BLOCK_TYPE_FS_IBLOCK = 2, | ||
64 | |||
65 | /** | ||
66 | * Legacy type, no longer in use. | ||
67 | */ | ||
68 | GNUNET_BLOCK_TYPE_FS_KBLOCK = 3, | ||
69 | |||
70 | /** | ||
71 | * Legacy type, no longer in use. | ||
72 | */ | ||
73 | GNUNET_BLOCK_TYPE_FS_SBLOCK = 4, | ||
74 | |||
75 | /** | ||
76 | * Legacy type, no longer in use. | ||
77 | */ | ||
78 | GNUNET_BLOCK_TYPE_FS_NBLOCK = 5, | ||
79 | |||
80 | /** | ||
81 | * Type of a block representing a block to be encoded on demand from disk. | ||
82 | * Should never appear on the network directly. | ||
83 | */ | ||
84 | GNUNET_BLOCK_TYPE_FS_ONDEMAND = 6, | ||
85 | |||
86 | /** | ||
87 | * Type of a block that contains a HELLO for a peer (for | ||
88 | * DHT and CADET find-peer operations). | ||
89 | */ | ||
90 | GNUNET_BLOCK_TYPE_DHT_HELLO = 7, | ||
91 | |||
92 | /** | ||
93 | * Block for testing. | ||
94 | */ | ||
95 | GNUNET_BLOCK_TYPE_TEST = 8, | ||
96 | |||
97 | /** | ||
98 | * Type of a block representing any type of search result | ||
99 | * (universal). Implemented in the context of #2564, replaces | ||
100 | * SBLOCKS, KBLOCKS and NBLOCKS. | ||
101 | */ | ||
102 | GNUNET_BLOCK_TYPE_FS_UBLOCK = 9, | ||
103 | |||
104 | /** | ||
105 | * Block for storing DNS exit service advertisements. | ||
106 | */ | ||
107 | GNUNET_BLOCK_TYPE_DNS = 10, | ||
108 | |||
109 | /** | ||
110 | * Block for storing record data | ||
111 | */ | ||
112 | GNUNET_BLOCK_TYPE_GNS_NAMERECORD = 11, | ||
113 | |||
114 | /** | ||
115 | * Block type for a revocation message by which a key is revoked. | ||
116 | */ | ||
117 | GNUNET_BLOCK_TYPE_REVOCATION = 12, | ||
118 | |||
119 | /** | ||
120 | * Block to store a cadet regex state | ||
121 | */ | ||
122 | GNUNET_BLOCK_TYPE_REGEX = 22, | ||
123 | |||
124 | /** | ||
125 | * Block to store a cadet regex accepting state | ||
126 | */ | ||
127 | GNUNET_BLOCK_TYPE_REGEX_ACCEPT = 23, | ||
128 | |||
129 | /** | ||
130 | * Block for testing set/consensus. If first byte of the block | ||
131 | * is non-zero, the block is considered invalid. | ||
132 | */ | ||
133 | GNUNET_BLOCK_TYPE_SET_TEST = 24, | ||
134 | |||
135 | /** | ||
136 | * Block type for consensus elements. | ||
137 | * Contains either special marker elements or a nested block. | ||
138 | */ | ||
139 | GNUNET_BLOCK_TYPE_CONSENSUS_ELEMENT = 25, | ||
140 | |||
141 | /** | ||
142 | * Block for testing set intersection. If first byte of the block | ||
143 | * is non-zero, the block is considered invalid. | ||
144 | */ | ||
145 | GNUNET_BLOCK_TYPE_SETI_TEST = 24, | ||
146 | |||
147 | /** | ||
148 | * Block for testing set union. If first byte of the block | ||
149 | * is non-zero, the block is considered invalid. | ||
150 | */ | ||
151 | GNUNET_BLOCK_TYPE_SETU_TEST = 24, | ||
152 | |||
153 | }; | ||
154 | |||
155 | |||
156 | /** | ||
157 | * Flags that can be set to control the evaluation. | ||
158 | */ | ||
159 | enum GNUNET_BLOCK_EvaluationOptions | ||
160 | { | ||
161 | /** | ||
162 | * Default behavior. | ||
163 | */ | ||
164 | GNUNET_BLOCK_EO_NONE = 0, | ||
165 | |||
166 | /** | ||
167 | * The block is obtained from the local database, skip cryptographic | ||
168 | * checks. | ||
169 | */ | ||
170 | GNUNET_BLOCK_EO_LOCAL_SKIP_CRYPTO = 1 | ||
171 | }; | ||
172 | |||
173 | |||
174 | /** | ||
175 | * Possible ways for how a block may relate to a query. | 51 | * Possible ways for how a block may relate to a query. |
176 | */ | 52 | */ |
177 | enum GNUNET_BLOCK_EvaluationResult | 53 | enum GNUNET_BLOCK_ReplyEvaluationResult |
178 | { | 54 | { |
179 | /** | ||
180 | * Valid result, and there may be more. | ||
181 | */ | ||
182 | GNUNET_BLOCK_EVALUATION_OK_MORE = 0, | ||
183 | 55 | ||
184 | /** | 56 | /** |
185 | * Last possible valid result. | 57 | * Specified block type not supported by any plugin. |
186 | */ | 58 | */ |
187 | GNUNET_BLOCK_EVALUATION_OK_LAST = 1, | 59 | GNUNET_BLOCK_REPLY_TYPE_NOT_SUPPORTED = -1, |
188 | 60 | ||
189 | /** | 61 | /** |
190 | * Valid result, but suppressed because it is a duplicate. | 62 | * Valid result, but suppressed because it is a duplicate. |
191 | */ | 63 | */ |
192 | GNUNET_BLOCK_EVALUATION_OK_DUPLICATE = 2, | 64 | GNUNET_BLOCK_REPLY_OK_DUPLICATE = 0, |
193 | |||
194 | /** | ||
195 | * Block does not match query (invalid result) | ||
196 | */ | ||
197 | GNUNET_BLOCK_EVALUATION_RESULT_INVALID = 3, | ||
198 | 65 | ||
199 | /** | 66 | /** |
200 | * Block does not match xquery (valid result, not relevant for the request) | 67 | * Block does not match xquery (valid result, not relevant for the request) |
201 | */ | 68 | */ |
202 | GNUNET_BLOCK_EVALUATION_RESULT_IRRELEVANT = 4, | 69 | GNUNET_BLOCK_REPLY_IRRELEVANT = 1, |
203 | 70 | ||
204 | /** | 71 | /** |
205 | * Query is valid, no reply given. | 72 | * Valid result, and there may be more. |
206 | */ | 73 | */ |
207 | GNUNET_BLOCK_EVALUATION_REQUEST_VALID = 10, | 74 | GNUNET_BLOCK_REPLY_OK_MORE = 2, |
208 | 75 | ||
209 | /** | 76 | /** |
210 | * Query format does not match block type (invalid query). For | 77 | * Last possible valid result. |
211 | * example, xquery not given or xquery_size not appropriate for | ||
212 | * type. | ||
213 | */ | 78 | */ |
214 | GNUNET_BLOCK_EVALUATION_REQUEST_INVALID = 11, | 79 | GNUNET_BLOCK_REPLY_OK_LAST = 3 |
215 | 80 | ||
216 | /** | ||
217 | * Specified block type not supported by this plugin. | ||
218 | */ | ||
219 | GNUNET_BLOCK_EVALUATION_TYPE_NOT_SUPPORTED = 20 | ||
220 | }; | 81 | }; |
221 | 82 | ||
222 | 83 | ||
@@ -271,7 +132,6 @@ struct GNUNET_BLOCK_Group; | |||
271 | * | 132 | * |
272 | * @param ctx block context in which the block group is created | 133 | * @param ctx block context in which the block group is created |
273 | * @param type type of the block for which we are creating the group | 134 | * @param type type of the block for which we are creating the group |
274 | * @param nonce random value used to seed the group creation | ||
275 | * @param raw_data optional serialized prior state of the group, NULL if unavailable/fresh | 135 | * @param raw_data optional serialized prior state of the group, NULL if unavailable/fresh |
276 | * @param raw_data_size number of bytes in @a raw_data, 0 if unavailable/fresh | 136 | * @param raw_data_size number of bytes in @a raw_data, 0 if unavailable/fresh |
277 | * @param ... type-specific additional data, can be empty | 137 | * @param ... type-specific additional data, can be empty |
@@ -281,7 +141,6 @@ struct GNUNET_BLOCK_Group; | |||
281 | struct GNUNET_BLOCK_Group * | 141 | struct GNUNET_BLOCK_Group * |
282 | GNUNET_BLOCK_group_create (struct GNUNET_BLOCK_Context *ctx, | 142 | GNUNET_BLOCK_group_create (struct GNUNET_BLOCK_Context *ctx, |
283 | enum GNUNET_BLOCK_Type type, | 143 | enum GNUNET_BLOCK_Type type, |
284 | uint32_t nonce, | ||
285 | const void *raw_data, | 144 | const void *raw_data, |
286 | size_t raw_data_size, | 145 | size_t raw_data_size, |
287 | ...); | 146 | ...); |
@@ -291,15 +150,13 @@ GNUNET_BLOCK_group_create (struct GNUNET_BLOCK_Context *ctx, | |||
291 | * Serialize state of a block group. | 150 | * Serialize state of a block group. |
292 | * | 151 | * |
293 | * @param bg group to serialize | 152 | * @param bg group to serialize |
294 | * @param[out] nonce set to the nonce of the @a bg | ||
295 | * @param[out] raw_data set to the serialized state | 153 | * @param[out] raw_data set to the serialized state |
296 | * @param[out] raw_data_size set to the number of bytes in @a raw_data | 154 | * @param[out] raw_data_size set to the number of bytes in @a raw_data |
297 | * @return #GNUNET_OK on success, #GNUNET_NO if serialization is not | 155 | * @return #GNUNET_OK on success, #GNUNET_NO if serialization is not |
298 | * supported, #GNUNET_SYSERR on error | 156 | * supported, #GNUNET_SYSERR on error |
299 | */ | 157 | */ |
300 | int | 158 | enum GNUNET_GenericReturnValue |
301 | GNUNET_BLOCK_group_serialize (struct GNUNET_BLOCK_Group *bg, | 159 | GNUNET_BLOCK_group_serialize (struct GNUNET_BLOCK_Group *bg, |
302 | uint32_t *nonce, | ||
303 | void **raw_data, | 160 | void **raw_data, |
304 | size_t *raw_data_size); | 161 | size_t *raw_data_size); |
305 | 162 | ||
@@ -314,16 +171,12 @@ GNUNET_BLOCK_group_destroy (struct GNUNET_BLOCK_Group *bg); | |||
314 | 171 | ||
315 | 172 | ||
316 | /** | 173 | /** |
317 | * Function called to validate a reply or a request. For | 174 | * Function called to validate if a reply is good for a |
318 | * request evaluation, simply pass "NULL" for the @a reply_block. | 175 | * particular query. |
319 | * Note that it is assumed that the reply has already been | ||
320 | * matched to the key (and signatures checked) as it would | ||
321 | * be done with the #GNUNET_BLOCK_get_key() function. | ||
322 | * | 176 | * |
323 | * @param ctx block contxt | 177 | * @param ctx block contxt |
324 | * @param type block type | 178 | * @param type block type |
325 | * @param group block group to use for evaluation | 179 | * @param[in,out] group block group to use for evaluation |
326 | * @param eo evaluation options to control evaluation | ||
327 | * @param query original query (hash) | 180 | * @param query original query (hash) |
328 | * @param xquery extrended query data (can be NULL, depending on type) | 181 | * @param xquery extrended query data (can be NULL, depending on type) |
329 | * @param xquery_size number of bytes in @a xquery | 182 | * @param xquery_size number of bytes in @a xquery |
@@ -331,20 +184,57 @@ GNUNET_BLOCK_group_destroy (struct GNUNET_BLOCK_Group *bg); | |||
331 | * @param reply_block_size number of bytes in @a reply_block | 184 | * @param reply_block_size number of bytes in @a reply_block |
332 | * @return characterization of result | 185 | * @return characterization of result |
333 | */ | 186 | */ |
334 | enum GNUNET_BLOCK_EvaluationResult | 187 | enum GNUNET_BLOCK_ReplyEvaluationResult |
335 | GNUNET_BLOCK_evaluate (struct GNUNET_BLOCK_Context *ctx, | 188 | GNUNET_BLOCK_check_reply (struct GNUNET_BLOCK_Context *ctx, |
336 | enum GNUNET_BLOCK_Type type, | 189 | enum GNUNET_BLOCK_Type type, |
337 | struct GNUNET_BLOCK_Group *group, | 190 | struct GNUNET_BLOCK_Group *group, |
338 | enum GNUNET_BLOCK_EvaluationOptions eo, | 191 | const struct GNUNET_HashCode *query, |
339 | const struct GNUNET_HashCode *query, | 192 | const void *xquery, |
340 | const void *xquery, | 193 | size_t xquery_size, |
341 | size_t xquery_size, | 194 | const void *reply_block, |
342 | const void *reply_block, | 195 | size_t reply_block_size); |
343 | size_t reply_block_size); | ||
344 | 196 | ||
345 | 197 | ||
346 | /** | 198 | /** |
347 | * Function called to obtain the key for a block. | 199 | * Function called to validate a request. |
200 | * | ||
201 | * @param ctx block contxt | ||
202 | * @param type block type | ||
203 | * @param query original query (hash) | ||
204 | * @param xquery extrended query data (can be NULL, depending on type) | ||
205 | * @param xquery_size number of bytes in @a xquery | ||
206 | * @return #GNUNET_OK if the block is fine, #GNUNET_NO if not, | ||
207 | * #GNUNET_SYSERR if @a type is not supported | ||
208 | */ | ||
209 | enum GNUNET_GenericReturnValue | ||
210 | GNUNET_BLOCK_check_query (struct GNUNET_BLOCK_Context *ctx, | ||
211 | enum GNUNET_BLOCK_Type type, | ||
212 | const struct GNUNET_HashCode *query, | ||
213 | const void *xquery, | ||
214 | size_t xquery_size); | ||
215 | |||
216 | |||
217 | /** | ||
218 | * Function called to validate a block. | ||
219 | * | ||
220 | * @param ctx block contxt | ||
221 | * @param type block type | ||
222 | * @param block payload to put | ||
223 | * @param block_size number of bytes in @a block | ||
224 | * @return #GNUNET_OK if the block is fine, #GNUNET_NO if not, | ||
225 | * #GNUNET_SYSERR if @a type is not supported | ||
226 | */ | ||
227 | enum GNUNET_GenericReturnValue | ||
228 | GNUNET_BLOCK_check_block (struct GNUNET_BLOCK_Context *ctx, | ||
229 | enum GNUNET_BLOCK_Type type, | ||
230 | const void *block, | ||
231 | size_t block_size); | ||
232 | |||
233 | |||
234 | /** | ||
235 | * Function called to obtain the @a key for a @a block. | ||
236 | * If the @a block is malformed, the function should | ||
237 | * zero-out @a key and return #GNUNET_OK. | ||
348 | * | 238 | * |
349 | * @param ctx block context | 239 | * @param ctx block context |
350 | * @param type block type | 240 | * @param type block type |
@@ -352,11 +242,10 @@ GNUNET_BLOCK_evaluate (struct GNUNET_BLOCK_Context *ctx, | |||
352 | * @param block_size number of bytes in @a block | 242 | * @param block_size number of bytes in @a block |
353 | * @param key set to the key (query) for the given block | 243 | * @param key set to the key (query) for the given block |
354 | * @return #GNUNET_YES on success, | 244 | * @return #GNUNET_YES on success, |
355 | * #GNUNET_NO if the block is malformed | 245 | * #GNUNET_NO if extracting a key from a block of this @a type does not work |
356 | * #GNUNET_SYSERR if type not supported | 246 | * #GNUNET_SYSERR if @a type not supported |
357 | * (or if extracting a key from a block of this type does not work) | ||
358 | */ | 247 | */ |
359 | int | 248 | enum GNUNET_GenericReturnValue |
360 | GNUNET_BLOCK_get_key (struct GNUNET_BLOCK_Context *ctx, | 249 | GNUNET_BLOCK_get_key (struct GNUNET_BLOCK_Context *ctx, |
361 | enum GNUNET_BLOCK_Type type, | 250 | enum GNUNET_BLOCK_Type type, |
362 | const void *block, | 251 | const void *block, |
@@ -375,7 +264,7 @@ GNUNET_BLOCK_get_key (struct GNUNET_BLOCK_Context *ctx, | |||
375 | * @param seen_results_count number of entries in @a seen_results | 264 | * @param seen_results_count number of entries in @a seen_results |
376 | * @return #GNUNET_SYSERR if not supported, #GNUNET_OK on success | 265 | * @return #GNUNET_SYSERR if not supported, #GNUNET_OK on success |
377 | */ | 266 | */ |
378 | int | 267 | enum GNUNET_GenericReturnValue |
379 | GNUNET_BLOCK_group_set_seen (struct GNUNET_BLOCK_Group *bg, | 268 | GNUNET_BLOCK_group_set_seen (struct GNUNET_BLOCK_Group *bg, |
380 | const struct GNUNET_HashCode *seen_results, | 269 | const struct GNUNET_HashCode *seen_results, |
381 | unsigned int seen_results_count); | 270 | unsigned int seen_results_count); |
@@ -383,7 +272,7 @@ GNUNET_BLOCK_group_set_seen (struct GNUNET_BLOCK_Group *bg, | |||
383 | 272 | ||
384 | /** | 273 | /** |
385 | * Try merging two block groups. Afterwards, @a bg1 should remain | 274 | * Try merging two block groups. Afterwards, @a bg1 should remain |
386 | * valid and contain the rules from both @a bg1 and @bg2, and | 275 | * valid and contain the rules from both @a bg1 and @a bg2, and |
387 | * @a bg2 should be destroyed (as part of this call). The latter | 276 | * @a bg2 should be destroyed (as part of this call). The latter |
388 | * should happen even if merging is not supported. | 277 | * should happen even if merging is not supported. |
389 | * | 278 | * |
@@ -393,7 +282,7 @@ GNUNET_BLOCK_group_set_seen (struct GNUNET_BLOCK_Group *bg, | |||
393 | * #GNUNET_NO if merge failed due to different nonce | 282 | * #GNUNET_NO if merge failed due to different nonce |
394 | * #GNUNET_SYSERR if merging is not supported | 283 | * #GNUNET_SYSERR if merging is not supported |
395 | */ | 284 | */ |
396 | int | 285 | enum GNUNET_GenericReturnValue |
397 | GNUNET_BLOCK_group_merge (struct GNUNET_BLOCK_Group *bg1, | 286 | GNUNET_BLOCK_group_merge (struct GNUNET_BLOCK_Group *bg1, |
398 | struct GNUNET_BLOCK_Group *bg2); | 287 | struct GNUNET_BLOCK_Group *bg2); |
399 | 288 | ||
@@ -410,4 +299,6 @@ GNUNET_BLOCK_group_merge (struct GNUNET_BLOCK_Group *bg1, | |||
410 | 299 | ||
411 | /** @} */ /* end of group */ | 300 | /** @} */ /* end of group */ |
412 | 301 | ||
302 | /** @} */ /* end of group addition */ | ||
303 | |||
413 | /* end of gnunet_block_lib.h */ | 304 | /* end of gnunet_block_lib.h */ |