src/include/gnunet_crypto_lib.h

   1 /*
   2      This file is part of GNUnet.
   3      (C) 2001-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_crypto_lib.h
  23  * @brief cryptographic primitives for GNUnet
  24  *
  25  * @author Christian Grothoff
  26  * @author Krista Bennett
  27  * @author Gerd Knorr <kraxel@bytesex.org>
  28  * @author Ioana Patrascu
  29  * @author Tzvetan Horozov
  30  *
  31  * @defgroup crypto Cryptographic operations
  32  * @defgroup hash Hashing and operations on hashes
  33  */
  34
  35 #ifndef GNUNET_CRYPTO_LIB_H
  36 #define GNUNET_CRYPTO_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  * @brief A 512-bit hashcode
  48  */
  49 struct GNUNET_HashCode;
  50
  51 /**
  52  * The identity of the host (wraps the signing key of the peer).
  53  */
  54 struct GNUNET_PeerIdentity;
  55
  56 #include "gnunet_common.h"
  57 #include "gnunet_scheduler_lib.h"
  58
  59
  60 /**
  61  * @brief A 512-bit hashcode
  62  */
  63 struct GNUNET_HashCode
  64 {
  65   uint32_t bits[512 / 8 / sizeof (uint32_t)];   /* = 16 */
  66 };
  67
  68
  69 /**
  70  * Maximum length of an ECC signature.
  71  * Note: round up to multiple of 8 minus 2 for alignment.
  72  */
  73 #define GNUNET_CRYPTO_ECC_SIGNATURE_DATA_ENCODING_LENGTH 126
  74
  75
  76 /**
  77  * Desired quality level for random numbers.
  78  * @ingroup crypto
  79  */
  80 enum GNUNET_CRYPTO_Quality
  81 {
  82   /**
  83    * No good quality of the operation is needed (i.e.,
  84    * random numbers can be pseudo-random).
  85    * @ingroup crypto
  86    */
  87   GNUNET_CRYPTO_QUALITY_WEAK,
  88
  89   /**
  90    * High-quality operations are desired.
  91    * @ingroup crypto
  92    */
  93   GNUNET_CRYPTO_QUALITY_STRONG,
  94
  95   /**
  96    * Randomness for IVs etc. is required.
  97    * @ingroup crypto
  98    */
  99   GNUNET_CRYPTO_QUALITY_NONCE
 100 };
 101
 102
 103 /**
 104  * @brief length of the sessionkey in bytes (256 BIT sessionkey)
 105  */
 106 #define GNUNET_CRYPTO_AES_KEY_LENGTH (256/8)
 107
 108 /**
 109  * Length of a hash value
 110  */
 111 #define GNUNET_CRYPTO_HASH_LENGTH (512/8)
 112
 113 /**
 114  * @brief 0-terminated ASCII encoding of a struct GNUNET_HashCode.
 115  */
 116 struct GNUNET_CRYPTO_HashAsciiEncoded
 117 {
 118   unsigned char encoding[104];
 119 };
 120
 121
 122 GNUNET_NETWORK_STRUCT_BEGIN
 123
 124
 125 /**
 126  * @brief header of what an ECC signature signs
 127  *        this must be followed by "size - 8" bytes of
 128  *        the actual signed data
 129  */
 130 struct GNUNET_CRYPTO_EccSignaturePurpose
 131 {
 132   /**
 133    * How many bytes does this signature sign?
 134    * (including this purpose header); in network
 135    * byte order (!).
 136    */
 137   uint32_t size GNUNET_PACKED;
 138
 139   /**
 140    * What does this signature vouch for?  This
 141    * must contain a GNUNET_SIGNATURE_PURPOSE_XXX
 142    * constant (from gnunet_signatures.h).  In
 143    * network byte order!
 144    */
 145   uint32_t purpose GNUNET_PACKED;
 146
 147 };
 148
 149
 150 /**
 151  * @brief an ECC signature using EdDSA.
 152  * See https://gnunet.org/ed25519
 153  */
 154 struct GNUNET_CRYPTO_EddsaSignature
 155 {
 156
 157   /**
 158    * R value.
 159    */
 160   unsigned char r[256 / 8];
 161
 162   /**
 163    * S value.
 164    */
 165   unsigned char s[256 / 8];
 166
 167 };
 168
 169
 170
 171 /**
 172  * @brief an ECC signature using ECDSA
 173  */
 174 struct GNUNET_CRYPTO_EcdsaSignature
 175 {
 176
 177   /**
 178    * R value.
 179    */
 180   unsigned char r[256 / 8];
 181
 182   /**
 183    * S value.
 184    */
 185   unsigned char s[256 / 8];
 186
 187 };
 188
 189
 190 /**
 191  * Public ECC key (always for Curve25519) encoded in a format suitable
 192  * for network transmission and EdDSA signatures.
 193  */
 194 struct GNUNET_CRYPTO_EddsaPublicKey
 195 {
 196   /**
 197    * Q consists of an x- and a y-value, each mod p (256 bits),
 198    * given here in affine coordinates.
 199    *
 200    * FIXME: this coordinate will be removed in the future (compressed point!).
 201    */
 202   unsigned char q_x[256 / 8];
 203
 204   /**
 205    * Q consists of an x- and a y-value, each mod p (256 bits),
 206    * given here in affine coordinates.
 207    */
 208   unsigned char q_y[256 / 8];
 209
 210 };
 211
 212
 213 /**
 214  * Public ECC key (always for Curve25519) encoded in a format suitable
 215  * for network transmission and ECDSA signatures.
 216  */
 217 struct GNUNET_CRYPTO_EcdsaPublicKey
 218 {
 219   /**
 220    * Q consists of an x- and a y-value, each mod p (256 bits),
 221    * given here in affine coordinates.
 222    *
 223    * FIXME: this coordinate will be removed in the future (compressed point!).
 224    */
 225   unsigned char q_x[256 / 8];
 226
 227   /**
 228    * Q consists of an x- and a y-value, each mod p (256 bits),
 229    * given here in affine coordinates.
 230    */
 231   unsigned char q_y[256 / 8];
 232
 233 };
 234
 235
 236 /**
 237  * The identity of the host (wraps the signing key of the peer).
 238  */
 239 struct GNUNET_PeerIdentity
 240 {
 241   struct GNUNET_CRYPTO_EddsaPublicKey public_key;
 242 };
 243
 244
 245 /**
 246  * Public ECC key (always for Curve25519) encoded in a format suitable
 247  * for network transmission and encryption (ECDH),
 248  * See http://cr.yp.to/ecdh.html
 249  */
 250 struct GNUNET_CRYPTO_EcdhePublicKey
 251 {
 252   /**
 253    * Q consists of an x- and a y-value, each mod p (256 bits),
 254    * given here in affine coordinates.
 255    */
 256   unsigned char q_x[256 / 8];
 257
 258   /**
 259    * Q consists of an x- and a y-value, each mod p (256 bits),
 260    * given here in affine coordinates.
 261    *
 262    * FIXME: this coordinate will be removed in the future (compressed point!).
 263    */
 264   unsigned char q_y[256 / 8];
 265
 266 };
 267
 268
 269 /**
 270  * Private ECC key encoded for transmission.  To be used only for ECDH
 271  * key exchange (ECDHE to be precise).
 272  */
 273 struct GNUNET_CRYPTO_EcdhePrivateKey
 274 {
 275   /**
 276    * d is a value mod n, where n has at most 256 bits.
 277    */
 278   unsigned char d[256 / 8];
 279
 280 };
 281
 282 /**
 283  * Private ECC key encoded for transmission.  To be used only for ECDSA
 284  * signatures.
 285  */
 286 struct GNUNET_CRYPTO_EcdsaPrivateKey
 287 {
 288   /**
 289    * d is a value mod n, where n has at most 256 bits.
 290    */
 291   unsigned char d[256 / 8];
 292
 293 };
 294
 295 /**
 296  * Private ECC key encoded for transmission.  To be used only for EdDSA
 297  * signatures.
 298  */
 299 struct GNUNET_CRYPTO_EddsaPrivateKey
 300 {
 301   /**
 302    * d is a value mod n, where n has at most 256 bits.
 303    */
 304   unsigned char d[256 / 8];
 305
 306 };
 307
 308
 309 /**
 310  * @brief type for session keys
 311  */
 312 struct GNUNET_CRYPTO_SymmetricSessionKey
 313 {
 314   /**
 315    * Actual key for AES.
 316    */
 317   unsigned char aes_key[GNUNET_CRYPTO_AES_KEY_LENGTH];
 318
 319   /**
 320    * Actual key for TwoFish.
 321    */
 322   unsigned char twofish_key[GNUNET_CRYPTO_AES_KEY_LENGTH];
 323
 324 };
 325
 326 GNUNET_NETWORK_STRUCT_END
 327
 328 /**
 329  * @brief IV for sym cipher
 330  *
 331  * NOTE: must be smaller (!) in size than the
 332  * `struct GNUNET_HashCode`.
 333  */
 334 struct GNUNET_CRYPTO_SymmetricInitializationVector
 335 {
 336   unsigned char aes_iv[GNUNET_CRYPTO_AES_KEY_LENGTH / 2];
 337
 338   unsigned char twofish_iv[GNUNET_CRYPTO_AES_KEY_LENGTH / 2];
 339 };
 340
 341
 342 /**
 343  * @brief type for (message) authentication keys
 344  */
 345 struct GNUNET_CRYPTO_AuthKey
 346 {
 347   unsigned char key[GNUNET_CRYPTO_HASH_LENGTH];
 348 };
 349
 350
 351 /* **************** Functions and Macros ************* */
 352
 353 /**
 354  * @ingroup crypto
 355  * Seed a weak random generator. Only #GNUNET_CRYPTO_QUALITY_WEAK-mode generator
 356  * can be seeded.
 357  *
 358  * @param seed the seed to use
 359  */
 360 void
 361 GNUNET_CRYPTO_seed_weak_random (int32_t seed);
 362
 363
 364 /**
 365  * Perform an incremental step in a CRC16 (for TCP/IP) calculation.
 366  *
 367  * @param sum current sum, initially 0
 368  * @param buf buffer to calculate CRC over (must be 16-bit aligned)
 369  * @param len number of bytes in @a buf, must be multiple of 2
 370  * @return updated crc sum (must be subjected to #GNUNET_CRYPTO_crc16_finish to get actual crc16)
 371  */
 372 uint32_t
 373 GNUNET_CRYPTO_crc16_step (uint32_t sum, const void *buf, size_t len);
 374
 375
 376 /**
 377  * Convert results from GNUNET_CRYPTO_crc16_step to final crc16.
 378  *
 379  * @param sum cummulative sum
 380  * @return crc16 value
 381  */
 382 uint16_t
 383 GNUNET_CRYPTO_crc16_finish (uint32_t sum);
 384
 385
 386 /**
 387  * @ingroup hash
 388  * Calculate the checksum of a buffer in one step.
 389  *
 390  * @param buf buffer to calculate CRC over (must be 16-bit aligned)
 391  * @param len number of bytes in @a buf, must be multiple of 2
 392  * @return crc16 value
 393  */
 394 uint16_t
 395 GNUNET_CRYPTO_crc16_n (const void *buf, size_t len);
 396
 397
 398 /**
 399  * @ingroup hash
 400  * Compute the CRC32 checksum for the first len
 401  * bytes of the buffer.
 402  *
 403  * @param buf the data over which we're taking the CRC
 404  * @param len the length of the buffer @a buf in bytes
 405  * @return the resulting CRC32 checksum
 406  */
 407 int32_t
 408 GNUNET_CRYPTO_crc32_n (const void *buf, size_t len);
 409
 410
 411 /**
 412  * @ingroup crypto
 413  * Produce a random value.
 414  *
 415  * @param mode desired quality of the random number
 416  * @param i the upper limit (exclusive) for the random number
 417  * @return a random value in the interval [0,@a i) (exclusive).
 418  */
 419 uint32_t
 420 GNUNET_CRYPTO_random_u32 (enum GNUNET_CRYPTO_Quality mode, uint32_t i);
 421
 422
 423 /**
 424  * @ingroup crypto
 425  * Random on unsigned 64-bit values.
 426  *
 427  * @param mode desired quality of the random number
 428  * @param max value returned will be in range [0,@a max) (exclusive)
 429  * @return random 64-bit number
 430  */
 431 uint64_t
 432 GNUNET_CRYPTO_random_u64 (enum GNUNET_CRYPTO_Quality mode, uint64_t max);
 433
 434
 435 /**
 436  * @ingroup crypto
 437  * Get an array with a random permutation of the
 438  * numbers 0...n-1.
 439  * @param mode #GNUNET_CRYPTO_QUALITY_STRONG if the strong (but expensive) PRNG should be used,
 440  *             #GNUNET_CRYPTO_QUALITY_WEAK or #GNUNET_CRYPTO_QUALITY_NONCE otherwise
 441  * @param n the size of the array
 442  * @return the permutation array (allocated from heap)
 443  */
 444 unsigned int *
 445 GNUNET_CRYPTO_random_permute (enum GNUNET_CRYPTO_Quality mode, unsigned int n);
 446
 447
 448 /**
 449  * @ingroup crypto
 450  * Create a new random session key.
 451  *
 452  * @param key key to initialize
 453  */
 454 void
 455 GNUNET_CRYPTO_symmetric_create_session_key (struct GNUNET_CRYPTO_SymmetricSessionKey *key);
 456
 457
 458 /**
 459  * @ingroup crypto
 460  * Encrypt a block using a symmetric sessionkey.
 461  *
 462  * @param block the block to encrypt
 463  * @param len the size of the block
 464  * @param sessionkey the key used to encrypt
 465  * @param iv the initialization vector to use, use INITVALUE
 466  *        for streams.
 467  * @return the size of the encrypted block, -1 for errors
 468  */
 469 ssize_t
 470 GNUNET_CRYPTO_symmetric_encrypt (const void *block, size_t len,
 471                                  const struct GNUNET_CRYPTO_SymmetricSessionKey *sessionkey,
 472                                  const struct GNUNET_CRYPTO_SymmetricInitializationVector *iv,
 473                                  void *result);
 474
 475
 476 /**
 477  * @ingroup crypto
 478  * Decrypt a given block using a symmetric sessionkey.
 479  *
 480  * @param block the data to decrypt, encoded as returned by encrypt
 481  * @param size how big is the block?
 482  * @param sessionkey the key used to decrypt
 483  * @param iv the initialization vector to use
 484  * @param result address to store the result at
 485  * @return -1 on failure, size of decrypted block on success
 486  */
 487 ssize_t
 488 GNUNET_CRYPTO_symmetric_decrypt (const void *block, size_t size,
 489                                  const struct GNUNET_CRYPTO_SymmetricSessionKey *sessionkey,
 490                                  const struct GNUNET_CRYPTO_SymmetricInitializationVector *iv,
 491                                  void *result);
 492
 493
 494 /**
 495  * @ingroup crypto
 496  * @brief Derive an IV
 497  * @param iv initialization vector
 498  * @param skey session key
 499  * @param salt salt for the derivation
 500  * @param salt_len size of the @a salt
 501  * @param ... pairs of void * & size_t for context chunks, terminated by NULL
 502  */
 503 void
 504 GNUNET_CRYPTO_symmetric_derive_iv (struct GNUNET_CRYPTO_SymmetricInitializationVector *iv,
 505                                    const struct GNUNET_CRYPTO_SymmetricSessionKey *skey,
 506                                    const void *salt,
 507                                    size_t salt_len, ...);
 508
 509
 510 /**
 511  * @brief Derive an IV
 512  * @param iv initialization vector
 513  * @param skey session key
 514  * @param salt salt for the derivation
 515  * @param salt_len size of the @a salt
 516  * @param argp pairs of void * & size_t for context chunks, terminated by NULL
 517  */
 518 void
 519 GNUNET_CRYPTO_symmetric_derive_iv_v (struct GNUNET_CRYPTO_SymmetricInitializationVector *iv,
 520                                      const struct GNUNET_CRYPTO_SymmetricSessionKey *skey,
 521                                      const void *salt,
 522                                      size_t salt_len,
 523                                      va_list argp);
 524
 525
 526 /**
 527  * @ingroup hash
 528  * Convert hash to ASCII encoding.
 529  * @param block the hash code
 530  * @param result where to store the encoding (struct GNUNET_CRYPTO_HashAsciiEncoded can be
 531  *  safely cast to char*, a '\\0' termination is set).
 532  */
 533 void
 534 GNUNET_CRYPTO_hash_to_enc (const struct GNUNET_HashCode * block,
 535                            struct GNUNET_CRYPTO_HashAsciiEncoded *result);
 536
 537
 538 /**
 539  * @ingroup hash
 540  * Convert ASCII encoding back to a 'struct GNUNET_HashCode'
 541  *
 542  * @param enc the encoding
 543  * @param enclen number of characters in @a enc (without 0-terminator, which can be missing)
 544  * @param result where to store the hash code
 545  * @return #GNUNET_OK on success, #GNUNET_SYSERR if result has the wrong encoding
 546  */
 547 int
 548 GNUNET_CRYPTO_hash_from_string2 (const char *enc, size_t enclen,
 549                                  struct GNUNET_HashCode *result);
 550
 551
 552 /**
 553  * @ingroup hash
 554  * Convert ASCII encoding back to `struct GNUNET_HashCode`
 555  *
 556  * @param enc the encoding
 557  * @param result where to store the hash code
 558  * @return #GNUNET_OK on success, #GNUNET_SYSERR if result has the wrong encoding
 559  */
 560 #define GNUNET_CRYPTO_hash_from_string(enc, result) \
 561   GNUNET_CRYPTO_hash_from_string2 (enc, strlen(enc), result)
 562
 563
 564 /**
 565  * @ingroup hash
 566  *
 567  * Compute the distance between 2 hashcodes.  The
 568  * computation must be fast, not involve @a a[0] or @a a[4] (they're used
 569  * elsewhere), and be somewhat consistent. And of course, the result
 570  * should be a positive number.
 571  *
 572  * @param a some hash code
 573  * @param b some hash code
 574  * @return number between 0 and UINT32_MAX
 575  */
 576 uint32_t
 577 GNUNET_CRYPTO_hash_distance_u32 (const struct GNUNET_HashCode *a,
 578                                  const struct GNUNET_HashCode *b);
 579
 580
 581 /**
 582  * @ingroup hash
 583  * Compute hash of a given block.
 584  *
 585  * @param block the data to hash
 586  * @param size size of the @a block
 587  * @param ret pointer to where to write the hashcode
 588  */
 589 void
 590 GNUNET_CRYPTO_hash (const void *block, size_t size, struct GNUNET_HashCode * ret);
 591
 592
 593 /**
 594  * @ingroup hash
 595  * Calculate HMAC of a message (RFC 2104)
 596  *
 597  * @param key secret key
 598  * @param plaintext input plaintext
 599  * @param plaintext_len length of @a plaintext
 600  * @param hmac where to store the hmac
 601  */
 602 void
 603 GNUNET_CRYPTO_hmac (const struct GNUNET_CRYPTO_AuthKey *key,
 604                     const void *plaintext, size_t plaintext_len,
 605                     struct GNUNET_HashCode * hmac);
 606
 607
 608 /**
 609  * Function called once the hash computation over the
 610  * specified file has completed.
 611  *
 612  * @param cls closure
 613  * @param res resulting hash, NULL on error
 614  */
 615 typedef void (*GNUNET_CRYPTO_HashCompletedCallback) (void *cls,
 616                                                      const struct GNUNET_HashCode *res);
 617
 618
 619 /**
 620  * Handle to file hashing operation.
 621  */
 622 struct GNUNET_CRYPTO_FileHashContext;
 623
 624
 625 /**
 626  * @ingroup hash
 627  * Compute the hash of an entire file.
 628  *
 629  * @param priority scheduling priority to use
 630  * @param filename name of file to hash
 631  * @param blocksize number of bytes to process in one task
 632  * @param callback function to call upon completion
 633  * @param callback_cls closure for @a callback
 634  * @return NULL on (immediate) errror
 635  */
 636 struct GNUNET_CRYPTO_FileHashContext *
 637 GNUNET_CRYPTO_hash_file (enum GNUNET_SCHEDULER_Priority priority,
 638                          const char *filename, size_t blocksize,
 639                          GNUNET_CRYPTO_HashCompletedCallback callback,
 640                          void *callback_cls);
 641
 642
 643 /**
 644  * Cancel a file hashing operation.
 645  *
 646  * @param fhc operation to cancel (callback must not yet have been invoked)
 647  */
 648 void
 649 GNUNET_CRYPTO_hash_file_cancel (struct GNUNET_CRYPTO_FileHashContext *fhc);
 650
 651
 652 /**
 653  * @ingroup hash
 654  * Create a random hash code.
 655  *
 656  * @param mode desired quality level
 657  * @param result hash code that is randomized
 658  */
 659 void
 660 GNUNET_CRYPTO_hash_create_random (enum GNUNET_CRYPTO_Quality mode,
 661                                   struct GNUNET_HashCode *result);
 662
 663
 664 /**
 665  * @ingroup hash
 666  * compute @a result = @a b - @a a
 667  *
 668  * @param a some hash code
 669  * @param b some hash code
 670  * @param result set to @a b - @a a
 671  */
 672 void
 673 GNUNET_CRYPTO_hash_difference (const struct GNUNET_HashCode *a,
 674                                const struct GNUNET_HashCode *b,
 675                                struct GNUNET_HashCode *result);
 676
 677
 678 /**
 679  * @ingroup hash
 680  * compute @a result = @a a + @a delta
 681  *
 682  * @param a some hash code
 683  * @param delta some hash code
 684  * @param result set to @a a + @a delta
 685  */
 686 void
 687 GNUNET_CRYPTO_hash_sum (const struct GNUNET_HashCode *a,
 688                         const struct GNUNET_HashCode *delta,
 689                         struct GNUNET_HashCode *result);
 690
 691
 692 /**
 693  * @ingroup hash
 694  * compute result = a ^ b
 695  *
 696  * @param a some hash code
 697  * @param b some hash code
 698  * @param result set to @a a ^ @a b
 699  */
 700 void
 701 GNUNET_CRYPTO_hash_xor (const struct GNUNET_HashCode * a, const struct GNUNET_HashCode * b,
 702                         struct GNUNET_HashCode * result);
 703
 704
 705 /**
 706  * @ingroup hash
 707  * Convert a hashcode into a key.
 708  *
 709  * @param hc hash code that serves to generate the key
 710  * @param skey set to a valid session key
 711  * @param iv set to a valid initialization vector
 712  */
 713 void
 714 GNUNET_CRYPTO_hash_to_aes_key (const struct GNUNET_HashCode * hc,
 715                                struct GNUNET_CRYPTO_SymmetricSessionKey *skey,
 716                                struct GNUNET_CRYPTO_SymmetricInitializationVector *iv);
 717
 718
 719 /**
 720  * @ingroup hash
 721  * Obtain a bit from a hashcode.
 722  *
 723  * @param code the `struct GNUNET_HashCode` to index bit-wise
 724  * @param bit index into the hashcode, [0...159]
 725  * @return Bit \a bit from hashcode \a code, -1 for invalid index
 726  */
 727 int
 728 GNUNET_CRYPTO_hash_get_bit (const struct GNUNET_HashCode *code,
 729                             unsigned int bit);
 730
 731
 732 /**
 733  * @ingroup hash
 734  * Determine how many low order bits match in two
 735  * `struct GNUNET_HashCodes`.  i.e. - 010011 and 011111 share
 736  * the first two lowest order bits, and therefore the
 737  * return value is two (NOT XOR distance, nor how many
 738  * bits match absolutely!).
 739  *
 740  * @param first the first hashcode
 741  * @param second the hashcode to compare first to
 742  * @return the number of bits that match
 743  */
 744 unsigned int
 745 GNUNET_CRYPTO_hash_matching_bits (const struct GNUNET_HashCode *first,
 746                                   const struct GNUNET_HashCode *second);
 747
 748
 749 /**
 750  * @ingroup hash
 751  * Compare function for HashCodes, producing a total ordering
 752  * of all hashcodes.
 753  *
 754  * @param h1 some hash code
 755  * @param h2 some hash code
 756  * @return 1 if @a h1 > @a h2, -1 if @a h1 < @a h2 and 0 if @a h1 == @a h2.
 757  */
 758 int
 759 GNUNET_CRYPTO_hash_cmp (const struct GNUNET_HashCode *h1,
 760                         const struct GNUNET_HashCode *h2);
 761
 762
 763 /**
 764  * @ingroup hash
 765  * Find out which of the two GNUNET_CRYPTO_hash codes is closer to target
 766  * in the XOR metric (Kademlia).
 767  *
 768  * @param h1 some hash code
 769  * @param h2 some hash code
 770  * @param target some hash code
 771  * @return -1 if @a h1 is closer, 1 if @a h2 is closer and 0 if @a h1== @a h2.
 772  */
 773 int
 774 GNUNET_CRYPTO_hash_xorcmp (const struct GNUNET_HashCode *h1,
 775                            const struct GNUNET_HashCode *h2,
 776                            const struct GNUNET_HashCode *target);
 777
 778
 779 /**
 780  * @ingroup hash
 781  * @brief Derive an authentication key
 782  * @param key authentication key
 783  * @param rkey root key
 784  * @param salt salt
 785  * @param salt_len size of the salt
 786  * @param argp pair of void * & size_t for context chunks, terminated by NULL
 787  */
 788 void
 789 GNUNET_CRYPTO_hmac_derive_key_v (struct GNUNET_CRYPTO_AuthKey *key,
 790                                  const struct GNUNET_CRYPTO_SymmetricSessionKey *rkey,
 791                                  const void *salt, size_t salt_len,
 792                                  va_list argp);
 793
 794
 795 /**
 796  * @ingroup hash
 797  * @brief Derive an authentication key
 798  * @param key authentication key
 799  * @param rkey root key
 800  * @param salt salt
 801  * @param salt_len size of the salt
 802  * @param ... pair of void * & size_t for context chunks, terminated by NULL
 803  */
 804 void
 805 GNUNET_CRYPTO_hmac_derive_key (struct GNUNET_CRYPTO_AuthKey *key,
 806                                const struct GNUNET_CRYPTO_SymmetricSessionKey *rkey,
 807                                const void *salt, size_t salt_len, ...);
 808
 809
 810 /**
 811  * @ingroup hash
 812  * @brief Derive key
 813  * @param result buffer for the derived key, allocated by caller
 814  * @param out_len desired length of the derived key
 815  * @param xtr_algo hash algorithm for the extraction phase, GCRY_MD_...
 816  * @param prf_algo hash algorithm for the expansion phase, GCRY_MD_...
 817  * @param xts salt
 818  * @param xts_len length of @a xts
 819  * @param skm source key material
 820  * @param skm_len length of @a skm
 821  * @param ... pair of void * & size_t for context chunks, terminated by NULL
 822  * @return #GNUNET_YES on success
 823  */
 824 int
 825 GNUNET_CRYPTO_hkdf (void *result, size_t out_len, int xtr_algo, int prf_algo,
 826                     const void *xts, size_t xts_len, const void *skm,
 827                     size_t skm_len, ...);
 828
 829
 830 /**
 831  * @ingroup hash
 832  * @brief Derive key
 833  * @param result buffer for the derived key, allocated by caller
 834  * @param out_len desired length of the derived key
 835  * @param xtr_algo hash algorithm for the extraction phase, GCRY_MD_...
 836  * @param prf_algo hash algorithm for the expansion phase, GCRY_MD_...
 837  * @param xts salt
 838  * @param xts_len length of @a xts
 839  * @param skm source key material
 840  * @param skm_len length of @a skm
 841  * @param argp va_list of void * & size_t pairs for context chunks
 842  * @return #GNUNET_YES on success
 843  */
 844 int
 845 GNUNET_CRYPTO_hkdf_v (void *result, size_t out_len, int xtr_algo, int prf_algo,
 846                       const void *xts, size_t xts_len, const void *skm,
 847                       size_t skm_len, va_list argp);
 848
 849
 850 /**
 851  * @brief Derive key
 852  * @param result buffer for the derived key, allocated by caller
 853  * @param out_len desired length of the derived key
 854  * @param xts salt
 855  * @param xts_len length of @a xts
 856  * @param skm source key material
 857  * @param skm_len length of @a skm
 858  * @param argp va_list of void * & size_t pairs for context chunks
 859  * @return #GNUNET_YES on success
 860  */
 861 int
 862 GNUNET_CRYPTO_kdf_v (void *result, size_t out_len, const void *xts,
 863                      size_t xts_len, const void *skm, size_t skm_len,
 864                      va_list argp);
 865
 866
 867 /**
 868  * @ingroup hash
 869  * @brief Derive key
 870  * @param result buffer for the derived key, allocated by caller
 871  * @param out_len desired length of the derived key
 872  * @param xts salt
 873  * @param xts_len length of @a xts
 874  * @param skm source key material
 875  * @param skm_len length of @a skm
 876  * @param ... void * & size_t pairs for context chunks
 877  * @return #GNUNET_YES on success
 878  */
 879 int
 880 GNUNET_CRYPTO_kdf (void *result, size_t out_len, const void *xts,
 881                    size_t xts_len, const void *skm, size_t skm_len, ...);
 882
 883
 884 /**
 885  * @ingroup crypto
 886  * Extract the public key for the given private key.
 887  *
 888  * @param priv the private key
 889  * @param pub where to write the public key
 890  */
 891 void
 892 GNUNET_CRYPTO_ecdsa_key_get_public (const struct GNUNET_CRYPTO_EcdsaPrivateKey *priv,
 893                                     struct GNUNET_CRYPTO_EcdsaPublicKey *pub);
 894
 895 /**
 896  * @ingroup crypto
 897  * Extract the public key for the given private key.
 898  *
 899  * @param priv the private key
 900  * @param pub where to write the public key
 901  */
 902 void
 903 GNUNET_CRYPTO_eddsa_key_get_public (const struct GNUNET_CRYPTO_EddsaPrivateKey *priv,
 904                                     struct GNUNET_CRYPTO_EddsaPublicKey *pub);
 905
 906
 907 /**
 908  * @ingroup crypto
 909  * Extract the public key for the given private key.
 910  *
 911  * @param priv the private key
 912  * @param pub where to write the public key
 913  */
 914 void
 915 GNUNET_CRYPTO_ecdhe_key_get_public (const struct GNUNET_CRYPTO_EcdhePrivateKey *priv,
 916                                     struct GNUNET_CRYPTO_EcdhePublicKey *pub);
 917
 918
 919 /**
 920  * Convert a public key to a string.
 921  *
 922  * @param pub key to convert
 923  * @return string representing @a pub
 924  */
 925 char *
 926 GNUNET_CRYPTO_ecdsa_public_key_to_string (const struct GNUNET_CRYPTO_EcdsaPublicKey *pub);
 927
 928
 929 /**
 930  * Convert a public key to a string.
 931  *
 932  * @param pub key to convert
 933  * @return string representing @a pub
 934  */
 935 char *
 936 GNUNET_CRYPTO_eddsa_public_key_to_string (const struct GNUNET_CRYPTO_EddsaPublicKey *pub);
 937
 938
 939 /**
 940  * Convert a string representing a public key to a public key.
 941  *
 942  * @param enc encoded public key
 943  * @param enclen number of bytes in @a enc (without 0-terminator)
 944  * @param pub where to store the public key
 945  * @return #GNUNET_OK on success
 946  */
 947 int
 948 GNUNET_CRYPTO_ecdsa_public_key_from_string (const char *enc,
 949                                             size_t enclen,
 950                                             struct GNUNET_CRYPTO_EcdsaPublicKey *pub);
 951
 952
 953 /**
 954  * Convert a string representing a public key to a public key.
 955  *
 956  * @param enc encoded public key
 957  * @param enclen number of bytes in @a enc (without 0-terminator)
 958  * @param pub where to store the public key
 959  * @return #GNUNET_OK on success
 960  */
 961 int
 962 GNUNET_CRYPTO_eddsa_public_key_from_string (const char *enc,
 963                                             size_t enclen,
 964                                             struct GNUNET_CRYPTO_EddsaPublicKey *pub);
 965
 966
 967 /**
 968  * @ingroup crypto
 969  * Create a new private key by reading it from a file.  If the
 970  * files does not exist, create a new key and write it to the
 971  * file.  Caller must free return value.  Note that this function
 972  * can not guarantee that another process might not be trying
 973  * the same operation on the same file at the same time.
 974  * If the contents of the file
 975  * are invalid the old file is deleted and a fresh key is
 976  * created.
 977  *
 978  * @param filename name of file to use to store the key
 979  * @return new private key, NULL on error (for example,
 980  *   permission denied); free using #GNUNET_free
 981  */
 982 struct GNUNET_CRYPTO_EcdsaPrivateKey *
 983 GNUNET_CRYPTO_ecdsa_key_create_from_file (const char *filename);
 984
 985
 986 /**
 987  * @ingroup crypto
 988  * Create a new private key by reading it from a file.  If the
 989  * files does not exist, create a new key and write it to the
 990  * file.  Caller must free return value.  Note that this function
 991  * can not guarantee that another process might not be trying
 992  * the same operation on the same file at the same time.
 993  * If the contents of the file
 994  * are invalid the old file is deleted and a fresh key is
 995  * created.
 996  *
 997  * @param filename name of file to use to store the key
 998  * @return new private key, NULL on error (for example,
 999  *   permission denied); free using #GNUNET_free
1000  */
1001 struct GNUNET_CRYPTO_EddsaPrivateKey *
1002 GNUNET_CRYPTO_eddsa_key_create_from_file (const char *filename);
1003
1004
1005 /**
1006  * @ingroup crypto
1007  * Create a new private key by reading our peer's key from
1008  * the file specified in the configuration.
1009  *
1010  * @param cfg the configuration to use
1011  * @return new private key, NULL on error (for example,
1012  *   permission denied); free using #GNUNET_free
1013  */
1014 struct GNUNET_CRYPTO_EddsaPrivateKey *
1015 GNUNET_CRYPTO_eddsa_key_create_from_configuration (const struct GNUNET_CONFIGURATION_Handle *cfg);
1016
1017
1018 /**
1019  * @ingroup crypto
1020  * Create a new private key. Caller must free return value.
1021  *
1022  * @return fresh private key; free using #GNUNET_free
1023  */
1024 struct GNUNET_CRYPTO_EcdsaPrivateKey *
1025 GNUNET_CRYPTO_ecdsa_key_create (void);
1026
1027
1028 /**
1029  * @ingroup crypto
1030  * Create a new private key. Caller must free return value.
1031  *
1032  * @return fresh private key; free using #GNUNET_free
1033  */
1034 struct GNUNET_CRYPTO_EddsaPrivateKey *
1035 GNUNET_CRYPTO_eddsa_key_create (void);
1036
1037
1038 /**
1039  * @ingroup crypto
1040  * Create a new private key. Caller must free return value.
1041  *
1042  * @return fresh private key; free using #GNUNET_free
1043  */
1044 struct GNUNET_CRYPTO_EcdhePrivateKey *
1045 GNUNET_CRYPTO_ecdhe_key_create (void);
1046
1047
1048 /**
1049  * @ingroup crypto
1050  * Clear memory that was used to store a private key.
1051  *
1052  * @param pk location of the key
1053  */
1054 void
1055 GNUNET_CRYPTO_eddsa_key_clear (struct GNUNET_CRYPTO_EddsaPrivateKey *pk);
1056
1057
1058 /**
1059  * @ingroup crypto
1060  * Clear memory that was used to store a private key.
1061  *
1062  * @param pk location of the key
1063  */
1064 void
1065 GNUNET_CRYPTO_ecdsa_key_clear (struct GNUNET_CRYPTO_EcdsaPrivateKey *pk);
1066
1067 /**
1068  * @ingroup crypto
1069  * Clear memory that was used to store a private key.
1070  *
1071  * @param pk location of the key
1072  */
1073 void
1074 GNUNET_CRYPTO_ecdhe_key_clear (struct GNUNET_CRYPTO_EcdhePrivateKey *pk);
1075
1076
1077 /**
1078  * @ingroup crypto
1079  * Get the shared private key we use for anonymous users.
1080  *
1081  * @return "anonymous" private key; do not free
1082  */
1083 const struct GNUNET_CRYPTO_EcdsaPrivateKey *
1084 GNUNET_CRYPTO_ecdsa_key_get_anonymous (void);
1085
1086
1087 /**
1088  * @ingroup crypto
1089  * Setup a hostkey file for a peer given the name of the
1090  * configuration file (!).  This function is used so that
1091  * at a later point code can be certain that reading a
1092  * hostkey is fast (for example in time-dependent testcases).
1093 *
1094  * @param cfg_name name of the configuration file to use
1095  */
1096 void
1097 GNUNET_CRYPTO_eddsa_setup_hostkey (const char *cfg_name);
1098
1099
1100 /**
1101  * @ingroup crypto
1102  * Retrieve the identity of the host's peer.
1103  *
1104  * @param cfg configuration to use
1105  * @param dst pointer to where to write the peer identity
1106  * @return #GNUNET_OK on success, #GNUNET_SYSERR if the identity
1107  *         could not be retrieved
1108  */
1109 int
1110 GNUNET_CRYPTO_get_peer_identity (const struct GNUNET_CONFIGURATION_Handle *cfg,
1111                                  struct GNUNET_PeerIdentity *dst);
1112
1113
1114 /**
1115  * @ingroup crypto
1116  * Derive key material from a public and a private ECC key.
1117  *
1118  * @param priv private key to use for the ECDH (x)
1119  * @param pub public key to use for the ECDH (yG)
1120  * @param key_material where to write the key material (xyG)
1121  * @return #GNUNET_SYSERR on error, #GNUNET_OK on success
1122  */
1123 int
1124 GNUNET_CRYPTO_ecc_ecdh (const struct GNUNET_CRYPTO_EcdhePrivateKey *priv,
1125                         const struct GNUNET_CRYPTO_EcdhePublicKey *pub,
1126                         struct GNUNET_HashCode *key_material);
1127
1128
1129 /**
1130  * @ingroup crypto
1131  * EdDSA sign a given block.
1132  *
1133  * @param priv private key to use for the signing
1134  * @param purpose what to sign (size, purpose)
1135  * @param sig where to write the signature
1136  * @return #GNUNET_SYSERR on error, #GNUNET_OK on success
1137  */
1138 int
1139 GNUNET_CRYPTO_eddsa_sign (const struct GNUNET_CRYPTO_EddsaPrivateKey *priv,
1140                           const struct GNUNET_CRYPTO_EccSignaturePurpose *purpose,
1141                           struct GNUNET_CRYPTO_EddsaSignature *sig);
1142
1143
1144 /**
1145  * @ingroup crypto
1146  * ECDSA Sign a given block.
1147  *
1148  * @param priv private key to use for the signing
1149  * @param purpose what to sign (size, purpose)
1150  * @param sig where to write the signature
1151  * @return #GNUNET_SYSERR on error, #GNUNET_OK on success
1152  */
1153 int
1154 GNUNET_CRYPTO_ecdsa_sign (const struct GNUNET_CRYPTO_EcdsaPrivateKey *priv,
1155                           const struct GNUNET_CRYPTO_EccSignaturePurpose *purpose,
1156                           struct GNUNET_CRYPTO_EcdsaSignature *sig);
1157
1158 /**
1159  * @ingroup crypto
1160  * Verify EdDSA signature.
1161  *
1162  * @param purpose what is the purpose that the signature should have?
1163  * @param validate block to validate (size, purpose, data)
1164  * @param sig signature that is being validated
1165  * @param pub public key of the signer
1166  * @returns #GNUNET_OK if ok, #GNUNET_SYSERR if invalid
1167  */
1168 int
1169 GNUNET_CRYPTO_eddsa_verify (uint32_t purpose,
1170                             const struct GNUNET_CRYPTO_EccSignaturePurpose *validate,
1171                             const struct GNUNET_CRYPTO_EddsaSignature *sig,
1172                             const struct GNUNET_CRYPTO_EddsaPublicKey *pub);
1173
1174
1175
1176 /**
1177  * @ingroup crypto
1178  * Verify ECDSA signature.
1179  *
1180  * @param purpose what is the purpose that the signature should have?
1181  * @param validate block to validate (size, purpose, data)
1182  * @param sig signature that is being validated
1183  * @param pub public key of the signer
1184  * @returns #GNUNET_OK if ok, #GNUNET_SYSERR if invalid
1185  */
1186 int
1187 GNUNET_CRYPTO_ecdsa_verify (uint32_t purpose,
1188                             const struct GNUNET_CRYPTO_EccSignaturePurpose *validate,
1189                             const struct GNUNET_CRYPTO_EcdsaSignature *sig,
1190                             const struct GNUNET_CRYPTO_EcdsaPublicKey *pub);
1191
1192
1193 /**
1194  * @ingroup crypto
1195  * Derive a private key from a given private key and a label.
1196  * Essentially calculates a private key 'h = H(l,P) * d mod n'
1197  * where n is the size of the ECC group and P is the public
1198  * key associated with the private key 'd'.
1199  *
1200  * @param priv original private key
1201  * @param label label to use for key deriviation
1202  * @param context additional context to use for HKDF of 'h';
1203  *        typically the name of the subsystem/application
1204  * @return derived private key
1205  */
1206 struct GNUNET_CRYPTO_EcdsaPrivateKey *
1207 GNUNET_CRYPTO_ecdsa_private_key_derive (const struct GNUNET_CRYPTO_EcdsaPrivateKey *priv,
1208                                         const char *label,
1209                                         const char *context);
1210
1211
1212 /**
1213  * @ingroup crypto
1214  * Derive a public key from a given public key and a label.
1215  * Essentially calculates a public key 'V = H(l,P) * P'.
1216  *
1217  * @param pub original public key
1218  * @param label label to use for key deriviation
1219  * @param context additional context to use for HKDF of 'h'.
1220  *        typically the name of the subsystem/application
1221  * @param result where to write the derived public key
1222  */
1223 void
1224 GNUNET_CRYPTO_ecdsa_public_key_derive (const struct GNUNET_CRYPTO_EcdsaPublicKey *pub,
1225                                        const char *label,
1226                                        const char *context,
1227                                        struct GNUNET_CRYPTO_EcdsaPublicKey *result);
1228
1229
1230 #if 0                           /* keep Emacsens' auto-indent happy */
1231 {
1232 #endif
1233 #ifdef __cplusplus
1234 }
1235 #endif
1236
1237
1238 /* ifndef GNUNET_CRYPTO_LIB_H */
1239 #endif
1240 /* end of gnunet_crypto_lib.h */