src/fs/fs.h

   1 /*
   2      This file is part of GNUnet.
   3      (C) 2003, 2004, 2005, 2006, 2007, 2008, 2009 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 fs/fs.h
  23  * @brief definitions for the entire fs module
  24  * @author Igor Wronsky, Christian Grothoff
  25  */
  26 #ifndef FS_H
  27 #define FS_H
  28
  29 #include "gnunet_datastore_service.h"
  30 #include "gnunet_fs_service.h"
  31
  32 /**
  33  * Size of the individual blocks used for file-sharing.
  34  */
  35 #define DBLOCK_SIZE (32*1024)
  36
  37
  38 /**
  39  * Pick a multiple of 2 here to achive 8-byte alignment!
  40  * We also probably want DBlocks to have (roughly) the
  41  * same size as IBlocks.  With SHA-512, the optimal
  42  * value is 32768 byte / 128 byte = 256
  43  * (128 byte = 2 * 512 bits).  DO NOT CHANGE!
  44  */
  45 #define CHK_PER_INODE 256
  46
  47
  48 /**
  49  * Maximum size for a file to be considered for
  50  * inlining in a directory.
  51  */
  52 #define MAX_INLINE_SIZE 65536
  53
  54
  55
  56 /**
  57  * @brief content hash key
  58  */
  59 struct ContentHashKey
  60 {
  61   GNUNET_HashCode key;
  62   GNUNET_HashCode query;
  63 };
  64
  65
  66 /**
  67  * @brief complete information needed
  68  * to download a file.
  69  */
  70 struct FileIdentifier
  71 {
  72
  73   /**
  74    * Total size of the file in bytes. (network byte order (!))
  75    */
  76   uint64_t file_length;
  77
  78   /**
  79    * Query and key of the top GNUNET_EC_IBlock.
  80    */
  81   struct ContentHashKey chk;
  82
  83 };
  84
  85
  86 /**
  87  * Information about a file and its location
  88  * (peer claiming to share the file).
  89  */
  90 struct Location
  91 {
  92   /**
  93    * Information about the shared file.
  94    */
  95   struct FileIdentifier fi;
  96
  97   /**
  98    * Identity of the peer sharing the file.
  99    */
 100   struct GNUNET_CRYPTO_RsaPublicKeyBinaryEncoded peer;
 101
 102   /**
 103    * Time when this location URI expires.
 104    */
 105   struct GNUNET_TIME_Absolute expirationTime;
 106
 107   /**
 108    * RSA signature over the GNUNET_EC_FileIdentifier,
 109    * GNUNET_hash of the peer and expiration time.
 110    */
 111   struct GNUNET_CRYPTO_RsaSignature contentSignature;
 112
 113 };
 114
 115 enum uri_types
 116 { chk, sks, ksk, loc };
 117
 118 /**
 119  * A Universal Resource Identifier (URI), opaque.
 120  */
 121 struct GNUNET_FS_Uri
 122 {
 123   enum uri_types type;
 124   union
 125   {
 126     struct
 127     {
 128       /**
 129        * Keywords start with a '+' if they are
 130        * mandatory (in which case the '+' is NOT
 131        * part of the keyword) and with a
 132        * simple space if they are optional
 133        * (in which case the space is ALSO not
 134        * part of the actual keyword).
 135        *
 136        * Double-quotes to protect spaces and
 137        * %-encoding are NOT used internally
 138        * (only in URI-strings).
 139        */
 140       char **keywords;
 141
 142       /**
 143        * Size of the keywords array.
 144        */
 145       unsigned int keywordCount;
 146     } ksk;
 147
 148     struct
 149     {
 150       /**
 151        * Hash of the public key for the namespace.
 152        */
 153       GNUNET_HashCode namespace;
 154
 155       /**
 156        * Human-readable identifier chosen for this
 157        * entry in the namespace.
 158        */
 159       char *identifier;
 160     } sks;
 161
 162     /**
 163      * Information needed to retrieve a file (content-hash-key
 164      * plus file size).
 165      */
 166     struct FileIdentifier chk;
 167
 168     /**
 169      * Information needed to retrieve a file including signed
 170      * location (identity of a peer) of the content.
 171      */
 172     struct Location loc;
 173   } data;
 174
 175 };
 176
 177
 178 /**
 179  * Information for a file or directory that is
 180  * about to be published.
 181  */
 182 struct GNUNET_FS_FileInformation
 183 {
 184
 185   /**
 186    * Files in a directory are kept as a linked list.
 187    */
 188   struct GNUNET_FS_FileInformation *next;
 189
 190   /**
 191    * If this is a file in a directory, "dir" refers to
 192    * the directory; otherwise NULL.
 193    */
 194   struct GNUNET_FS_FileInformation *dir;
 195
 196   /**
 197    * Pointer kept for the client.
 198    */
 199   void *client_info;
 200
 201   /**
 202    * Metadata to use for the file.
 203    */
 204   struct GNUNET_CONTAINER_MetaData *meta;
 205
 206   /**
 207    * Keywords to use for KBlocks.
 208    */
 209   struct GNUNET_FS_Uri *keywords;
 210
 211   /**
 212    * CHK for this file or directory. NULL if
 213    * we have not yet computed it.
 214    */
 215   struct GNUNET_FS_Uri *chk_uri;
 216
 217   /**
 218    * At what time should the content expire?
 219    */
 220   struct GNUNET_TIME_Absolute expirationTime;
 221
 222   /**
 223    * At what time did we start this upload?
 224    */
 225   struct GNUNET_TIME_Absolute start_time;
 226
 227   /**
 228    * Under what filename is this struct serialized
 229    * (for operational persistence).
 230    */
 231   char *serialization;
 232
 233   /**
 234    * In-memory cache of the current CHK tree.
 235    * This struct will contain the CHK values
 236    * from the root to the currently processed
 237    * node in the tree as identified by
 238    * "current_depth" and "publish_offset".
 239    * The "chktree" will be initially NULL,
 240    * then allocated to a sufficient number of
 241    * entries for the size of the file and
 242    * finally freed once the upload is complete.
 243    */
 244   struct ContentHashKey *chk_tree;
 245
 246   /**
 247    * Error message (non-NULL if this operation
 248    * failed).
 249    */
 250   char *emsg;
 251
 252   /**
 253    * Number of entries in "chk_tree".
 254    */
 255   unsigned int chk_tree_depth;
 256
 257   /**
 258    * Depth in the CHK-tree at which we are
 259    * currently publishing.  0 is the root
 260    * of the tree.
 261    */
 262   unsigned int current_depth;
 263
 264   /**
 265    * How many bytes of this file or directory have been
 266    * published so far?
 267    */
 268   uint64_t publish_offset;
 269
 270   /**
 271    * Data describing either the file or the directory.
 272    */
 273   union
 274   {
 275
 276     /**
 277      * Data for a file.
 278      */
 279     struct {
 280
 281       /**
 282        * Function that can be used to read the data for the file.
 283        */
 284       GNUNET_FS_DataReader reader;
 285
 286       /**
 287        * Closure for reader.
 288        */
 289       void *reader_cls;
 290
 291       /**
 292        * Name of the file (must be an absolute path).
 293        * Only required for indexing.  FIXME: not yet
 294        * initialized!
 295        */
 296       char *filename;
 297
 298       /**
 299        * If this file is being indexed, this value
 300        * is set to the hash over the entire file
 301        * (when the indexing process is started).
 302        * Otherwise this field is not used.
 303        */
 304       GNUNET_HashCode file_id;
 305
 306       /**
 307        * Size of the file (in bytes).
 308        */
 309       uint64_t file_size;
 310
 311       /**
 312        * Should the file be indexed or inserted?
 313        */
 314       int do_index;
 315
 316     } file;
 317
 318     /**
 319      * Data for a directory.
 320      */
 321     struct {
 322
 323       /**
 324        * Name of the directory.
 325        */
 326       char *dirname;
 327
 328       /**
 329        * Linked list of entries in the directory.
 330        */
 331       struct GNUNET_FS_FileInformation *entries;
 332
 333       /**
 334        * Size of the directory itself (in bytes); 0 if the
 335        * size has not yet been calculated.
 336        */
 337       size_t dir_size;
 338
 339       /**
 340        * Pointer to the data for the directory (or NULL if not
 341        * available).
 342        */
 343       void *dir_data;
 344
 345     } dir;
 346
 347   } data;
 348
 349   /**
 350    * Is this struct for a file or directory?
 351    */
 352   int is_directory;
 353
 354   /**
 355    * Desired anonymity level.
 356    */
 357   unsigned int anonymity;
 358
 359   /**
 360    * Desired priority (for keeping the content in the DB).
 361    */
 362   unsigned int priority;
 363
 364 };
 365
 366
 367 /**
 368  * Master context for most FS operations.
 369  */
 370 struct GNUNET_FS_Handle
 371 {
 372   /**
 373    * Scheduler.
 374    */
 375   struct GNUNET_SCHEDULER_Handle *sched;
 376
 377   /**
 378    * Configuration to use.
 379    */
 380   const struct GNUNET_CONFIGURATION_Handle *cfg;
 381
 382   /**
 383    * Name of our client.
 384    */
 385   char *client_name;
 386
 387   /**
 388    * Function to call with updates on our progress.
 389    */
 390   GNUNET_FS_ProgressCallback upcb;
 391
 392   /**
 393    * Closure for upcb.
 394    */
 395   void *upcb_cls;
 396
 397   /**
 398    * Connection to the FS service.
 399    */
 400   struct GNUNET_CLIENT_Connection *client;
 401
 402
 403 };
 404
 405
 406 /**
 407  * Handle for controlling an upload.
 408  */
 409 struct GNUNET_FS_PublishContext
 410 {
 411   /**
 412    * Handle to the global fs context.
 413    */
 414   struct GNUNET_FS_Handle *h;
 415
 416   /**
 417    * Argument to pass to the client in callbacks.
 418    */
 419   void *client_ctx;
 420
 421   /**
 422    * File-structure that is being shared.
 423    */
 424   struct GNUNET_FS_FileInformation *fi;
 425
 426   /**
 427    * Namespace that we are publishing in, NULL if we have no namespace.
 428    */
 429   struct GNUNET_FS_Namespace *namespace;
 430
 431   /**
 432    * ID of the content in the namespace, NULL if we have no namespace.
 433    */
 434   char *nid;
 435
 436   /**
 437    * ID for future updates, NULL if we have no namespace or no updates.
 438    */
 439   char *nuid;
 440
 441   /**
 442    * ID of the task performing the upload. NO_TASK
 443    * if the upload has completed.
 444    */
 445   GNUNET_SCHEDULER_TaskIdentifier upload_task;
 446
 447   /**
 448    * Our own client handle for the FS service;
 449    * only briefly used when we start to index a
 450    * file, otherwise NULL.
 451    */
 452   struct GNUNET_CLIENT_Connection *client;
 453
 454   /**
 455    * Typically GNUNET_NO.  Set to GNUNET_YES if
 456    * "upload_task" is GNUNET_SCHEDULER_NO_TASK
 457    * and we're waiting for a response from the
 458    * datastore service (in which case this
 459    * struct must not be freed until we have that
 460    * response).  If someone tries to stop the
 461    * download for good during this period,
 462    * "in_network_wait" is set to GNUNET_SYSERR
 463    * which will cause the struct to be destroyed
 464    * right after we have the reply (or timeout)
 465    * from the datastore service.
 466    */
 467   int in_network_wait;
 468
 469   /**
 470    * Options for publishing.
 471    */
 472   enum GNUNET_FS_PublishOptions options;
 473
 474   /**
 475    * Current position in the file-tree for the
 476    * upload.
 477    */
 478   struct GNUNET_FS_FileInformation *fi_pos;
 479
 480   /**
 481    * Connection to the datastore service.
 482    */
 483   struct GNUNET_DATASTORE_Handle *dsh;
 484
 485   /**
 486    * Space reservation ID with datastore service
 487    * for this upload.
 488    */
 489   int rid;
 490 };
 491
 492
 493 /**
 494  * Handle for controlling an unindexing operation.
 495  */
 496 struct GNUNET_FS_UnindexContext
 497 {
 498 };
 499
 500
 501 /**
 502  * Handle for controlling a search.
 503  */
 504 struct GNUNET_FS_SearchContext
 505 {
 506 };
 507
 508
 509 /**
 510  * Context for controlling a download.
 511  */
 512 struct GNUNET_FS_DownloadContext
 513 {
 514 };
 515
 516 struct GNUNET_FS_Namespace
 517 {
 518
 519   /**
 520    * Private key for the namespace.
 521    */
 522   struct GNUNET_CRYPTO_RsaPrivateKey *key;
 523
 524   /**
 525    * Reference counter.
 526    */
 527   unsigned int rc;
 528 };
 529
 530
 531 /**
 532  * @brief index block (indexing a DBlock that
 533  *        can be obtained directly from reading
 534  *        the plaintext file)
 535  */
 536 struct OnDemandBlock
 537 {
 538   /**
 539    * Hash code of the entire content of the
 540    * file that was indexed (used to uniquely
 541    * identify the plaintext file).
 542    */
 543   GNUNET_HashCode file_id;
 544
 545   /**
 546    * At which offset should we be able to find
 547    * this on-demand encoded block?
 548    */
 549   uint64_t offset;
 550
 551 };
 552
 553
 554 /**
 555  * @brief keyword block (advertising data under a keyword)
 556  */
 557 struct KBlock
 558 {
 559
 560   /**
 561    * GNUNET_RSA_Signature using RSA-key generated from search keyword.
 562    */
 563   struct GNUNET_CRYPTO_RsaSignature signature;
 564
 565   /**
 566    * What is being signed and why?
 567    */
 568   struct GNUNET_CRYPTO_RsaSignaturePurpose purpose;
 569
 570   /**
 571    * Key generated (!) from the H(keyword) as the seed!
 572    */
 573   struct GNUNET_CRYPTO_RsaPublicKeyBinaryEncoded keyspace;
 574
 575   /* 0-terminated URI here */
 576
 577   /* variable-size Meta-Data follows here */
 578
 579 };
 580
 581 /**
 582  * @brief namespace content block (advertising data under an identifier in a namespace)
 583  */
 584 struct SBlock
 585 {
 586
 587   /**
 588    * GNUNET_RSA_Signature using RSA-key of the namespace
 589    */
 590   struct GNUNET_CRYPTO_RsaSignature signature;
 591
 592   /**
 593    * What is being signed and why?
 594    */
 595   struct GNUNET_CRYPTO_RsaSignaturePurpose purpose;
 596
 597   /**
 598    * Hash of the hash of the human-readable identifier used for
 599    * this entry (the hash of the human-readable identifier is
 600    * used as the key for decryption; the xor of this identifier
 601    * and the hash of the "keyspace" is the datastore-query hash).
 602    */
 603   GNUNET_HashCode identifier;
 604
 605   /**
 606    * Public key of the namespace.
 607    */
 608   struct GNUNET_CRYPTO_RsaPublicKeyBinaryEncoded subspace;
 609
 610   /* 0-terminated update-identifier here */
 611
 612   /* 0-terminated URI here */
 613
 614   /* variable-size Meta-Data follows here */
 615
 616 };
 617
 618
 619 /**
 620  * Message sent from a GNUnet (fs) publishing
 621  * activity to the gnunet-fs-service to
 622  * initiate indexing of a file.  The service
 623  * is supposed to check if the specified file
 624  * is available and has the same cryptographic
 625  * hash.  It should then respond with either
 626  * a confirmation or a denial.
 627  *
 628  * On OSes where this works, it is considered
 629  * acceptable if the service only checks that
 630  * the path, device and inode match (it can
 631  * then be assumed that the hash will also match
 632  * without actually computing it; this is an
 633  * optimization that should be safe given that
 634  * the client is not our adversary).
 635  */
 636 struct IndexStartMessage
 637 {
 638
 639   /**
 640    * Message type will be
 641    * GNUNET_MESSAGE_TYPE_FS_INDEX_START.
 642    */
 643   struct GNUNET_MessageHeader header;
 644
 645   /**
 646    * ID of device containing the file, as seen by the client.  This
 647    * device ID is obtained using a call like "statvfs" (and converting
 648    * the "f_fsid" field to a 32-bit big-endian number).  Use 0 if the
 649    * OS does not support this, in which case the service must do a
 650    * full hash recomputation.
 651    */
 652   uint32_t device;
 653
 654   /**
 655    * Inode of the file on the given device, as seen by the client
 656    * ("st_ino" field from "struct stat").  Use 0 if the OS does not
 657    * support this, in which case the service must do a full hash
 658    * recomputation.
 659    */
 660   uint64_t inode;
 661
 662   /**
 663    * Hash of the file that we would like to index.
 664    */
 665   GNUNET_HashCode file_id;
 666
 667   /* this is followed by a 0-terminated
 668      filename of a file with the hash
 669      "file_id" as seen by the client */
 670
 671 };
 672
 673
 674 /**
 675  * Message send by FS service in response to a request
 676  * asking for a list of all indexed files.
 677  */
 678 struct IndexInfoMessage
 679 {
 680   /**
 681    * Message type will be
 682    * GNUNET_MESSAGE_TYPE_FS_INDEX_LIST_ENTRY.
 683    */
 684   struct GNUNET_MessageHeader header;
 685
 686   /**
 687    * Hash of the indexed file.
 688    */
 689   GNUNET_HashCode file_id;
 690
 691   /* this is followed by a 0-terminated
 692      filename of a file with the hash
 693      "file_id" as seen by the client */
 694
 695 };
 696
 697
 698 #endif
 699
 700 /* end of fs.h */