src/include/gnunet_namestore_service.h

   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  * Record type indicating any record/'*'
  48  */
  49 #define GNUNET_NAMESTORE_TYPE_ANY 0
  50
  51 /**
  52  * Record type for GNS zone transfer ("PKEY").
  53  */
  54 #define GNUNET_NAMESTORE_TYPE_PKEY 65536
  55
  56 /**
  57  * Record type for GNS zone transfer ("PSEU").
  58  */
  59 #define GNUNET_NAMESTORE_TYPE_PSEU 65537
  60
  61 /**
  62  * Record type for GNS legacy hostnames ("LEHO").
  63  */
  64 #define GNUNET_NAMESTORE_TYPE_LEHO 65538
  65
  66 /**
  67  * Record type for VPN resolution
  68  */
  69 #define GNUNET_NAMESTORE_TYPE_VPN 65539
  70
  71 /**
  72  * Entry in the queue.
  73  */
  74 struct GNUNET_NAMESTORE_QueueEntry;
  75
  76 /**
  77  * Handle to the namestore service.
  78  */
  79 struct GNUNET_NAMESTORE_Handle;
  80
  81 /**
  82  * Handle to the namestore zone iterator.
  83  */
  84 struct GNUNET_NAMESTORE_ZoneIterator;
  85
  86 /**
  87  * Maximum size of a value that can be stored in the namestore.
  88  */
  89 #define GNUNET_NAMESTORE_MAX_VALUE_SIZE (63 * 1024)
  90
  91
  92
  93 /**
  94  * Connect to the namestore service.
  95  *
  96  * @param cfg configuration to use
  97  * @return handle to use to access the service
  98  */
  99 struct GNUNET_NAMESTORE_Handle *
 100 GNUNET_NAMESTORE_connect (const struct GNUNET_CONFIGURATION_Handle *cfg);
 101
 102
 103 /**
 104  * Disconnect from the namestore service (and free associated
 105  * resources).
 106  *
 107  * @param h handle to the namestore
 108  * @param drop set to GNUNET_YES to delete all data in namestore (!)
 109  */
 110 void
 111 GNUNET_NAMESTORE_disconnect (struct GNUNET_NAMESTORE_Handle *h, int drop);
 112
 113
 114 /**
 115  * Continuation called to notify client about result of the
 116  * operation.
 117  *
 118  * @param cls closure
 119  * @param success GNUNET_SYSERR on failure (including timeout/queue drop/failure to validate)
 120  *                GNUNET_NO if content was already there or not found
 121  *                GNUNET_YES (or other positive value) on success
 122  * @param emsg NULL on success, otherwise an error message
 123  */
 124 typedef void (*GNUNET_NAMESTORE_ContinuationWithStatus) (void *cls,
 125                                                          int32_t success,
 126                                                          const char *emsg);
 127
 128
 129 /**
 130  * Flags that can be set for a record.
 131  */
 132 enum GNUNET_NAMESTORE_RecordFlags
 133 {
 134
 135   /**
 136    * No special options.
 137    */
 138   GNUNET_NAMESTORE_RF_NONE = 0,
 139
 140   /**
 141    * This peer is the authority for this record; it must thus
 142    * not be deleted (other records can be deleted if we run
 143    * out of space).
 144    */
 145   GNUNET_NAMESTORE_RF_AUTHORITY = 1,
 146
 147   /**
 148    * This is a private record of this peer and it should
 149    * thus not be handed out to other peers.
 150    */
 151   GNUNET_NAMESTORE_RF_PRIVATE = 2,
 152
 153   /**
 154    * This record was added by the system
 155    * and is pending user confimation
 156    */
 157   GNUNET_NAMESTORE_RF_PENDING = 4
 158
 159 };
 160
 161
 162 /**
 163  * A GNS record.
 164  */
 165 struct GNUNET_NAMESTORE_RecordData
 166 {
 167
 168   /**
 169    * Binary value stored in the DNS record.
 170    */
 171   const void *data;
 172
 173   /**
 174    * Expiration time for the DNS record.
 175    */
 176   struct GNUNET_TIME_Absolute expiration;
 177
 178   /**
 179    * Number of bytes in 'data'.
 180    */
 181   size_t data_size;
 182
 183   /**
 184    * Type of the GNS/DNS record.
 185    */
 186   uint32_t record_type;
 187
 188   /**
 189    * Flags for the record.
 190    */
 191   enum GNUNET_NAMESTORE_RecordFlags flags;
 192 };
 193
 194
 195 /**
 196  * Store an item in the namestore.  If the item is already present,
 197  * the expiration time is updated to the max of the existing time and
 198  * the new time.  This API is used when we cache signatures from other
 199  * authorities.
 200  *
 201  * @param h handle to the namestore
 202  * @param zone_key public key of the zone
 203  * @param name name that is being mapped (at most 255 characters long)
 204  * @param freshness when does the corresponding block in the DHT expire (until
 205  *               when should we never do a DHT lookup for the same name again)?
 206  * @param rd_count number of entries in 'rd' array
 207  * @param rd array of records with data to store
 208  * @param signature signature for all the records in the zone under the given name
 209  * @param cont continuation to call when done
 210  * @param cont_cls closure for cont
 211  * @return handle to abort the request
 212  */
 213 struct GNUNET_NAMESTORE_QueueEntry *
 214 GNUNET_NAMESTORE_record_put (struct GNUNET_NAMESTORE_Handle *h,
 215                              const struct GNUNET_CRYPTO_RsaPublicKeyBinaryEncoded *zone_key,
 216                              const char *name,
 217                              struct GNUNET_TIME_Absolute freshness,
 218                              unsigned int rd_count,
 219                              const struct GNUNET_NAMESTORE_RecordData *rd,
 220                              const struct GNUNET_CRYPTO_RsaSignature *signature,
 221                              GNUNET_NAMESTORE_ContinuationWithStatus cont,
 222                              void *cont_cls);
 223
 224
 225 /**
 226  * Check if a signature is valid.  This API is used by the GNS Block
 227  * to validate signatures received from the network.
 228  *
 229  * @param public_key public key of the zone
 230  * @param expire block expiration
 231  * @param name name that is being mapped (at most 255 characters long)
 232  * @param rd_count number of entries in 'rd' array
 233  * @param rd array of records with data to store
 234  * @param signature signature for all the records in the zone under the given name
 235  * @return GNUNET_OK if the signature is valid
 236  */
 237 int
 238 GNUNET_NAMESTORE_verify_signature (const struct GNUNET_CRYPTO_RsaPublicKeyBinaryEncoded *public_key,
 239                                    const struct GNUNET_TIME_Absolute freshness,
 240                                    const char *name,
 241                                    unsigned int rd_count,
 242                                    const struct GNUNET_NAMESTORE_RecordData *rd,
 243                                    const struct GNUNET_CRYPTO_RsaSignature *signature);
 244
 245
 246 /**
 247  * Store an item in the namestore.  If the item is already present,
 248  * the expiration time is updated to the max of the existing time and
 249  * the new time.  This API is used by the authority of a zone.
 250  *
 251  * @param h handle to the namestore
 252  * @param pkey private key of the zone
 253  * @param name name that is being mapped (at most 255 characters long)
 254  * @param rd record data to store
 255  * @param cont continuation to call when done
 256  * @param cont_cls closure for cont
 257  * @return handle to abort the request
 258  */
 259 struct GNUNET_NAMESTORE_QueueEntry *
 260 GNUNET_NAMESTORE_record_create (struct GNUNET_NAMESTORE_Handle *h,
 261                                 const struct GNUNET_CRYPTO_RsaPrivateKey *pkey,
 262                                 const char *name,
 263                                 const struct GNUNET_NAMESTORE_RecordData *rd,
 264                                 GNUNET_NAMESTORE_ContinuationWithStatus cont,
 265                                 void *cont_cls);
 266
 267
 268 /**
 269  * Explicitly remove some content from the database.  The
 270  * "cont"inuation will be called with status "GNUNET_OK" if content
 271  * was removed, "GNUNET_NO" if no matching entry was found and
 272  * "GNUNET_SYSERR" on all other types of errors.
 273  * This API is used by the authority of a zone.
 274  *
 275  * @param h handle to the namestore
 276  * @param pkey private key of the zone
 277  * @param name name that is being mapped (at most 255 characters long)
 278  * @param rd record data, remove specific record,  NULL to remove the name and all records
 279  * @param cont continuation to call when done
 280  * @param cont_cls closure for cont
 281  * @return handle to abort the request
 282  */
 283 struct GNUNET_NAMESTORE_QueueEntry *
 284 GNUNET_NAMESTORE_record_remove (struct GNUNET_NAMESTORE_Handle *h,
 285                                 const struct GNUNET_CRYPTO_RsaPrivateKey *pkey,
 286                                 const char *name,
 287                                 const struct GNUNET_NAMESTORE_RecordData *rd,
 288                                 GNUNET_NAMESTORE_ContinuationWithStatus cont,
 289                                 void *cont_cls);
 290
 291
 292 /**
 293  * Process a record that was stored in the namestore.
 294  *
 295  * @param cls closure
 296  * @param zone_key public key of the zone
 297  * @param expire when does the corresponding block in the DHT expire (until
 298  *               when should we never do a DHT lookup for the same name again)?;
 299  *               GNUNET_TIME_UNIT_ZERO_ABS if there are no records of any type in the namestore,
 300  *               or the expiration time of the block in the namestore (even if there are zero
 301  *               records matching the desired record type)
 302  * @param name name that is being mapped (at most 255 characters long)
 303  * @param rd_count number of entries in 'rd' array
 304  * @param rd array of records with data to store
 305  * @param signature signature of the record block, NULL if signature is unavailable (i.e.
 306  *        because the user queried for a particular record type only)
 307  */
 308 typedef void (*GNUNET_NAMESTORE_RecordProcessor) (void *cls,
 309                                                   const struct GNUNET_CRYPTO_RsaPublicKeyBinaryEncoded *zone_key,
 310                                                   struct GNUNET_TIME_Absolute freshness,
 311                                                   const char *name,
 312                                                   unsigned int rd_len,
 313                                                   const struct GNUNET_NAMESTORE_RecordData *rd,
 314                                                   const struct GNUNET_CRYPTO_RsaSignature *signature);
 315
 316
 317 /**
 318  * Get a result for a particular key from the namestore.  The processor
 319  * will only be called once.
 320  *
 321  * @param h handle to the namestore
 322  * @param zone zone to look up a record from
 323  * @param name name to look up
 324  * @param record_type desired record type, 0 for all
 325  * @param proc function to call on the matching records, or with
 326  *        NULL (rd_count == 0) if there are no matching records
 327  * @param proc_cls closure for proc
 328  * @return a handle that can be used to
 329  *         cancel
 330  */
 331 struct GNUNET_NAMESTORE_QueueEntry *
 332 GNUNET_NAMESTORE_lookup_record (struct GNUNET_NAMESTORE_Handle *h,
 333                               const struct GNUNET_CRYPTO_ShortHashCode *zone,
 334                               const char *name,
 335                               uint32_t record_type,
 336                               GNUNET_NAMESTORE_RecordProcessor proc, void *proc_cls);
 337
 338
 339 /**
 340  * Look for an existing PKEY delegation record for a given public key.
 341  * Returns at most one result to the processor.
 342  *
 343  * @param h handle to the namestore
 344  * @param zone hash of public key of the zone to look up in, never NULL
 345  * @param value_zone hash of the public key of the target zone (value), never NULL
 346  * @param proc function to call on the matching records, or with
 347  *        NULL (rd_count == 0) if there are no matching records
 348  * @param proc_cls closure for proc
 349  * @return a handle that can be used to
 350  *         cancel
 351  */
 352 struct GNUNET_NAMESTORE_QueueEntry *
 353 GNUNET_NAMESTORE_zone_to_name (struct GNUNET_NAMESTORE_Handle *h,
 354                                const struct GNUNET_CRYPTO_ShortHashCode *zone,
 355                                const struct GNUNET_CRYPTO_ShortHashCode *value_zone,
 356                                GNUNET_NAMESTORE_RecordProcessor proc, void *proc_cls);
 357
 358
 359
 360 /**
 361  * Starts a new zone iteration (used to periodically PUT all of our
 362  * records into our DHT). "proc" will be called once
 363  * immediately, and then again after
 364  * "GNUNET_NAMESTORE_zone_iterator_next" is invoked.
 365  *
 366  * @param h handle to the namestore
 367  * @param zone zone to access, NULL for all zones
 368  * @param must_have_flags flags that must be set for the record to be returned
 369  * @param must_not_have_flags flags that must NOT be set for the record to be returned
 370  * @param proc function to call on each name from the zone; it
 371  *        will be called repeatedly with a value (if available)
 372  *        and always once at the end with a name of NULL.
 373  * @param proc_cls closure for proc
 374  * @return an iterator handle to use for iteration
 375  */
 376 struct GNUNET_NAMESTORE_ZoneIterator *
 377 GNUNET_NAMESTORE_zone_iteration_start (struct GNUNET_NAMESTORE_Handle *h,
 378                                        const struct GNUNET_CRYPTO_ShortHashCode *zone,
 379                                        enum GNUNET_NAMESTORE_RecordFlags must_have_flags,
 380                                        enum GNUNET_NAMESTORE_RecordFlags must_not_have_flags,
 381                                        GNUNET_NAMESTORE_RecordProcessor proc,
 382                                        void *proc_cls);
 383
 384
 385 /**
 386  * Calls the record processor specified in GNUNET_NAMESTORE_zone_iteration_start
 387  * for the next record.
 388  *
 389  * @param it the iterator
 390  */
 391 void
 392 GNUNET_NAMESTORE_zone_iterator_next (struct GNUNET_NAMESTORE_ZoneIterator *it);
 393
 394
 395 /**
 396  * Stops iteration and releases the namestore handle for further calls.
 397  *
 398  * @param it the iterator
 399  */
 400 void
 401 GNUNET_NAMESTORE_zone_iteration_stop (struct GNUNET_NAMESTORE_ZoneIterator *it);
 402
 403
 404 /**
 405  * Cancel a namestore operation.  The final callback from the
 406  * operation must not have been done yet.
 407  *
 408  * @param qe operation to cancel
 409  */
 410 void
 411 GNUNET_NAMESTORE_cancel (struct GNUNET_NAMESTORE_QueueEntry *qe);
 412
 413
 414
 415 /* convenience APIs for serializing / deserializing GNS records */
 416
 417 /**
 418  * Calculate how many bytes we will need to serialize the given
 419  * records.
 420  *
 421  * @param rd_count number of records in the rd array
 422  * @param rd array of GNUNET_NAMESTORE_RecordData with rd_count elements
 423  *
 424  * @return the required size to serialize
 425  *
 426  */
 427 size_t
 428 GNUNET_NAMESTORE_records_get_size (unsigned int rd_count,
 429                                    const struct GNUNET_NAMESTORE_RecordData *rd);
 430
 431 /**
 432  * Serialize the given records to the given destination buffer.
 433  *
 434  * @param rd_count number of records in the rd array
 435  * @param rd array of GNUNET_NAMESTORE_RecordData with rd_count elements
 436  * @param dest_size size of the destination array
 437  * @param dest where to write the result
 438  *
 439  * @return the size of serialized records
 440  */
 441 ssize_t
 442 GNUNET_NAMESTORE_records_serialize (unsigned int rd_count,
 443                                     const struct GNUNET_NAMESTORE_RecordData *rd,
 444                                     size_t dest_size,
 445                                     char *dest);
 446
 447
 448 /**
 449  * Deserialize the given records to the given destination.
 450  *
 451  * @param len size of the serialized record data
 452  * @param src the serialized record data
 453  * @param rd_count number of records in the rd array
 454  * @param dest where to put the data
 455  *
 456  * @return GNUNET_OK on success, GNUNET_SYSERR on error
 457  */
 458 int
 459 GNUNET_NAMESTORE_records_deserialize (size_t len,
 460                                       const char *src,
 461                                       unsigned int rd_count,
 462                                       struct GNUNET_NAMESTORE_RecordData *dest);
 463
 464
 465 /**
 466  * Checks if a name is wellformed
 467  *
 468  * @param name the name to check
 469  * @return GNUNET_OK on success, GNUNET_SYSERR on error
 470  */
 471 int
 472 GNUNET_NAMESTORE_check_name (const char * name);
 473
 474 /**
 475  * Convert the 'value' of a record to a string.
 476  *
 477  * @param type type of the record
 478  * @param data value in binary encoding
 479  * @param data_size number of bytes in data
 480  * @return NULL on error, otherwise human-readable representation of the value
 481  */
 482 char *
 483 GNUNET_NAMESTORE_value_to_string (uint32_t type,
 484                                   const void *data,
 485                                   size_t data_size);
 486
 487
 488 /**
 489  * Convert human-readable version of a 'value' of a record to the binary
 490  * representation.
 491  *
 492  * @param type type of the record
 493  * @param s human-readable string
 494  * @param data set to value in binary encoding (will be allocated)
 495  * @param data_size set to number of bytes in data
 496  * @return GNUNET_OK on success
 497  */
 498 int
 499 GNUNET_NAMESTORE_string_to_value (uint32_t type,
 500                                   const char *s,
 501                                   void **data,
 502                                   size_t *data_size);
 503
 504
 505 /**
 506  * Convert a type name (i.e. "AAAA") to the corresponding number.
 507  *
 508  * @param typename name to convert
 509  * @return corresponding number, UINT32_MAX on error
 510  */
 511 uint32_t
 512 GNUNET_NAMESTORE_typename_to_number (const char *typename);
 513
 514
 515 /**
 516  * Convert a type number (i.e. 1) to the corresponding type string (i.e. "A")
 517  *
 518  * @param type number of a type to convert
 519  * @return corresponding typestring, NULL on error
 520  */
 521 const char *
 522 GNUNET_NAMESTORE_number_to_typename (uint32_t type);
 523
 524
 525 #if 0                           /* keep Emacsens' auto-indent happy */
 526 {
 527 #endif
 528 #ifdef __cplusplus
 529 }
 530 #endif
 531
 532 /* end of gnunet_namestore_service.h */
 533 #endif