2 This file is part of GNUnet
3 (C) 2012 Christian Grothoff (and other contributing authors)
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.
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.
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.
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
26 * Other functions we might want:
27 * - enumerate all known zones
28 * - convenience function to gather record and the full affilliated stree
32 #ifndef GNUNET_NAMESTORE_SERVICE_H
33 #define GNUNET_NAMESTORE_SERVICE_H
35 #include "gnunet_util_lib.h"
36 #include "gnunet_block_lib.h"
41 #if 0 /* keep Emacsens' auto-indent happy */
47 * Record type indicating any record/'*'
49 #define GNUNET_NAMESTORE_TYPE_ANY 0
52 * Record type for GNS zone transfer ("PKEY").
54 #define GNUNET_NAMESTORE_TYPE_PKEY 65536
57 * Record type for GNS zone transfer ("PSEU").
59 #define GNUNET_NAMESTORE_TYPE_PSEU 65537
62 * Record type for GNS legacy hostnames ("LEHO").
64 #define GNUNET_NAMESTORE_TYPE_LEHO 65538
67 * Record type for VPN resolution
69 #define GNUNET_NAMESTORE_TYPE_VPN 65539
72 * Record type for zone revocation
74 #define GNUNET_NAMESTORE_TYPE_REV 65540
79 struct GNUNET_NAMESTORE_QueueEntry;
82 * Handle to the namestore service.
84 struct GNUNET_NAMESTORE_Handle;
87 * Handle to the namestore zone iterator.
89 struct GNUNET_NAMESTORE_ZoneIterator;
92 * Maximum size of a value that can be stored in the namestore.
94 #define GNUNET_NAMESTORE_MAX_VALUE_SIZE (63 * 1024)
99 * Connect to the namestore service.
101 * @param cfg configuration to use
102 * @return handle to use to access the service
104 struct GNUNET_NAMESTORE_Handle *
105 GNUNET_NAMESTORE_connect (const struct GNUNET_CONFIGURATION_Handle *cfg);
109 * Disconnect from the namestore service (and free associated
112 * @param h handle to the namestore
113 * @param drop set to GNUNET_YES to delete all data in namestore (!)
116 GNUNET_NAMESTORE_disconnect (struct GNUNET_NAMESTORE_Handle *h, int drop);
120 * Continuation called to notify client about result of the
124 * @param success GNUNET_SYSERR on failure (including timeout/queue drop/failure to validate)
125 * GNUNET_NO if content was already there or not found
126 * GNUNET_YES (or other positive value) on success
127 * @param emsg NULL on success, otherwise an error message
129 typedef void (*GNUNET_NAMESTORE_ContinuationWithStatus) (void *cls,
135 * Flags that can be set for a record.
137 enum GNUNET_NAMESTORE_RecordFlags
141 * No special options.
143 GNUNET_NAMESTORE_RF_NONE = 0,
146 * This peer is the authority for this record; it must thus
147 * not be deleted (other records can be deleted if we run
150 GNUNET_NAMESTORE_RF_AUTHORITY = 1,
153 * This is a private record of this peer and it should
154 * thus not be handed out to other peers.
156 GNUNET_NAMESTORE_RF_PRIVATE = 2,
159 * This record was added by the system
160 * and is pending user confimation
162 GNUNET_NAMESTORE_RF_PENDING = 4
170 struct GNUNET_NAMESTORE_RecordData
174 * Binary value stored in the DNS record.
179 * Expiration time for the DNS record.
181 struct GNUNET_TIME_Absolute expiration;
184 * Number of bytes in 'data'.
189 * Type of the GNS/DNS record.
191 uint32_t record_type;
194 * Flags for the record.
196 enum GNUNET_NAMESTORE_RecordFlags flags;
201 * Store an item in the namestore. If the item is already present,
202 * the expiration time is updated to the max of the existing time and
203 * the new time. This API is used when we cache signatures from other
206 * @param h handle to the namestore
207 * @param zone_key public key of the zone
208 * @param name name that is being mapped (at most 255 characters long)
209 * @param freshness when does the corresponding block in the DHT expire (until
210 * when should we never do a DHT lookup for the same name again)?
211 * @param rd_count number of entries in 'rd' array
212 * @param rd array of records with data to store
213 * @param signature signature for all the records in the zone under the given name
214 * @param cont continuation to call when done
215 * @param cont_cls closure for cont
216 * @return handle to abort the request
218 struct GNUNET_NAMESTORE_QueueEntry *
219 GNUNET_NAMESTORE_record_put (struct GNUNET_NAMESTORE_Handle *h,
220 const struct GNUNET_CRYPTO_RsaPublicKeyBinaryEncoded *zone_key,
222 struct GNUNET_TIME_Absolute freshness,
223 unsigned int rd_count,
224 const struct GNUNET_NAMESTORE_RecordData *rd,
225 const struct GNUNET_CRYPTO_RsaSignature *signature,
226 GNUNET_NAMESTORE_ContinuationWithStatus cont,
231 * Check if a signature is valid. This API is used by the GNS Block
232 * to validate signatures received from the network.
234 * @param public_key public key of the zone
235 * @param expire block expiration
236 * @param name name that is being mapped (at most 255 characters long)
237 * @param rd_count number of entries in 'rd' array
238 * @param rd array of records with data to store
239 * @param signature signature for all the records in the zone under the given name
240 * @return GNUNET_OK if the signature is valid
243 GNUNET_NAMESTORE_verify_signature (const struct GNUNET_CRYPTO_RsaPublicKeyBinaryEncoded *public_key,
244 const struct GNUNET_TIME_Absolute freshness,
246 unsigned int rd_count,
247 const struct GNUNET_NAMESTORE_RecordData *rd,
248 const struct GNUNET_CRYPTO_RsaSignature *signature);
252 * Store an item in the namestore. If the item is already present,
253 * the expiration time is updated to the max of the existing time and
254 * the new time. This API is used by the authority of a zone.
256 * @param h handle to the namestore
257 * @param pkey private key of the zone
258 * @param name name that is being mapped (at most 255 characters long)
259 * @param rd record data to store
260 * @param cont continuation to call when done
261 * @param cont_cls closure for cont
262 * @return handle to abort the request
264 struct GNUNET_NAMESTORE_QueueEntry *
265 GNUNET_NAMESTORE_record_create (struct GNUNET_NAMESTORE_Handle *h,
266 const struct GNUNET_CRYPTO_RsaPrivateKey *pkey,
268 const struct GNUNET_NAMESTORE_RecordData *rd,
269 GNUNET_NAMESTORE_ContinuationWithStatus cont,
274 * Explicitly remove some content from the database. The
275 * "cont"inuation will be called with status "GNUNET_OK" if content
276 * was removed, "GNUNET_NO" if no matching entry was found and
277 * "GNUNET_SYSERR" on all other types of errors.
278 * This API is used by the authority of a zone.
280 * @param h handle to the namestore
281 * @param pkey private key of the zone
282 * @param name name that is being mapped (at most 255 characters long)
283 * @param rd record data, remove specific record, NULL to remove the name and all records
284 * @param cont continuation to call when done
285 * @param cont_cls closure for cont
286 * @return handle to abort the request
288 struct GNUNET_NAMESTORE_QueueEntry *
289 GNUNET_NAMESTORE_record_remove (struct GNUNET_NAMESTORE_Handle *h,
290 const struct GNUNET_CRYPTO_RsaPrivateKey *pkey,
292 const struct GNUNET_NAMESTORE_RecordData *rd,
293 GNUNET_NAMESTORE_ContinuationWithStatus cont,
298 * Process a record that was stored in the namestore.
301 * @param zone_key public key of the zone
302 * @param expire when does the corresponding block in the DHT expire (until
303 * when should we never do a DHT lookup for the same name again)?;
304 * GNUNET_TIME_UNIT_ZERO_ABS if there are no records of any type in the namestore,
305 * or the expiration time of the block in the namestore (even if there are zero
306 * records matching the desired record type)
307 * @param name name that is being mapped (at most 255 characters long)
308 * @param rd_count number of entries in 'rd' array
309 * @param rd array of records with data to store
310 * @param signature signature of the record block, NULL if signature is unavailable (i.e.
311 * because the user queried for a particular record type only)
313 typedef void (*GNUNET_NAMESTORE_RecordProcessor) (void *cls,
314 const struct GNUNET_CRYPTO_RsaPublicKeyBinaryEncoded *zone_key,
315 struct GNUNET_TIME_Absolute freshness,
318 const struct GNUNET_NAMESTORE_RecordData *rd,
319 const struct GNUNET_CRYPTO_RsaSignature *signature);
323 * Get a result for a particular key from the namestore. The processor
324 * will only be called once.
326 * @param h handle to the namestore
327 * @param zone zone to look up a record from
328 * @param name name to look up
329 * @param record_type desired record type, 0 for all
330 * @param proc function to call on the matching records, or with
331 * NULL (rd_count == 0) if there are no matching records
332 * @param proc_cls closure for proc
333 * @return a handle that can be used to
336 struct GNUNET_NAMESTORE_QueueEntry *
337 GNUNET_NAMESTORE_lookup_record (struct GNUNET_NAMESTORE_Handle *h,
338 const struct GNUNET_CRYPTO_ShortHashCode *zone,
340 uint32_t record_type,
341 GNUNET_NAMESTORE_RecordProcessor proc, void *proc_cls);
345 * Look for an existing PKEY delegation record for a given public key.
346 * Returns at most one result to the processor.
348 * @param h handle to the namestore
349 * @param zone hash of public key of the zone to look up in, never NULL
350 * @param value_zone hash of the public key of the target zone (value), never NULL
351 * @param proc function to call on the matching records, or with
352 * NULL (rd_count == 0) if there are no matching records
353 * @param proc_cls closure for proc
354 * @return a handle that can be used to
357 struct GNUNET_NAMESTORE_QueueEntry *
358 GNUNET_NAMESTORE_zone_to_name (struct GNUNET_NAMESTORE_Handle *h,
359 const struct GNUNET_CRYPTO_ShortHashCode *zone,
360 const struct GNUNET_CRYPTO_ShortHashCode *value_zone,
361 GNUNET_NAMESTORE_RecordProcessor proc, void *proc_cls);
366 * Starts a new zone iteration (used to periodically PUT all of our
367 * records into our DHT). "proc" will be called once
368 * immediately, and then again after
369 * "GNUNET_NAMESTORE_zone_iterator_next" is invoked.
371 * @param h handle to the namestore
372 * @param zone zone to access, NULL for all zones
373 * @param must_have_flags flags that must be set for the record to be returned
374 * @param must_not_have_flags flags that must NOT be set for the record to be returned
375 * @param proc function to call on each name from the zone; it
376 * will be called repeatedly with a value (if available)
377 * and always once at the end with a name of NULL.
378 * @param proc_cls closure for proc
379 * @return an iterator handle to use for iteration
381 struct GNUNET_NAMESTORE_ZoneIterator *
382 GNUNET_NAMESTORE_zone_iteration_start (struct GNUNET_NAMESTORE_Handle *h,
383 const struct GNUNET_CRYPTO_ShortHashCode *zone,
384 enum GNUNET_NAMESTORE_RecordFlags must_have_flags,
385 enum GNUNET_NAMESTORE_RecordFlags must_not_have_flags,
386 GNUNET_NAMESTORE_RecordProcessor proc,
391 * Calls the record processor specified in GNUNET_NAMESTORE_zone_iteration_start
392 * for the next record.
394 * @param it the iterator
397 GNUNET_NAMESTORE_zone_iterator_next (struct GNUNET_NAMESTORE_ZoneIterator *it);
401 * Stops iteration and releases the namestore handle for further calls.
403 * @param it the iterator
406 GNUNET_NAMESTORE_zone_iteration_stop (struct GNUNET_NAMESTORE_ZoneIterator *it);
410 * Cancel a namestore operation. The final callback from the
411 * operation must not have been done yet.
413 * @param qe operation to cancel
416 GNUNET_NAMESTORE_cancel (struct GNUNET_NAMESTORE_QueueEntry *qe);
420 /* convenience APIs for serializing / deserializing GNS records */
423 * Calculate how many bytes we will need to serialize the given
426 * @param rd_count number of records in the rd array
427 * @param rd array of GNUNET_NAMESTORE_RecordData with rd_count elements
429 * @return the required size to serialize
433 GNUNET_NAMESTORE_records_get_size (unsigned int rd_count,
434 const struct GNUNET_NAMESTORE_RecordData *rd);
437 * Serialize the given records to the given destination buffer.
439 * @param rd_count number of records in the rd array
440 * @param rd array of GNUNET_NAMESTORE_RecordData with rd_count elements
441 * @param dest_size size of the destination array
442 * @param dest where to write the result
444 * @return the size of serialized records
447 GNUNET_NAMESTORE_records_serialize (unsigned int rd_count,
448 const struct GNUNET_NAMESTORE_RecordData *rd,
454 * Deserialize the given records to the given destination.
456 * @param len size of the serialized record data
457 * @param src the serialized record data
458 * @param rd_count number of records in the rd array
459 * @param dest where to put the data
461 * @return GNUNET_OK on success, GNUNET_SYSERR on error
464 GNUNET_NAMESTORE_records_deserialize (size_t len,
466 unsigned int rd_count,
467 struct GNUNET_NAMESTORE_RecordData *dest);
471 * Checks if a name is wellformed
473 * @param name the name to check
474 * @return GNUNET_OK on success, GNUNET_SYSERR on error
477 GNUNET_NAMESTORE_check_name (const char * name);
480 * Convert the 'value' of a record to a string.
482 * @param type type of the record
483 * @param data value in binary encoding
484 * @param data_size number of bytes in data
485 * @return NULL on error, otherwise human-readable representation of the value
488 GNUNET_NAMESTORE_value_to_string (uint32_t type,
494 * Convert human-readable version of a 'value' of a record to the binary
497 * @param type type of the record
498 * @param s human-readable string
499 * @param data set to value in binary encoding (will be allocated)
500 * @param data_size set to number of bytes in data
501 * @return GNUNET_OK on success
504 GNUNET_NAMESTORE_string_to_value (uint32_t type,
511 * Convert a type name (i.e. "AAAA") to the corresponding number.
513 * @param typename name to convert
514 * @return corresponding number, UINT32_MAX on error
517 GNUNET_NAMESTORE_typename_to_number (const char *typename);
521 * Convert a type number (i.e. 1) to the corresponding type string (i.e. "A")
523 * @param type number of a type to convert
524 * @return corresponding typestring, NULL on error
527 GNUNET_NAMESTORE_number_to_typename (uint32_t type);
530 #if 0 /* keep Emacsens' auto-indent happy */
537 /* end of gnunet_namestore_service.h */