diff options
Diffstat (limited to 'src/include/gnunet_namestore_service.h')
| -rw-r--r-- | src/include/gnunet_namestore_service.h | 368 |
1 files changed, 368 insertions, 0 deletions
diff --git a/src/include/gnunet_namestore_service.h b/src/include/gnunet_namestore_service.h new file mode 100644 index 0000000..8ab2ce8 --- /dev/null +++ b/src/include/gnunet_namestore_service.h @@ -0,0 +1,368 @@ +/* + This file is part of GNUnet + (C) 2012 Christian Grothoff (and other contributing authors) + + GNUnet is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published + by the Free Software Foundation; either version 2, or (at your + option) any later version. + + GNUnet is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + General Public License for more details. + + You should have received a copy of the GNU General Public License + along with GNUnet; see the file COPYING. If not, write to the + Free Software Foundation, Inc., 59 Temple Place - Suite 330, + Boston, MA 02111-1307, USA. +*/ + +/** + * @file include/gnunet_namestore_service.h + * @brief API that can be used to store naming information on a GNUnet node; + * @author Christian Grothoff + * + * Other functions we might want: + * - enumerate all known zones + * - convenience function to gather record and the full affilliated stree + * in one shot + */ + +#ifndef GNUNET_NAMESTORE_SERVICE_H +#define GNUNET_NAMESTORE_SERVICE_H + +#include "gnunet_util_lib.h" +#include "gnunet_block_lib.h" + +#ifdef __cplusplus +extern "C" +{ +#if 0 /* keep Emacsens' auto-indent happy */ +} +#endif +#endif + +/** + * Entry in the queue. + */ +struct GNUNET_NAMESTORE_QueueEntry; + +/** + * Handle to the namestore service. + */ +struct GNUNET_NAMESTORE_Handle; + +/** + * Handle to the namestore zone iterator. + */ +struct GNUNET_NAMESTORE_ZoneIterator; + +/** + * Maximum size of a value that can be stored in the namestore. + */ +#define GNUNET_NAMESTORE_MAX_VALUE_SIZE (63 * 1024) + +/** + * Connect to the namestore service. + * + * @param cfg configuration to use + * @return handle to use to access the service + */ +struct GNUNET_NAMESTORE_Handle * +GNUNET_NAMESTORE_connect (const struct GNUNET_CONFIGURATION_Handle *cfg); + + +/** + * Disconnect from the namestore service (and free associated + * resources). + * + * @param h handle to the namestore + * @param drop set to GNUNET_YES to delete all data in namestore (!) + */ +void +GNUNET_NAMESTORE_disconnect (struct GNUNET_NAMESTORE_Handle *h, int drop); + + +/** + * Continuation called to notify client about result of the + * operation. + * + * @param cls closure + * @param success GNUNET_SYSERR on failure (including timeout/queue drop/failure to validate) + * GNUNET_NO if content was already there + * GNUNET_YES (or other positive value) on success + * @param emsg NULL on success, otherwise an error message + */ +typedef void (*GNUNET_NAMESTORE_ContinuationWithStatus) (void *cls, + int32_t success, + const char *emsg); + + +/** + * Flags that can be set for a record. + */ +enum GNUNET_NAMESTORE_RecordFlags +{ + + /** + * No special options. + */ + GNUNET_NAMESTORE_RF_NONE = 0, + + /** + * This peer is the authority for this record; it must thus + * not be deleted (other records can be deleted if we run + * out of space). + */ + GNUNET_NAMESTORE_RF_AUTHORITY = 1, + + /** + * This is a private record of this peer and it should + * thus not be handed out to other peers. + */ + GNUNET_NAMESTORE_RF_PRIVATE = 2 + +}; + + +/** + * A GNS record. + */ +struct GNUNET_NAMESTORE_RecordData +{ + + /** + * Binary value stored in the DNS record. + */ + const void *data; + + /** + * Expiration time for the DNS record. + */ + struct GNUNET_TIME_Absolute expiration; + + /** + * Number of bytes in 'data'. + */ + size_t data_size; + + /** + * Type of the GNS/DNS record. + */ + uint32_t record_type; + + /** + * Flags for the record. + */ + enum GNUNET_NAMESTORE_RecordFlags flags; +}; + + +/** + * Store an item in the namestore. If the item is already present, + * the expiration time is updated to the max of the existing time and + * the new time. This API is used when we cache signatures from other + * authorities. + * + * @param h handle to the namestore + * @param zone_key public key of the zone + * @param name name that is being mapped (at most 255 characters long) + * @param expire when does the corresponding block in the DHT expire (until + * when should we never do a DHT lookup for the same name again)? + * @param rd_count number of entries in 'rd' array + * @param rd array of records with data to store + * @param signature signature for all the records in the zone under the given name + * @param cont continuation to call when done + * @param cont_cls closure for cont + * @return handle to abort the request + */ +struct GNUNET_NAMESTORE_QueueEntry * +GNUNET_NAMESTORE_record_put (struct GNUNET_NAMESTORE_Handle *h, + const struct GNUNET_CRYPTO_RsaPublicKeyBinaryEncoded *zone_key, + const char *name, + struct GNUNET_TIME_Absolute expire, + unsigned int rd_count, + const struct GNUNET_NAMESTORE_RecordData *rd, + const struct GNUNET_CRYPTO_RsaSignature *signature, + GNUNET_NAMESTORE_ContinuationWithStatus cont, + void *cont_cls); + + +/** + * Check if a signature is valid. This API is used by the GNS Block + * to validate signatures received from the network. + * + * @param public_key public key of the zone + * @param name name that is being mapped (at most 255 characters long) + * @param rd_count number of entries in 'rd' array + * @param rd array of records with data to store + * @param signature signature for all the records in the zone under the given name + * @return GNUNET_OK if the signature is valid + */ +int +GNUNET_NAMESTORE_verify_signature (const struct GNUNET_CRYPTO_RsaPublicKeyBinaryEncoded *public_key, + const char *name, + unsigned int rd_count, + const struct GNUNET_NAMESTORE_RecordData *rd, + const struct GNUNET_CRYPTO_RsaSignature *signature); + + +/** + * Store an item in the namestore. If the item is already present, + * the expiration time is updated to the max of the existing time and + * the new time. This API is used by the authority of a zone. + * + * @param h handle to the namestore + * @param pkey private key of the zone + * @param name name that is being mapped (at most 255 characters long) + * @param rd record data to store + * @param cont continuation to call when done + * @param cont_cls closure for cont + * @return handle to abort the request + */ +struct GNUNET_NAMESTORE_QueueEntry * +GNUNET_NAMESTORE_record_create (struct GNUNET_NAMESTORE_Handle *h, + const struct GNUNET_CRYPTO_RsaPrivateKey *pkey, + const char *name, + const struct GNUNET_NAMESTORE_RecordData *rd, + GNUNET_NAMESTORE_ContinuationWithStatus cont, + void *cont_cls); + + +/** + * Explicitly remove some content from the database. The + * "cont"inuation will be called with status "GNUNET_OK" if content + * was removed, "GNUNET_NO" if no matching entry was found and + * "GNUNET_SYSERR" on all other types of errors. + * This API is used by the authority of a zone. + * + * @param h handle to the namestore + * @param pkey private key of the zone + * @param name name that is being mapped (at most 255 characters long) + * @param rd record data + * @param cont continuation to call when done + * @param cont_cls closure for cont + * @return handle to abort the request + */ +struct GNUNET_NAMESTORE_QueueEntry * +GNUNET_NAMESTORE_record_remove (struct GNUNET_NAMESTORE_Handle *h, + const struct GNUNET_CRYPTO_RsaPrivateKey *pkey, + const char *name, + const struct GNUNET_NAMESTORE_RecordData *rd, + GNUNET_NAMESTORE_ContinuationWithStatus cont, + void *cont_cls); + + +/** + * Process a record that was stored in the namestore. + * + * @param cls closure + * @param zone_key public key of the zone + * @param expire when does the corresponding block in the DHT expire (until + * when should we never do a DHT lookup for the same name again)?; + * GNUNET_TIME_UNIT_ZERO_ABS if there are no records of any type in the namestore, + * or the expiration time of the block in the namestore (even if there are zero + * records matching the desired record type) + * @param name name that is being mapped (at most 255 characters long) + * @param rd_count number of entries in 'rd' array + * @param rd array of records with data to store + * @param signature signature of the record block, NULL if signature is unavailable (i.e. + * because the user queried for a particular record type only) + */ +typedef void (*GNUNET_NAMESTORE_RecordProcessor) (void *cls, + const struct GNUNET_CRYPTO_RsaPublicKeyBinaryEncoded *zone_key, + struct GNUNET_TIME_Absolute expire, + const char *name, + unsigned int rd_count, + const struct GNUNET_NAMESTORE_RecordData *rd, + const struct GNUNET_CRYPTO_RsaSignature *signature); + + +/** + * Get a result for a particular key from the namestore. The processor + * will only be called once. + * + * @param h handle to the namestore + * @param zone zone to look up a record from + * @param name name to look up + * @param record_type desired record type, 0 for all + * @param proc function to call on the matching records, or with + * NULL (rd_count == 0) if there are no matching records + * @param proc_cls closure for proc + * @return a handle that can be used to + * cancel + */ +struct GNUNET_NAMESTORE_QueueEntry * +GNUNET_NAMESTORE_lookup_record (struct GNUNET_NAMESTORE_Handle *h, + const GNUNET_HashCode *zone, + const char *name, + uint32_t record_type, + GNUNET_NAMESTORE_RecordProcessor proc, void *proc_cls); + + +/** + * Starts a new zone iteration (used to periodically PUT all of our + * records into our DHT). This MUST lock the GNUNET_NAMESTORE_Handle + * for any other calls than GNUNET_NAMESTORE_zone_iterator_next and + * GNUNET_NAMESTORE_zone_iteration_stop. "proc" will be called once + * immediately, and then again after + * "GNUNET_NAMESTORE_zone_iterator_next" is invoked. + * + * @param h handle to the namestore + * @param zone zone to access, NULL for all zones + * @param must_have_flags flags that must be set for the record to be returned + * @param must_not_have_flags flags that must NOT be set for the record to be returned + * @param proc function to call on each name from the zone; it + * will be called repeatedly with a value (if available) + * and always once at the end with a name of NULL. + * @param proc_cls closure for proc + * @return an iterator handle to use for iteration + */ +struct GNUNET_NAMESTORE_ZoneIterator * +GNUNET_NAMESTORE_zone_iteration_start (struct GNUNET_NAMESTORE_Handle *h, + const GNUNET_HashCode *zone, + enum GNUNET_NAMESTORE_RecordFlags must_have_flags, + enum GNUNET_NAMESTORE_RecordFlags must_not_have_flags, + GNUNET_NAMESTORE_RecordProcessor proc, + void *proc_cls); + + +/** + * Calls the record processor specified in GNUNET_NAMESTORE_zone_iteration_start + * for the next record. + * + * @param it the iterator + */ +void +GNUNET_NAMESTORE_zone_iterator_next (struct GNUNET_NAMESTORE_ZoneIterator *it); + + +/** + * Stops iteration and releases the namestore handle for further calls. + * + * @param it the iterator + */ +void +GNUNET_NAMESTORE_zone_iteration_stop (struct GNUNET_NAMESTORE_ZoneIterator *it); + + +/** + * Cancel a namestore operation. The final callback from the + * operation must not have been done yet. + * + * @param qe operation to cancel + */ +void +GNUNET_NAMESTORE_cancel (struct GNUNET_NAMESTORE_QueueEntry *qe); + + +#if 0 /* keep Emacsens' auto-indent happy */ +{ +#endif +#ifdef __cplusplus +} +#endif + +/* end of gnunet_namestore_service.h */ +#endif |