diff options
author | Christian Grothoff <christian@grothoff.org> | 2012-02-17 09:15:29 +0000 |
---|---|---|
committer | Christian Grothoff <christian@grothoff.org> | 2012-02-17 09:15:29 +0000 |
commit | 6b66d2f47c58508b0e9ebee9a646534809a36a7d (patch) | |
tree | 32b1c40714fac897b4ecd57b5b980843497eacdc /src/include/gnunet_namestore_service.h | |
parent | 349d176da232e5fdc6afd9c90ae02bf928365ac0 (diff) | |
download | gnunet-6b66d2f47c58508b0e9ebee9a646534809a36a7d.tar.gz gnunet-6b66d2f47c58508b0e9ebee9a646534809a36a7d.zip |
-draft for new API
Diffstat (limited to 'src/include/gnunet_namestore_service.h')
-rw-r--r-- | src/include/gnunet_namestore_service.h | 482 |
1 files changed, 482 insertions, 0 deletions
diff --git a/src/include/gnunet_namestore_service.h b/src/include/gnunet_namestore_service.h new file mode 100644 index 000000000..0865e8d63 --- /dev/null +++ b/src/include/gnunet_namestore_service.h | |||
@@ -0,0 +1,482 @@ | |||
1 | /* | ||
2 | This file is part of GNUnet | ||
3 | (C) 2012 Christian Grothoff (and other contributing authors) | ||
4 | |||
5 | GNUnet is free software; you can redistribute it and/or modify | ||
6 | it under the terms of the GNU General Public License as published | ||
7 | by the Free Software Foundation; either version 2, or (at your | ||
8 | 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 | General Public License for more details. | ||
14 | |||
15 | You should have received a copy of the GNU General Public License | ||
16 | along with GNUnet; see the file COPYING. If not, write to the | ||
17 | Free Software Foundation, Inc., 59 Temple Place - Suite 330, | ||
18 | Boston, MA 02111-1307, USA. | ||
19 | */ | ||
20 | |||
21 | /** | ||
22 | * @file include/gnunet_namestore_service.h | ||
23 | * @brief API that can be used to store naming information on a GNUnet node; | ||
24 | * @author Christian Grothoff | ||
25 | * | ||
26 | * Other functions we might want: | ||
27 | * - enumerate all known zones | ||
28 | * - convenience function to gather record and the full affilliated stree | ||
29 | * in one shot | ||
30 | */ | ||
31 | |||
32 | #ifndef GNUNET_NAMESTORE_SERVICE_H | ||
33 | #define GNUNET_NAMESTORE_SERVICE_H | ||
34 | |||
35 | #include "gnunet_util_lib.h" | ||
36 | #include "gnunet_block_lib.h" | ||
37 | |||
38 | #ifdef __cplusplus | ||
39 | extern "C" | ||
40 | { | ||
41 | #if 0 /* keep Emacsens' auto-indent happy */ | ||
42 | } | ||
43 | #endif | ||
44 | #endif | ||
45 | |||
46 | /** | ||
47 | * Entry in the queue. | ||
48 | */ | ||
49 | struct GNUNET_NAMESTORE_QueueEntry; | ||
50 | |||
51 | /** | ||
52 | * Handle to the namestore service. | ||
53 | */ | ||
54 | struct GNUNET_NAMESTORE_Handle; | ||
55 | |||
56 | /** | ||
57 | * Maximum size of a value that can be stored in the namestore. | ||
58 | */ | ||
59 | #define GNUNET_NAMESTORE_MAX_VALUE_SIZE (63 * 1024) | ||
60 | |||
61 | /** | ||
62 | * Connect to the namestore service. | ||
63 | * | ||
64 | * @param cfg configuration to use | ||
65 | * @return handle to use to access the service | ||
66 | */ | ||
67 | struct GNUNET_NAMESTORE_Handle * | ||
68 | GNUNET_NAMESTORE_connect (const struct GNUNET_CONFIGURATION_Handle *cfg); | ||
69 | |||
70 | |||
71 | /** | ||
72 | * Disconnect from the namestore service (and free | ||
73 | * associated resources). | ||
74 | * | ||
75 | * @param h handle to the namestore | ||
76 | * @param drop set to GNUNET_YES to delete all data in namestore (!) | ||
77 | */ | ||
78 | void | ||
79 | GNUNET_NAMESTORE_disconnect (struct GNUNET_NAMESTORE_Handle *h, int drop); | ||
80 | |||
81 | |||
82 | /** | ||
83 | * Continuation called to notify client about result of the | ||
84 | * operation. | ||
85 | * | ||
86 | * @param cls closure | ||
87 | * @param success GNUNET_SYSERR on failure (including timeout/queue drop) | ||
88 | * GNUNET_NO if content was already there | ||
89 | * GNUNET_YES (or other positive value) on success | ||
90 | * @param emsg NULL on success, otherwise an error message | ||
91 | */ | ||
92 | typedef void (*GNUNET_NAMESTORE_ContinuationWithStatus) (void *cls, | ||
93 | int32_t success, | ||
94 | const char *emsg); | ||
95 | |||
96 | |||
97 | /** | ||
98 | * Flags that can be set for a record. | ||
99 | */ | ||
100 | enum GNUNET_NAMESTORE_RecordFlags | ||
101 | { | ||
102 | |||
103 | /** | ||
104 | * No special options. | ||
105 | */ | ||
106 | GNUNET_NAMESTORE_RF_NONE = 0, | ||
107 | |||
108 | /** | ||
109 | * This peer is the authority for this record; it must thus | ||
110 | * not be deleted (other records can be deleted if we run | ||
111 | * out of space). | ||
112 | */ | ||
113 | GNUNET_NAMESTORE_RF_AUTHORITY = 1, | ||
114 | |||
115 | /** | ||
116 | * This is a private record of this peer and it should | ||
117 | * thus not be handed out to other peers. | ||
118 | */ | ||
119 | GNUNET_NAMESTORE_RF_PRIVATE = 2 | ||
120 | |||
121 | }; | ||
122 | |||
123 | |||
124 | /** | ||
125 | * We formally store records in a B-tree for signing. This struct | ||
126 | * identifies the location of a record in the B-tree. | ||
127 | */ | ||
128 | struct GNUNET_NAMESTORE_SignatureLocation | ||
129 | { | ||
130 | /** | ||
131 | * Offset in the B-tree. | ||
132 | */ | ||
133 | uint64_t offset; | ||
134 | |||
135 | /** | ||
136 | * Depth in the B-tree. | ||
137 | */ | ||
138 | uint32_t depth; | ||
139 | |||
140 | /** | ||
141 | * Revision of the B-tree. | ||
142 | */ | ||
143 | uint32_t revision; | ||
144 | }; | ||
145 | |||
146 | |||
147 | /** | ||
148 | * Continuation called to notify client about result of the | ||
149 | * signing operation. | ||
150 | * | ||
151 | * @param cls closure | ||
152 | * @param sig where the signature is now located in the S-tree | ||
153 | */ | ||
154 | typedef void (*GNUNET_NAMESTORE_ContinuationWithSignature) (void *cls, | ||
155 | const struct GNUNET_NAMESPACE_SignatureLocation *sig); | ||
156 | |||
157 | |||
158 | |||
159 | |||
160 | |||
161 | /** | ||
162 | * Get the hash of a record (what will be signed in the Stree for | ||
163 | * the record). | ||
164 | * | ||
165 | * @param zone hash of the public key of the zone | ||
166 | * @param name name that is being mapped (at most 255 characters long) | ||
167 | * @param record_type type of the record (A, AAAA, PKEY, etc.) | ||
168 | * @param expiration expiration time for the content | ||
169 | * @param flags flags for the content | ||
170 | * @param data_size number of bytes in data | ||
171 | * @param data value, semantics depend on 'record_type' (see RFCs for DNS and | ||
172 | * GNS specification for GNS extensions) | ||
173 | * @param record_hash hash of the record (set) | ||
174 | */ | ||
175 | void | ||
176 | GNUNET_NAMESTORE_record_hash (struct GNUNET_NAMESTORE_Handle *h, | ||
177 | const GNUNET_HashCode *zone, | ||
178 | const char *name, | ||
179 | uint32_t record_type, | ||
180 | struct GNUNET_TIME_Absolute expiration, | ||
181 | enum GNUNET_NAMESTORE_RecordFlags flags, | ||
182 | size_t data_size, | ||
183 | const void *data, | ||
184 | GNUNET_HashCode *record_hash); | ||
185 | |||
186 | |||
187 | /** | ||
188 | * Sign a record. This function is used by the authority of the zone | ||
189 | * to add a record. | ||
190 | * | ||
191 | * @param h handle to the namestore | ||
192 | * @param zone_privkey private key of the zone | ||
193 | * @param record_hash hash of the record to be signed | ||
194 | * @param cont continuation to call when done | ||
195 | * @param cont_cls closure for cont | ||
196 | * @return handle to abort the request | ||
197 | */ | ||
198 | struct GNUNET_NAMESTORE_QueueEntry * | ||
199 | GNUNET_NAMESTORE_stree_extend (struct GNUNET_NAMESTORE_Handle *h, | ||
200 | const struct GNUNET_CRYPTO_RsaPrivateKey *zone_privkey, | ||
201 | const GNUNET_HashCode *record_hash, | ||
202 | GNUNET_NAMESTORE_ContinuationWithSignature cont, | ||
203 | void *cont_cls); | ||
204 | |||
205 | |||
206 | /** | ||
207 | * Rebalance the signature tree of our zone. This function should | ||
208 | * be called "rarely" to rebalance the tree. | ||
209 | * | ||
210 | * @param h handle to the namestore | ||
211 | * @param zone_privkey private key for the zone to rebalance | ||
212 | * @param cont continuation to call when done | ||
213 | * @param cont_cls closure for cont | ||
214 | * @return handle to abort the request | ||
215 | */ | ||
216 | struct GNUNET_NAMESTORE_QueueEntry * | ||
217 | GNUNET_NAMESTORE_stree_rebalance (struct GNUNET_NAMESTORE_Handle *h, | ||
218 | const struct GNUNET_CRYPTO_RsaPrivateKey *zone_privkey, | ||
219 | GNUNET_NAMESTORE_ContinuationWithStatus cont, | ||
220 | void *cont_cls); | ||
221 | |||
222 | |||
223 | /** | ||
224 | * Provide the root of a signature tree. This function is | ||
225 | * used by non-authorities as the first operation when | ||
226 | * adding a foreign zone. | ||
227 | * | ||
228 | * @param h handle to the namestore | ||
229 | * @param zone_key public key of the zone | ||
230 | * @param signature signature of the top-level entry of the zone | ||
231 | * @param revision revision number of the zone | ||
232 | * @param top_hash top-level hash of the zone | ||
233 | * @param cont continuation to call when done | ||
234 | * @param cont_cls closure for cont | ||
235 | * @return handle to abort the request | ||
236 | */ | ||
237 | struct GNUNET_NAMESTORE_QueueEntry * | ||
238 | GNUNET_NAMESTORE_stree_start (struct GNUNET_NAMESTORE_Handle *h, | ||
239 | const struct GNUNET_CRYPTO_RsaPublicKeyBinaryEncoded *zone_key, | ||
240 | const struct GNUNET_CRYPTO_RsaSignature *signature, | ||
241 | uint32_t revision, | ||
242 | const GNUNET_HashCode *top_hash, | ||
243 | GNUNET_NAMESTORE_ContinuationWithSignature cont, | ||
244 | void *cont_cls); | ||
245 | |||
246 | |||
247 | /** | ||
248 | * Store part of a signature B-tree in the namestore. This function | ||
249 | * is used by non-authorities to cache parts of a zone's signature tree. | ||
250 | * Note that the tree must be build top-down. This function must check | ||
251 | * that the nodes being added are valid, and if not refuse the operation. | ||
252 | * | ||
253 | * @param h handle to the namestore | ||
254 | * @param zone_key public key of the zone | ||
255 | * @param loc location in the B-tree | ||
256 | * @param ploc parent's location in the B-tree (must have depth = loc.depth - 1), NULL for root | ||
257 | * @param top_sig signature at the top, NULL if 'loc.depth > 0' | ||
258 | * @param num_entries number of entries at this node in the B-tree | ||
259 | * @param entries the 'num_entries' entries to store (hashes over the | ||
260 | * records) | ||
261 | * @param cont continuation to call when done | ||
262 | * @param cont_cls closure for cont | ||
263 | * @return handle to abort the request | ||
264 | */ | ||
265 | struct GNUNET_NAMESTORE_QueueEntry * | ||
266 | GNUNET_NAMESTORE_stree_put (struct GNUNET_NAMESTORE_Handle *h, | ||
267 | const struct GNUNET_CRYPTO_PublicKey *zone_key, | ||
268 | const struct GNUNET_NAMESTORE_SignatureLocation *loc, | ||
269 | const struct GNUNET_NAMESTORE_SignatureLocation *ploc, | ||
270 | const struct GNUNET_CRYPTO_RsaSignature *sig, | ||
271 | unsigned int num_entries, | ||
272 | const GNUNET_HashCode *entries, | ||
273 | GNUNET_NAMESTORE_ContinuationWithStatus cont, | ||
274 | void *cont_cls); | ||
275 | |||
276 | |||
277 | /** | ||
278 | * Store an item in the namestore. If the item is already present, | ||
279 | * the expiration time is updated to the max of the existing time and | ||
280 | * the new time. The operation must fail if there is no matching | ||
281 | * entry in the signature tree. | ||
282 | * | ||
283 | * @param h handle to the namestore | ||
284 | * @param zone hash of the public key of the zone | ||
285 | * @param name name that is being mapped (at most 255 characters long) | ||
286 | * @param record_type type of the record (A, AAAA, PKEY, etc.) | ||
287 | * @param expiration expiration time for the content | ||
288 | * @param flags flags for the content | ||
289 | * @param sig_loc where is the information about the signature for this record stored? | ||
290 | * @param data_size number of bytes in data | ||
291 | * @param data value, semantics depend on 'record_type' (see RFCs for DNS and | ||
292 | * GNS specification for GNS extensions) | ||
293 | * @param cont continuation to call when done | ||
294 | * @param cont_cls closure for cont | ||
295 | * @return handle to abort the request | ||
296 | */ | ||
297 | struct GNUNET_NAMESTORE_QueueEntry * | ||
298 | GNUNET_NAMESTORE_record_put (struct GNUNET_NAMESTORE_Handle *h, | ||
299 | const GNUNET_HashCode *zone, | ||
300 | const char *name, | ||
301 | uint32_t record_type, | ||
302 | struct GNUNET_TIME_Absolute expiration, | ||
303 | enum GNUNET_NAMESTORE_RecordFlags flags, | ||
304 | const struct GNUNET_NAMESTORE_SignatureLocation *sig_loc, | ||
305 | size_t data_size, | ||
306 | const void *data, | ||
307 | GNUNET_NAMESTORE_ContinuationWithStatus cont, | ||
308 | void *cont_cls); | ||
309 | |||
310 | |||
311 | /** | ||
312 | * Explicitly remove some content from the database. The | ||
313 | * "cont"inuation will be called with status "GNUNET_OK" if content | ||
314 | * was removed, "GNUNET_NO" if no matching entry was found and | ||
315 | * "GNUNET_SYSERR" on all other types of errors. | ||
316 | * | ||
317 | * @param h handle to the namestore | ||
318 | * @param zone hash of the public key of the zone | ||
319 | * @param name name that is being mapped (at most 255 characters long) | ||
320 | * @param record_type type of the record (A, AAAA, PKEY, etc.) | ||
321 | * @param size number of bytes in data | ||
322 | * @param data content stored | ||
323 | * @param cont continuation to call when done | ||
324 | * @param cont_cls closure for cont | ||
325 | * @return handle to abort the request | ||
326 | */ | ||
327 | struct GNUNET_NAMESTORE_QueueEntry * | ||
328 | GNUNET_NAMESTORE_record_remove (struct GNUNET_NAMESTORE_Handle *h, | ||
329 | const GNUNET_HashCode *zone, | ||
330 | const char *name, | ||
331 | uint32_t record_type, | ||
332 | size_t size, | ||
333 | const void *data, | ||
334 | GNUNET_NAMESTORE_ContinuationWithStatus cont, | ||
335 | void *cont_cls); | ||
336 | |||
337 | |||
338 | /** | ||
339 | * Process a record that was stored in the namestore. | ||
340 | * | ||
341 | * @param cls closure | ||
342 | * @param zone hash of the public key of the zone | ||
343 | * @param name name that is being mapped (at most 255 characters long) | ||
344 | * @param record_type type of the record (A, AAAA, PKEY, etc.) | ||
345 | * @param expiration expiration time for the content | ||
346 | * @param flags flags for the content | ||
347 | * @param sig_loc where is the information about the signature for this record stored? | ||
348 | * @param size number of bytes in data | ||
349 | * @param data content stored | ||
350 | */ | ||
351 | typedef void (*GNUNET_NAMESTORE_RecordProcessor) (void *cls, | ||
352 | const GNUNET_HashCode *zone, | ||
353 | const char *name, | ||
354 | uint32_t record_type, | ||
355 | struct GNUNET_TIME_Absolute expiration, | ||
356 | enum GNUNET_NAMESTORE_RecordFlags flags, | ||
357 | const struct GNUNET_NAMESTORE_SignatureLocation *sig_loc, | ||
358 | size_t size, const void *data); | ||
359 | |||
360 | |||
361 | /** | ||
362 | * Get a result for a particular key from the namestore. The processor | ||
363 | * will only be called once. | ||
364 | * | ||
365 | * @param h handle to the namestore | ||
366 | * @param zone zone to look up a record from | ||
367 | * @param name name to look up | ||
368 | * @param record_type desired record type | ||
369 | * @param proc function to call on each matching value; | ||
370 | * will be called once with a NULL value at the end | ||
371 | * @param proc_cls closure for proc | ||
372 | * @return a handle that can be used to | ||
373 | * cancel | ||
374 | */ | ||
375 | struct GNUNET_NAMESTORE_QueueEntry * | ||
376 | GNUNET_NAMESTORE_lookup_name (struct GNUNET_NAMESTORE_Handle *h, | ||
377 | const GNUNET_HashCode *zone, | ||
378 | const char *name, | ||
379 | uint32_t record_type, | ||
380 | GNUNET_NAMESTORE_RecordProcessor proc, void *proc_cls); | ||
381 | |||
382 | |||
383 | |||
384 | /** | ||
385 | * Get the hash of a subtree in the STree (what will be signed in the parent | ||
386 | * location). | ||
387 | * | ||
388 | * @param zone hash of the public key of the zone | ||
389 | * @param loc where we are in the signature tree | ||
390 | * @param num_entries number of entries being stored here | ||
391 | * @param entries the entries themselves | ||
392 | * @param st_hash hash of the stree node (set) | ||
393 | */ | ||
394 | void | ||
395 | GNUNET_NAMESTORE_record_hash (struct GNUNET_NAMESTORE_Handle *h, | ||
396 | const GNUNET_HashCode *zone, | ||
397 | const struct GNUNET_NAMESTORE_SignatureLocation *loc, | ||
398 | unsigned int num_entries, | ||
399 | const GNUNET_HashCode *entries, | ||
400 | GNUNET_HashCode *st_hash); | ||
401 | |||
402 | |||
403 | /** | ||
404 | * Process a Stree node that was stored in the namestore. | ||
405 | * | ||
406 | * @param cls closure | ||
407 | * @param zone hash of the public key of the zone | ||
408 | * @param loc where we are in the signature tree | ||
409 | * @param ploc location of our parent in the signature tree (NULL if 'loc.depth == 0') | ||
410 | * @param top_sig signature at the root (NULL if 'loc.depth > 0') | ||
411 | * @param num_entries number of entries being stored here | ||
412 | * @param entries the entries themselves | ||
413 | */ | ||
414 | typedef void (*GNUNET_NAMESTORE_StreeProcessor) (void *cls, | ||
415 | const GNUNET_HashCode *zone, | ||
416 | const struct GNUNET_NAMESTORE_SignatureLocation *loc, | ||
417 | const struct GNUNET_NAMESTORE_SignatureLocation *ploc, | ||
418 | const struct GNUNET_CRYPTO_RsaSignature *top_sig, | ||
419 | unsigned int num_entries, | ||
420 | const GNUNET_HashCode *entries); | ||
421 | |||
422 | |||
423 | /** | ||
424 | * Obtain part of a signature B-tree. The processor | ||
425 | * will only be called once. | ||
426 | * | ||
427 | * @param h handle to the namestore | ||
428 | * @param zone zone to look up a record from | ||
429 | * @param sig_loc location to look up | ||
430 | * @param proc function to call on each matching value; | ||
431 | * will be called once with a NULL value at the end | ||
432 | * @param proc_cls closure for proc | ||
433 | * @return a handle that can be used to | ||
434 | * cancel | ||
435 | */ | ||
436 | struct GNUNET_NAMESTORE_QueueEntry * | ||
437 | GNUNET_NAMESTORE_lookup_stree (struct GNUNET_NAMESTORE_Handle *h, | ||
438 | const GNUNET_HashCode *zone, | ||
439 | const struct GNUNET_NAMESTORE_SignatureLocation *sig_loc, | ||
440 | GNUNET_NAMESTORE_StreeProcessor proc, void *proc_cls); | ||
441 | |||
442 | |||
443 | /** | ||
444 | * Get all records of a zone. | ||
445 | * | ||
446 | * @param h handle to the namestore | ||
447 | * @param zone zone to access | ||
448 | * @param proc function to call on a random value; it | ||
449 | * will be called repeatedly with a value (if available) | ||
450 | * and always once at the end with a zone and name of NULL. | ||
451 | * @param proc_cls closure for proc | ||
452 | * @return a handle that can be used to | ||
453 | * cancel | ||
454 | */ | ||
455 | struct GNUNET_NAMESTORE_QueueEntry * | ||
456 | GNUNET_NAMESTORE_zone_transfer (struct GNUNET_NAMESTORE_Handle *h, | ||
457 | const GNUNET_HashCode *zone, | ||
458 | GNUNET_NAMESTORE_RecordProcessor proc, | ||
459 | void *proc_cls); | ||
460 | |||
461 | |||
462 | |||
463 | |||
464 | /** | ||
465 | * Cancel a namestore operation. The final callback from the | ||
466 | * operation must not have been done yet. | ||
467 | * | ||
468 | * @param qe operation to cancel | ||
469 | */ | ||
470 | void | ||
471 | GNUNET_NAMESTORE_cancel (struct GNUNET_NAMESTORE_QueueEntry *qe); | ||
472 | |||
473 | |||
474 | #if 0 /* keep Emacsens' auto-indent happy */ | ||
475 | { | ||
476 | #endif | ||
477 | #ifdef __cplusplus | ||
478 | } | ||
479 | #endif | ||
480 | |||
481 | /* end of gnunet_namestore_service.h */ | ||
482 | #endif | ||