src/include/gnunet_namestore_service.h

   1 /*
   2      This file is part of GNUnet
   3      (C) 2012, 2013 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 3, 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  *        Naming information can either be records for which this peer/user
  25  *        is authoritative, or blocks which are cached, encrypted naming
  26  *        data from other peers.
  27  * @author Christian Grothoff
  28  */
  29 #ifndef GNUNET_NAMESTORE_SERVICE_H
  30 #define GNUNET_NAMESTORE_SERVICE_H
  31
  32 #include "gnunet_util_lib.h"
  33 #include "gnunet_block_lib.h"
  34
  35 #ifdef __cplusplus
  36 extern "C"
  37 {
  38 #if 0                           /* keep Emacsens' auto-indent happy */
  39 }
  40 #endif
  41 #endif
  42
  43
  44 /**
  45  * Entry in the queue.
  46  */
  47 struct GNUNET_NAMESTORE_QueueEntry;
  48
  49 /**
  50  * Handle to the namestore service.
  51  */
  52 struct GNUNET_NAMESTORE_Handle;
  53
  54 /**
  55  * Handle to the namestore zone iterator.
  56  */
  57 struct GNUNET_NAMESTORE_ZoneIterator;
  58
  59 /**
  60  * Maximum size of a value that can be stored in the namestore.
  61  */
  62 #define GNUNET_NAMESTORE_MAX_VALUE_SIZE (63 * 1024)
  63
  64
  65 /**
  66  * Connect to the namestore service.
  67  *
  68  * @param cfg configuration to use
  69  * @return handle to use to access the service
  70  */
  71 struct GNUNET_NAMESTORE_Handle *
  72 GNUNET_NAMESTORE_connect (const struct GNUNET_CONFIGURATION_Handle *cfg);
  73
  74
  75 /**
  76  * Disconnect from the namestore service (and free associated
  77  * resources).  Must not be called from within operation callbacks of
  78  * the API.
  79  *
  80  * @param h handle to the namestore
  81  */
  82 void
  83 GNUNET_NAMESTORE_disconnect (struct GNUNET_NAMESTORE_Handle *h);
  84
  85
  86 /**
  87  * Continuation called to notify client about result of the
  88  * operation.
  89  *
  90  * @param cls closure
  91  * @param success #GNUNET_SYSERR on failure (including timeout/queue drop/failure to validate)
  92  *                #GNUNET_NO if content was already there or not found
  93  *                #GNUNET_YES (or other positive value) on success
  94  * @param emsg NULL on success, otherwise an error message
  95  */
  96 typedef void (*GNUNET_NAMESTORE_ContinuationWithStatus) (void *cls,
  97                                                          int32_t success,
  98                                                          const char *emsg);
  99
 100
 101 /**
 102  * Flags that can be set for a record.
 103  */
 104 enum GNUNET_NAMESTORE_RecordFlags
 105 {
 106
 107   /**
 108    * No special options.
 109    */
 110   GNUNET_NAMESTORE_RF_NONE = 0,
 111
 112   /**
 113    * This is a private record of this peer and it should
 114    * thus not be handed out to other peers.
 115    */
 116   GNUNET_NAMESTORE_RF_PRIVATE = 2,
 117
 118   /**
 119    * This record was added automatically by the system
 120    * and is pending user confimation.
 121    */
 122   GNUNET_NAMESTORE_RF_PENDING = 4,
 123
 124   /**
 125    * This expiration time of the record is a relative
 126    * time (not an absolute time).
 127    */
 128   GNUNET_NAMESTORE_RF_RELATIVE_EXPIRATION = 8,
 129
 130   /**
 131    * This record should not be used unless all (other) records with an absolute
 132    * expiration time have expired.
 133    */
 134   GNUNET_NAMESTORE_RF_SHADOW_RECORD = 16
 135
 136   /**
 137    * When comparing flags for record equality for removal,
 138    * which flags should must match (in addition to the type,
 139    * name, expiration value and data of the record)?  All flags
 140    * that are not listed here will be ignored for this purpose.
 141    * (for example, we don't expect that users will remember to
 142    * pass the '--private' option when removing a record from
 143    * the namestore, hence we don't require this particular option
 144    * to match upon removal).  See also
 145    * #GNUNET_NAMESTORE_records_cmp.
 146    */
 147 #define GNUNET_NAMESTORE_RF_RCMP_FLAGS (GNUNET_NAMESTORE_RF_RELATIVE_EXPIRATION)
 148 };
 149
 150
 151 /**
 152  * A GNS record.
 153  */
 154 struct GNUNET_NAMESTORE_RecordData
 155 {
 156
 157   /**
 158    * Binary value stored in the DNS record.  Note: "data" must never
 159    * be individually 'malloc'ed, but instead always points into some
 160    * existing data area.
 161    */
 162   const void *data;
 163
 164   /**
 165    * Expiration time for the DNS record.  Can be relative
 166    * or absolute, depending on 'flags'.  Measured in the same
 167    * unit as GNUnet time (microseconds).
 168    */
 169   uint64_t expiration_time;
 170
 171   /**
 172    * Number of bytes in 'data'.
 173    */
 174   size_t data_size;
 175
 176   /**
 177    * Type of the GNS/DNS record.
 178    */
 179   uint32_t record_type;
 180
 181   /**
 182    * Flags for the record.
 183    */
 184   enum GNUNET_NAMESTORE_RecordFlags flags;
 185 };
 186
 187
 188
 189 GNUNET_NETWORK_STRUCT_BEGIN
 190
 191
 192 /**
 193  * Information we have in an encrypted block with record data (i.e. in the DHT).
 194  */
 195 struct GNUNET_NAMESTORE_Block
 196 {
 197
 198   /**
 199    * Signature of the block.
 200    */
 201   struct GNUNET_CRYPTO_EcdsaSignature signature;
 202
 203   /**
 204    * Derived key used for signing; hash of this is the query.
 205    */
 206   struct GNUNET_CRYPTO_EcdsaPublicKey derived_key;
 207
 208   /**
 209    * Number of bytes signed; also specifies the number of bytes
 210    * of encrypted data that follow.
 211    */
 212   struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
 213
 214   /**
 215    * Expiration time of the block.
 216    */
 217   struct GNUNET_TIME_AbsoluteNBO expiration_time;
 218
 219   /* followed by encrypted data */
 220 };
 221
 222
 223
 224 GNUNET_NETWORK_STRUCT_END
 225
 226 /**
 227  * Store an item in the namestore.  If the item is already present,
 228  * it is replaced with the new record.
 229  *
 230  * @param h handle to the namestore
 231  * @param block block to store
 232  * @param cont continuation to call when done
 233  * @param cont_cls closure for @a cont
 234  * @return handle to abort the request
 235  */
 236 struct GNUNET_NAMESTORE_QueueEntry *
 237 GNUNET_NAMESTORE_block_cache (struct GNUNET_NAMESTORE_Handle *h,
 238                               const struct GNUNET_NAMESTORE_Block *block,
 239                               GNUNET_NAMESTORE_ContinuationWithStatus cont,
 240                               void *cont_cls);
 241
 242
 243 /**
 244  * Store an item in the namestore.  If the item is already present,
 245  * it is replaced with the new record.  Use an empty array to
 246  * remove all records under the given name.
 247  *
 248  * @param h handle to the namestore
 249  * @param pkey private key of the zone
 250  * @param label name that is being mapped (at most 255 characters long)
 251  * @param rd_count number of records in the 'rd' array
 252  * @param rd array of records with data to store
 253  * @param cont continuation to call when done
 254  * @param cont_cls closure for @a cont
 255  * @return handle to abort the request
 256  */
 257 struct GNUNET_NAMESTORE_QueueEntry *
 258 GNUNET_NAMESTORE_records_store (struct GNUNET_NAMESTORE_Handle *h,
 259                                 const struct GNUNET_CRYPTO_EcdsaPrivateKey *pkey,
 260                                 const char *label,
 261                                 unsigned int rd_count,
 262                                 const struct GNUNET_NAMESTORE_RecordData *rd,
 263                                 GNUNET_NAMESTORE_ContinuationWithStatus cont,
 264                                 void *cont_cls);
 265
 266
 267 /**
 268  * Process a record that was stored in the namestore.
 269  *
 270  * @param cls closure
 271  * @param block block that was stored in the namestore
 272  */
 273 typedef void (*GNUNET_NAMESTORE_BlockProcessor) (void *cls,
 274                                                  const struct GNUNET_NAMESTORE_Block *block);
 275
 276
 277 /**
 278  * Get a result for a particular key from the namestore.  The processor
 279  * will only be called once.
 280  *
 281  * @param h handle to the namestore
 282  * @param derived_hash hash of zone key combined with name to lookup
 283  *        then at the end once with NULL
 284  * @param proc function to call on the matching block, or with
 285  *        NULL if there is no matching block
 286  * @param proc_cls closure for @a proc
 287  * @return a handle that can be used to cancel
 288  */
 289 struct GNUNET_NAMESTORE_QueueEntry *
 290 GNUNET_NAMESTORE_lookup_block (struct GNUNET_NAMESTORE_Handle *h,
 291                                const struct GNUNET_HashCode *derived_hash,
 292                                GNUNET_NAMESTORE_BlockProcessor proc, void *proc_cls);
 293
 294
 295 /**
 296  * Process a record that was stored in the namestore.
 297  *
 298  * @param cls closure
 299  * @param zone private key of the zone; NULL on disconnect
 300  * @param label label of the records; NULL on disconnect
 301  * @param rd_count number of entries in @a rd array, 0 if label was deleted
 302  * @param rd array of records with data to store
 303  */
 304 typedef void (*GNUNET_NAMESTORE_RecordMonitor) (void *cls,
 305                                                 const struct GNUNET_CRYPTO_EcdsaPrivateKey *zone,
 306                                                 const char *label,
 307                                                 unsigned int rd_count,
 308                                                 const struct GNUNET_NAMESTORE_RecordData *rd);
 309
 310
 311 /**
 312  * Look for an existing PKEY delegation record for a given public key.
 313  * Returns at most one result to the processor.
 314  *
 315  * @param h handle to the namestore
 316  * @param zone public key of the zone to look up in, never NULL
 317  * @param value_zone public key of the target zone (value), never NULL
 318  * @param proc function to call on the matching records, or with
 319  *        NULL (rd_count == 0) if there are no matching records
 320  * @param proc_cls closure for @a proc
 321  * @return a handle that can be used to
 322  *         cancel
 323  */
 324 struct GNUNET_NAMESTORE_QueueEntry *
 325 GNUNET_NAMESTORE_zone_to_name (struct GNUNET_NAMESTORE_Handle *h,
 326                                const struct GNUNET_CRYPTO_EcdsaPrivateKey *zone,
 327                                const struct GNUNET_CRYPTO_EcdsaPublicKey *value_zone,
 328                                GNUNET_NAMESTORE_RecordMonitor proc, void *proc_cls);
 329
 330
 331 /**
 332  * Process a records that were decrypted from a block.
 333  *
 334  * @param cls closure
 335  * @param rd_count number of entries in @a rd array
 336  * @param rd array of records with data to store
 337  */
 338 typedef void (*GNUNET_NAMESTORE_RecordCallback) (void *cls,
 339                                                  unsigned int rd_count,
 340                                                  const struct GNUNET_NAMESTORE_RecordData *rd);
 341
 342
 343 /**
 344  * Cancel a namestore operation.  The final callback from the
 345  * operation must not have been done yet.  Must be called on any
 346  * namestore operation that has not yet completed prior to calling
 347  * #GNUNET_NAMESTORE_disconnect.
 348  *
 349  * @param qe operation to cancel
 350  */
 351 void
 352 GNUNET_NAMESTORE_cancel (struct GNUNET_NAMESTORE_QueueEntry *qe);
 353
 354
 355 /**
 356  * Starts a new zone iteration (used to periodically PUT all of our
 357  * records into our DHT). This MUST lock the struct GNUNET_NAMESTORE_Handle
 358  * for any other calls than #GNUNET_NAMESTORE_zone_iterator_next and
 359  * #GNUNET_NAMESTORE_zone_iteration_stop. @a proc will be called once
 360  * immediately, and then again after
 361  * #GNUNET_NAMESTORE_zone_iterator_next is invoked.
 362  *
 363  * @param h handle to the namestore
 364  * @param zone zone to access, NULL for all zones
 365  * @param proc function to call on each name from the zone; it
 366  *        will be called repeatedly with a value (if available)
 367  *        and always once at the end with a name of NULL.
 368  * @param proc_cls closure for @a proc
 369  * @return an iterator handle to use for iteration
 370  */
 371 struct GNUNET_NAMESTORE_ZoneIterator *
 372 GNUNET_NAMESTORE_zone_iteration_start (struct GNUNET_NAMESTORE_Handle *h,
 373                                        const struct GNUNET_CRYPTO_EcdsaPrivateKey *zone,
 374                                        GNUNET_NAMESTORE_RecordMonitor proc,
 375                                        void *proc_cls);
 376
 377
 378 /**
 379  * Calls the record processor specified in #GNUNET_NAMESTORE_zone_iteration_start
 380  * for the next record.
 381  *
 382  * @param it the iterator
 383  */
 384 void
 385 GNUNET_NAMESTORE_zone_iterator_next (struct GNUNET_NAMESTORE_ZoneIterator *it);
 386
 387
 388 /**
 389  * Stops iteration and releases the namestore handle for further calls.  Must
 390  * be called on any iteration that has not yet completed prior to calling
 391  * #GNUNET_NAMESTORE_disconnect.
 392  *
 393  * @param it the iterator
 394  */
 395 void
 396 GNUNET_NAMESTORE_zone_iteration_stop (struct GNUNET_NAMESTORE_ZoneIterator *it);
 397
 398
 399 /**
 400  * Handle for a monitoring activity.
 401  */
 402 struct GNUNET_NAMESTORE_ZoneMonitor;
 403
 404
 405 /**
 406  * Function called once the monitor has caught up with the current
 407  * state of the database.  Will be called AGAIN after each disconnect
 408  * (record monitor called with 'NULL' for zone_key) once we're again
 409  * in sync.
 410  *
 411  * @param cls closure
 412  */
 413 typedef void (*GNUNET_NAMESTORE_RecordsSynchronizedCallback)(void *cls);
 414
 415
 416 /**
 417  * Begin monitoring a zone for changes.  Will first call the @a monitor function
 418  * on all existing records in the selected zone(s), then calls @a sync_cb,
 419  * and then calls the @a monitor whenever a record changes.  If the namestore
 420  * disconnects, the @a monitor function is called with a disconnect event; if
 421  * the connection is re-established, the process begins from the start (all
 422  * existing records, sync, then updates).
 423  *
 424  * @param cfg configuration to use to connect to namestore
 425  * @param zone zone to monitor
 426  * @param monitor function to call on zone changes
 427  * @param sync_cb function called when we're in sync with the namestore
 428  * @param cls closure for @a monitor and @a sync_cb
 429  * @return handle to stop monitoring
 430  */
 431 struct GNUNET_NAMESTORE_ZoneMonitor *
 432 GNUNET_NAMESTORE_zone_monitor_start (const struct GNUNET_CONFIGURATION_Handle *cfg,
 433                                      const struct GNUNET_CRYPTO_EcdsaPrivateKey *zone,
 434                                      GNUNET_NAMESTORE_RecordMonitor monitor,
 435                                      GNUNET_NAMESTORE_RecordsSynchronizedCallback sync_cb,
 436                                      void *cls);
 437
 438
 439 /**
 440  * Stop monitoring a zone for changes.
 441  *
 442  * @param zm handle to the monitor activity to stop
 443  */
 444 void
 445 GNUNET_NAMESTORE_zone_monitor_stop (struct GNUNET_NAMESTORE_ZoneMonitor *zm);
 446
 447
 448 /* convenience APIs for serializing / deserializing GNS records */
 449
 450 /**
 451  * Calculate how many bytes we will need to serialize the given
 452  * records.
 453  *
 454  * @param rd_count number of records in the @a rd array
 455  * @param rd array of #GNUNET_NAMESTORE_RecordData with @a rd_count elements
 456  * @return the required size to serialize
 457  */
 458 size_t
 459 GNUNET_NAMESTORE_records_get_size (unsigned int rd_count,
 460                                    const struct GNUNET_NAMESTORE_RecordData *rd);
 461
 462
 463 /**
 464  * Serialize the given records to the given destination buffer.
 465  *
 466  * @param rd_count number of records in the @a rd array
 467  * @param rd array of #GNUNET_NAMESTORE_RecordData with @a rd_count elements
 468  * @param dest_size size of the destination array @a dst
 469  * @param dest where to write the result
 470  * @return the size of serialized records, -1 if records do not fit
 471  */
 472 ssize_t
 473 GNUNET_NAMESTORE_records_serialize (unsigned int rd_count,
 474                                     const struct GNUNET_NAMESTORE_RecordData *rd,
 475                                     size_t dest_size,
 476                                     char *dest);
 477
 478
 479 /**
 480  * Deserialize the given records to the given destination.
 481  *
 482  * @param len size of the serialized record data
 483  * @param src the serialized record data
 484  * @param rd_count number of records in the @a dest array
 485  * @param dest where to put the data
 486  * @return #GNUNET_OK on success, #GNUNET_SYSERR on error
 487  */
 488 int
 489 GNUNET_NAMESTORE_records_deserialize (size_t len,
 490                                       const char *src,
 491                                       unsigned int rd_count,
 492                                       struct GNUNET_NAMESTORE_RecordData *dest);
 493
 494
 495 /**
 496  * Test if a given record is expired.
 497  *
 498  * @param rd record to test
 499  * @return #GNUNET_YES if the record is expired,
 500  *         #GNUNET_NO if not
 501  */
 502 int
 503 GNUNET_NAMESTORE_is_expired (const struct GNUNET_NAMESTORE_RecordData *rd);
 504
 505
 506 /**
 507  * Convert a UTF-8 string to UTF-8 lowercase
 508  * @param src source string
 509  * @return converted result
 510  */
 511 char *
 512 GNUNET_NAMESTORE_normalize_string (const char *src);
 513
 514
 515 /**
 516  * Convert a zone to a string (for printing debug messages).
 517  * This is one of the very few calls in the entire API that is
 518  * NOT reentrant!
 519  *
 520  * @param z public key of a zone
 521  * @return string form; will be overwritten by next call to #GNUNET_NAMESTORE_z2s.
 522  */
 523 const char *
 524 GNUNET_NAMESTORE_z2s (const struct GNUNET_CRYPTO_EcdsaPublicKey *z);
 525
 526
 527 /**
 528  * Convert public key to the respective absolute domain name in the
 529  * ".zkey" pTLD.
 530  * This is one of the very few calls in the entire API that is
 531  * NOT reentrant!
 532  *
 533  * @param pkey a public key with a point on the eliptic curve
 534  * @return string "X.zkey" where X is the coordinates of the public
 535  *         key in an encoding suitable for DNS labels.
 536  */
 537 const char *
 538 GNUNET_NAMESTORE_pkey_to_zkey (const struct GNUNET_CRYPTO_EcdsaPublicKey *pkey);
 539
 540
 541 /**
 542  * Convert an absolute domain name in the ".zkey" pTLD to the
 543  * respective public key.
 544  *
 545  * @param zkey string "X.zkey" where X is the public
 546  *         key in an encoding suitable for DNS labels.
 547  * @param pkey set to a public key on the eliptic curve
 548  * @return #GNUNET_SYSERR if @a zkey has the wrong syntax
 549  */
 550 int
 551 GNUNET_NAMESTORE_zkey_to_pkey (const char *zkey,
 552                                struct GNUNET_CRYPTO_EcdsaPublicKey *pkey);
 553
 554
 555 /**
 556  * Calculate the DHT query for a given @a label in a given @a zone.
 557  *
 558  * @param zone private key of the zone
 559  * @param label label of the record
 560  * @param query hash to use for the query
 561  */
 562 void
 563 GNUNET_NAMESTORE_query_from_private_key (const struct GNUNET_CRYPTO_EcdsaPrivateKey *zone,
 564                                          const char *label,
 565                                          struct GNUNET_HashCode *query);
 566
 567
 568 /**
 569  * Calculate the DHT query for a given @a label in a given @a zone.
 570  *
 571  * @param pub public key of the zone
 572  * @param label label of the record
 573  * @param query hash to use for the query
 574  */
 575 void
 576 GNUNET_NAMESTORE_query_from_public_key (const struct GNUNET_CRYPTO_EcdsaPublicKey *pub,
 577                                         const char *label,
 578                                         struct GNUNET_HashCode *query);
 579
 580
 581 /**
 582  * Sign name and records
 583  *
 584  * @param key the private key
 585  * @param expire block expiration
 586  * @param label the name for the records
 587  * @param rd record data
 588  * @param rd_count number of records in @a rd
 589  */
 590 struct GNUNET_NAMESTORE_Block *
 591 GNUNET_NAMESTORE_block_create (const struct GNUNET_CRYPTO_EcdsaPrivateKey *key,
 592                                struct GNUNET_TIME_Absolute expire,
 593                                const char *label,
 594                                const struct GNUNET_NAMESTORE_RecordData *rd,
 595                                unsigned int rd_count);
 596
 597
 598 /**
 599  * Check if a signature is valid.  This API is used by the GNS Block
 600  * to validate signatures received from the network.
 601  *
 602  * @param block block to verify
 603  * @return #GNUNET_OK if the signature is valid
 604  */
 605 int
 606 GNUNET_NAMESTORE_block_verify (const struct GNUNET_NAMESTORE_Block *block);
 607
 608
 609 /**
 610  * Decrypt block.
 611  *
 612  * @param block block to decrypt
 613  * @param zone_key public key of the zone
 614  * @param label the name for the records
 615  * @param proc function to call with the result
 616  * @param proc_cls closure for @a proc
 617  * @return #GNUNET_OK on success, #GNUNET_SYSERR if the block was
 618  *        not well-formed
 619  */
 620 int
 621 GNUNET_NAMESTORE_block_decrypt (const struct GNUNET_NAMESTORE_Block *block,
 622                                 const struct GNUNET_CRYPTO_EcdsaPublicKey *zone_key,
 623                                 const char *label,
 624                                 GNUNET_NAMESTORE_RecordCallback proc,
 625                                 void *proc_cls);
 626
 627
 628 /**
 629  * Compares if two records are equal
 630  *
 631  * @param a a record
 632  * @param b another record
 633  * @return #GNUNET_YES if the records are equal, or #GNUNET_NO if not.
 634  */
 635 int
 636 GNUNET_NAMESTORE_records_cmp (const struct GNUNET_NAMESTORE_RecordData *a,
 637                               const struct GNUNET_NAMESTORE_RecordData *b);
 638
 639
 640 /**
 641  * Returns the expiration time of the given block of records. The block
 642  * expiration time is the expiration time of the record with smallest
 643  * expiration time.
 644  *
 645  * @param rd_count number of records given in @a rd
 646  * @param rd array of records
 647  * @return absolute expiration time
 648  */
 649 struct GNUNET_TIME_Absolute
 650 GNUNET_NAMESTORE_record_get_expiration_time (unsigned int rd_count,
 651                                              const struct GNUNET_NAMESTORE_RecordData *rd);
 652
 653
 654 #if 0                           /* keep Emacsens' auto-indent happy */
 655 {
 656 #endif
 657 #ifdef __cplusplus
 658 }
 659 #endif
 660
 661 /* end of gnunet_namestore_service.h */
 662 #endif