- use tunnel encryption state to select decryption key

[oweals/gnunet.git] / src / include / gnunet_namestore_service.h

diff --git a/src/include/gnunet_namestore_service.h b/src/include/gnunet_namestore_service.h
index 9b0171970904095c98becbda90a30f949b30a657..8466d613507d7f7d5a32e478e792c496b7f05a1a 100644 (file)
--- a/src/include/gnunet_namestore_service.h
+++ b/src/include/gnunet_namestore_service.h
@@ -1,10 +1,10 @@
 /*
      This file is part of GNUnet
 /*
      This file is part of GNUnet

-     (C) 2012 Christian Grothoff (and other contributing authors)
+     (C) 2012, 2013 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
 
      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
+     by the Free Software Foundation; either version 3, or (at your

      option) any later version.
 
      GNUnet is distributed in the hope that it will be useful, but
      option) any later version.
 
      GNUnet is distributed in the hope that it will be useful, but


@@ -21,19 +21,17 @@
 /**
  * @file include/gnunet_namestore_service.h
  * @brief API that can be used to store naming information on a GNUnet node;
 /**
  * @file include/gnunet_namestore_service.h
  * @brief API that can be used to store naming information on a GNUnet node;

+ *        Naming information can either be records for which this peer/user
+ *        is authoritative, or blocks which are cached, encrypted naming
+ *        data from other peers.

  * @author Christian Grothoff
  * @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"
 #ifndef GNUNET_NAMESTORE_SERVICE_H
 #define GNUNET_NAMESTORE_SERVICE_H
 
 #include "gnunet_util_lib.h"
 #include "gnunet_block_lib.h"

+#include "gnunet_gnsrecord_lib.h"

 
 #ifdef __cplusplus
 extern "C"
 
 #ifdef __cplusplus
 extern "C"


@@ -43,6 +41,7 @@ extern "C"
 #endif
 #endif
 
 #endif
 #endif
 

+

 /**
  * Entry in the queue.
  */
 /**
  * Entry in the queue.
  */


@@ -58,10 +57,6 @@ struct GNUNET_NAMESTORE_Handle;
  */
 struct GNUNET_NAMESTORE_ZoneIterator;
 
  */
 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.
 
 /**
  * Connect to the namestore service.


@@ -75,13 +70,13 @@ GNUNET_NAMESTORE_connect (const struct GNUNET_CONFIGURATION_Handle *cfg);
 
 /**
  * Disconnect from the namestore service (and free associated
 
 /**
  * Disconnect from the namestore service (and free associated

- * resources).
+ * resources).  Must not be called from within operation callbacks of
+ * the API.

  *
  * @param h handle to the namestore
  *
  * @param h handle to the namestore

- * @param drop set to GNUNET_YES to delete all data in namestore (!)

  */
 void
  */
 void

-GNUNET_NAMESTORE_disconnect (struct GNUNET_NAMESTORE_Handle *h, int drop);
+GNUNET_NAMESTORE_disconnect (struct GNUNET_NAMESTORE_Handle *h);

 
 
 /**
 
 
 /**


@@ -89,9 +84,9 @@ GNUNET_NAMESTORE_disconnect (struct GNUNET_NAMESTORE_Handle *h, int drop);
  * operation.
  *
  * @param cls closure
  * 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 success #GNUNET_SYSERR on failure (including timeout/queue drop/failure to validate)
+ *                #GNUNET_NO if content was already there or not found
+ *                #GNUNET_YES (or other positive value) on success

  * @param emsg NULL on success, otherwise an error message
  */
 typedef void (*GNUNET_NAMESTORE_ContinuationWithStatus) (void *cls,
  * @param emsg NULL on success, otherwise an error message
  */
 typedef void (*GNUNET_NAMESTORE_ContinuationWithStatus) (void *cls,


@@ -99,237 +94,138 @@ typedef void (*GNUNET_NAMESTORE_ContinuationWithStatus) (void *cls,
                                                          const char *emsg);
 
 
                                                          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,
 /**
  * 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.
+ * it is replaced with the new record.  Use an empty array to
+ * remove all records under the given name.

  *
  * @param h handle to the namestore
  *
  * @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 pkey private key of the zone
+ * @param label name that is being mapped
+ * @param rd_count number of records in the 'rd' array

  * @param rd array of records with data to store
  * @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 continuation to call when done

- * @param cont_cls closure for cont
+ * @param cont_cls closure for @a cont

  * @return handle to abort the request
  */
 struct GNUNET_NAMESTORE_QueueEntry *
  * @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);
+GNUNET_NAMESTORE_records_store (struct GNUNET_NAMESTORE_Handle *h,
+                               const struct GNUNET_CRYPTO_EcdsaPrivateKey *pkey,
+                               const char *label,
+                               unsigned int rd_count,
+                               const struct GNUNET_GNSRECORD_Data *rd,
+                               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.
+ * Process a record that was stored in the namestore.

  *
  *

- * @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 cls closure
+ * @param zone private key of the zone; NULL on disconnect
+ * @param label label of the records; NULL on disconnect
+ * @param rd_count number of entries in @a rd array, 0 if label was deleted

  * @param rd array of records with data to store
  * @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);
-
+typedef void (*GNUNET_NAMESTORE_RecordMonitor) (void *cls,
+                                               const struct GNUNET_CRYPTO_EcdsaPrivateKey *zone,
+                                               const char *label,
+                                               unsigned int rd_count,
+                                               const struct GNUNET_GNSRECORD_Data *rd);

 
 /**
 
 /**

- * 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.
+ * Set the desired nick name for a zone

  *
  * @param h handle to the namestore
  * @param pkey private key of the 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 nick the nick name to set

  * @param cont continuation to call when done
  * @param cont continuation to call when done

- * @param cont_cls closure for cont
+ * @param cont_cls closure for 'cont'

  * @return handle to abort the request
  */
 struct GNUNET_NAMESTORE_QueueEntry *
  * @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);
-
+GNUNET_NAMESTORE_set_nick (struct GNUNET_NAMESTORE_Handle *h,
+                           const struct GNUNET_CRYPTO_EcdsaPrivateKey *pkey,
+                           const char *nick,
+                           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.
+ * Lookup an item in the namestore.

  *
  * @param h handle to the namestore
  * @param pkey private key of the 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
+ * @param label name that is being mapped
+ * @param rm function to call with the result (with 0 records if we don't have that label)
+ * @param rm_cls closure for @a rm

  * @return handle to abort the request
  */
 struct GNUNET_NAMESTORE_QueueEntry *
  * @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);
+GNUNET_NAMESTORE_records_lookup (struct GNUNET_NAMESTORE_Handle *h,
+                                 const struct GNUNET_CRYPTO_EcdsaPrivateKey *pkey,
+                                 const char *label,
+                                 GNUNET_NAMESTORE_RecordMonitor rm,
+                                 void *rm_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_len,
-                                                 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.  
+ * Look for an existing PKEY delegation record for a given public key.
+ * Returns at most one result to the processor.

  *
  * @param h handle to the namestore
  *
  * @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 zone public key of the zone to look up in, never NULL
+ * @param value_zone public key of the target zone (value), never NULL

  * @param proc function to call on the matching records, or with
  *        NULL (rd_count == 0) if there are no matching records
  * @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
+ * @param proc_cls closure for @a proc

  * @return a handle that can be used to
  *         cancel
  */
 struct GNUNET_NAMESTORE_QueueEntry *
  * @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);
+GNUNET_NAMESTORE_zone_to_name (struct GNUNET_NAMESTORE_Handle *h,
+                              const struct GNUNET_CRYPTO_EcdsaPrivateKey *zone,
+                              const struct GNUNET_CRYPTO_EcdsaPublicKey *value_zone,
+                              GNUNET_NAMESTORE_RecordMonitor proc, void *proc_cls);
+
+
+/**
+ * Cancel a namestore operation.  The final callback from the
+ * operation must not have been done yet.  Must be called on any
+ * namestore operation that has not yet completed prior to calling
+ * #GNUNET_NAMESTORE_disconnect.
+ *
+ * @param qe operation to cancel
+ */
+void
+GNUNET_NAMESTORE_cancel (struct GNUNET_NAMESTORE_QueueEntry *qe);

 
 
 /**
  * Starts a new zone iteration (used to periodically PUT all of our
 
 
 /**
  * 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
+ * records into our DHT). This MUST lock the struct GNUNET_NAMESTORE_Handle
+ * for any other calls than #GNUNET_NAMESTORE_zone_iterator_next and
+ * #GNUNET_NAMESTORE_zone_iteration_stop. @a proc will be called once

  * immediately, and then again after
  * immediately, and then again after

- * "GNUNET_NAMESTORE_zone_iterator_next" is invoked.
+ * #GNUNET_NAMESTORE_zone_iterator_next is invoked.

  *
  * @param h handle to the namestore
  * @param zone zone to access, NULL for all zones
  *
  * @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)
  * @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
+ *        and always once at the end with a label of NULL.
+ * @param proc_cls closure for @a proc

  * @return an iterator handle to use for iteration
  */
 struct GNUNET_NAMESTORE_ZoneIterator *
 GNUNET_NAMESTORE_zone_iteration_start (struct GNUNET_NAMESTORE_Handle *h,
  * @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,
+                                      const struct GNUNET_CRYPTO_EcdsaPrivateKey *zone,
+                                      GNUNET_NAMESTORE_RecordMonitor proc,

                                       void *proc_cls);
 
 
 /**
                                       void *proc_cls);
 
 
 /**

- * Calls the record processor specified in GNUNET_NAMESTORE_zone_iteration_start
+ * Calls the record processor specified in #GNUNET_NAMESTORE_zone_iteration_start

  * for the next record.
  *
  * @param it the iterator
  * for the next record.
  *
  * @param it the iterator


@@ -339,7 +235,9 @@ GNUNET_NAMESTORE_zone_iterator_next (struct GNUNET_NAMESTORE_ZoneIterator *it);
 
 
 /**
 
 
 /**

- * Stops iteration and releases the namestore handle for further calls.
+ * Stops iteration and releases the namestore handle for further calls.  Must
+ * be called on any iteration that has not yet completed prior to calling
+ * #GNUNET_NAMESTORE_disconnect.

  *
  * @param it the iterator
  */
  *
  * @param it the iterator
  */


@@ -348,64 +246,59 @@ 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
+ * Handle for a monitoring activity.

  */
  */

-void
-GNUNET_NAMESTORE_cancel (struct GNUNET_NAMESTORE_QueueEntry *qe);
-
-
+struct GNUNET_NAMESTORE_ZoneMonitor;

 
 

-/* convenience APIs for serializing / deserializing GNS records */

 
 /**
 
 /**

- * Calculate how many bytes we will need to serialize the given
- * records.
- *
- * @param rd_count number of records in the rd array
- * @param rd array of GNUNET_NAMESTORE_RecordData with rd_count elements
- *
- * @return the required size to serialize
+ * Function called once the monitor has caught up with the current
+ * state of the database.  Will be called AGAIN after each disconnect
+ * (record monitor called with 'NULL' for zone_key) once we're again
+ * in sync.

  *
  *

+ * @param cls closure

  */
  */

-size_t
-GNUNET_NAMESTORE_records_get_size (unsigned int rd_count,
-                                  const struct GNUNET_NAMESTORE_RecordData *rd);
+typedef void (*GNUNET_NAMESTORE_RecordsSynchronizedCallback)(void *cls);
+

 
 /**
 
 /**

- * Serialize the given records to the given destination buffer.
+ * Begin monitoring a zone for changes.  Will first call the @a
+ * monitor function on all existing records in the selected zone(s) if
+ * @a iterate_first is #GNUNET_YES.  In any case, we will then call @a
+ * sync_cb, and then afterwards call the @a monitor whenever a record
+ * changes.  If the namestore disconnects, the @a monitor function is
+ * called with a disconnect event; if the connection is
+ * re-established, the process begins from the start (depending on @a
+ * iterate_first, we first do all existing records, then @a sync, then
+ * updates).

  *
  *

- * @param rd_cound number of records in the rd array
- * @param rd array of GNUNET_NAMESTORE_RecordData with rd_count elements
- * @param dest_size size of the destination array
- * @param dest where to write the result
- *
- * @return the size of serialized records
+ * @param cfg configuration to use to connect to namestore
+ * @param zone zone to monitor, NULL for all zones
+ * @param iterate_first #GNUNET_YES to first iterate over all existing records,
+ *                      #GNUNET_NO to only return changes that happen from now on
+ * @param monitor function to call on zone changes
+ * @param sync_cb function called when we're in sync with the namestore
+ * @param cls closure for @a monitor and @a sync_cb
+ * @return handle to stop monitoring

  */
  */

-ssize_t
-GNUNET_NAMESTORE_records_serialize (unsigned int rd_count,
-                                   const struct GNUNET_NAMESTORE_RecordData *rd,
-                                   size_t dest_size,
-                                   char *dest);
+struct GNUNET_NAMESTORE_ZoneMonitor *
+GNUNET_NAMESTORE_zone_monitor_start (const struct GNUNET_CONFIGURATION_Handle *cfg,
+                                    const struct GNUNET_CRYPTO_EcdsaPrivateKey *zone,
+                                     int iterate_first,
+                                    GNUNET_NAMESTORE_RecordMonitor monitor,
+                                    GNUNET_NAMESTORE_RecordsSynchronizedCallback sync_cb,
+                                    void *cls);

 
 
 /**
 
 
 /**

- * Deserialize the given records to the given destination.
- *
- * @param len size of the serialized record data
- * @param src the serialized record data
- * @param rd_cound number of records in the rd array
- * @param dest where to put the data
+ * Stop monitoring a zone for changes.

  *
  *

- * @return GNUNET_OK on success, GNUNET_SYSERR on error
+ * @param zm handle to the monitor activity to stop

  */
  */

-int
-GNUNET_NAMESTORE_records_deserialize (size_t len,
-                                     const char *src,
-                                     unsigned int rd_count,
-                                     struct GNUNET_NAMESTORE_RecordData *dest);
+void
+GNUNET_NAMESTORE_zone_monitor_stop (struct GNUNET_NAMESTORE_ZoneMonitor *zm);
+

 
 
 #if 0                           /* keep Emacsens' auto-indent happy */
 
 
 #if 0                           /* keep Emacsens' auto-indent happy */