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  * Fill block with a random values.
 414  *
 415  * @param mode desired quality of the random number
 416  * @param buffer the buffer to fill
 417  * @param length buffer length
 418  */
 419 void
 420 GNUNET_CRYPTO_random_block (enum GNUNET_CRYPTO_Quality mode, void *buffer, size_t length);
 421
 422 /**
 423  * @ingroup crypto
 424  * Produce a random value.
 425  *
 426  * @param mode desired quality of the random number
 427  * @param i the upper limit (exclusive) for the random number
 428  * @return a random value in the interval [0,@a i) (exclusive).
 429  */
 430 uint32_t
 431 GNUNET_CRYPTO_random_u32 (enum GNUNET_CRYPTO_Quality mode, uint32_t i);
 432
 433
 434 /**
 435  * @ingroup crypto
 436  * Random on unsigned 64-bit values.
 437  *
 438  * @param mode desired quality of the random number
 439  * @param max value returned will be in range [0,@a max) (exclusive)
 440  * @return random 64-bit number
 441  */
 442 uint64_t
 443 GNUNET_CRYPTO_random_u64 (enum GNUNET_CRYPTO_Quality mode, uint64_t max);
 444
 445
 446 /**
 447  * @ingroup crypto
 448  * Get an array with a random permutation of the
 449  * numbers 0...n-1.
 450  * @param mode #GNUNET_CRYPTO_QUALITY_STRONG if the strong (but expensive) PRNG should be used,
 451  *             #GNUNET_CRYPTO_QUALITY_WEAK or #GNUNET_CRYPTO_QUALITY_NONCE otherwise
 452  * @param n the size of the array
 453  * @return the permutation array (allocated from heap)
 454  */
 455 unsigned int *
 456 GNUNET_CRYPTO_random_permute (enum GNUNET_CRYPTO_Quality mode, unsigned int n);
 457
 458
 459 /**
 460  * @ingroup crypto
 461  * Create a new random session key.
 462  *
 463  * @param key key to initialize
 464  */
 465 void
 466 GNUNET_CRYPTO_symmetric_create_session_key (struct GNUNET_CRYPTO_SymmetricSessionKey *key);
 467
 468
 469 /**
 470  * @ingroup crypto
 471  * Encrypt a block using a symmetric sessionkey.
 472  *
 473  * @param block the block to encrypt
 474  * @param len the size of the block
 475  * @param sessionkey the key used to encrypt
 476  * @param iv the initialization vector to use, use INITVALUE
 477  *        for streams.
 478  * @return the size of the encrypted block, -1 for errors
 479  */
 480 ssize_t
 481 GNUNET_CRYPTO_symmetric_encrypt (const void *block, size_t len,
 482                                  const struct GNUNET_CRYPTO_SymmetricSessionKey *sessionkey,
 483                                  const struct GNUNET_CRYPTO_SymmetricInitializationVector *iv,
 484                                  void *result);
 485
 486
 487 /**
 488  * @ingroup crypto
 489  * Decrypt a given block using a symmetric sessionkey.
 490  *
 491  * @param block the data to decrypt, encoded as returned by encrypt
 492  * @param size how big is the block?
 493  * @param sessionkey the key used to decrypt
 494  * @param iv the initialization vector to use
 495  * @param result address to store the result at
 496  * @return -1 on failure, size of decrypted block on success
 497  */
 498 ssize_t
 499 GNUNET_CRYPTO_symmetric_decrypt (const void *block, size_t size,
 500                                  const struct GNUNET_CRYPTO_SymmetricSessionKey *sessionkey,
 501                                  const struct GNUNET_CRYPTO_SymmetricInitializationVector *iv,
 502                                  void *result);
 503
 504
 505 /**
 506  * @ingroup crypto
 507  * @brief Derive an IV
 508  * @param iv initialization vector
 509  * @param skey session key
 510  * @param salt salt for the derivation
 511  * @param salt_len size of the @a salt
 512  * @param ... pairs of void * & size_t for context chunks, terminated by NULL
 513  */
 514 void
 515 GNUNET_CRYPTO_symmetric_derive_iv (struct GNUNET_CRYPTO_SymmetricInitializationVector *iv,
 516                                    const struct GNUNET_CRYPTO_SymmetricSessionKey *skey,
 517                                    const void *salt,
 518                                    size_t salt_len, ...);
 519
 520
 521 /**
 522  * @brief Derive an IV
 523  * @param iv initialization vector
 524  * @param skey session key
 525  * @param salt salt for the derivation
 526  * @param salt_len size of the @a salt
 527  * @param argp pairs of void * & size_t for context chunks, terminated by NULL
 528  */
 529 void
 530 GNUNET_CRYPTO_symmetric_derive_iv_v (struct GNUNET_CRYPTO_SymmetricInitializationVector *iv,
 531                                      const struct GNUNET_CRYPTO_SymmetricSessionKey *skey,
 532                                      const void *salt,
 533                                      size_t salt_len,
 534                                      va_list argp);
 535
 536
 537 /**
 538  * @ingroup hash
 539  * Convert hash to ASCII encoding.
 540  * @param block the hash code
 541  * @param result where to store the encoding (struct GNUNET_CRYPTO_HashAsciiEncoded can be
 542  *  safely cast to char*, a '\\0' termination is set).
 543  */
 544 void
 545 GNUNET_CRYPTO_hash_to_enc (const struct GNUNET_HashCode * block,
 546                            struct GNUNET_CRYPTO_HashAsciiEncoded *result);
 547
 548
 549 /**
 550  * @ingroup hash
 551  * Convert ASCII encoding back to a 'struct GNUNET_HashCode'
 552  *
 553  * @param enc the encoding
 554  * @param enclen number of characters in @a enc (without 0-terminator, which can be missing)
 555  * @param result where to store the hash code
 556  * @return #GNUNET_OK on success, #GNUNET_SYSERR if result has the wrong encoding
 557  */
 558 int
 559 GNUNET_CRYPTO_hash_from_string2 (const char *enc, size_t enclen,
 560                                  struct GNUNET_HashCode *result);
 561
 562
 563 /**
 564  * @ingroup hash
 565  * Convert ASCII encoding back to `struct GNUNET_HashCode`
 566  *
 567  * @param enc the encoding
 568  * @param result where to store the hash code
 569  * @return #GNUNET_OK on success, #GNUNET_SYSERR if result has the wrong encoding
 570  */
 571 #define GNUNET_CRYPTO_hash_from_string(enc, result) \
 572   GNUNET_CRYPTO_hash_from_string2 (enc, strlen(enc), result)
 573
 574
 575 /**
 576  * @ingroup hash
 577  *
 578  * Compute the distance between 2 hashcodes.  The
 579  * computation must be fast, not involve @a a[0] or @a a[4] (they're used
 580  * elsewhere), and be somewhat consistent. And of course, the result
 581  * should be a positive number.
 582  *
 583  * @param a some hash code
 584  * @param b some hash code
 585  * @return number between 0 and UINT32_MAX
 586  */
 587 uint32_t
 588 GNUNET_CRYPTO_hash_distance_u32 (const struct GNUNET_HashCode *a,
 589                                  const struct GNUNET_HashCode *b);
 590
 591
 592 /**
 593  * @ingroup hash
 594  * Compute hash of a given block.
 595  *
 596  * @param block the data to hash
 597  * @param size size of the @a block
 598  * @param ret pointer to where to write the hashcode
 599  */
 600 void
 601 GNUNET_CRYPTO_hash (const void *block, size_t size, struct GNUNET_HashCode * ret);
 602
 603
 604 /**
 605  * @ingroup hash
 606  * Calculate HMAC of a message (RFC 2104)
 607  *
 608  * @param key secret key
 609  * @param plaintext input plaintext
 610  * @param plaintext_len length of @a plaintext
 611  * @param hmac where to store the hmac
 612  */
 613 void
 614 GNUNET_CRYPTO_hmac (const struct GNUNET_CRYPTO_AuthKey *key,
 615                     const void *plaintext, size_t plaintext_len,
 616                     struct GNUNET_HashCode * hmac);
 617
 618
 619 /**
 620  * Function called once the hash computation over the
 621  * specified file has completed.
 622  *
 623  * @param cls closure
 624  * @param res resulting hash, NULL on error
 625  */
 626 typedef void (*GNUNET_CRYPTO_HashCompletedCallback) (void *cls,
 627                                                      const struct GNUNET_HashCode *res);
 628
 629
 630 /**
 631  * Handle to file hashing operation.
 632  */
 633 struct GNUNET_CRYPTO_FileHashContext;
 634
 635
 636 /**
 637  * @ingroup hash
 638  * Compute the hash of an entire file.
 639  *
 640  * @param priority scheduling priority to use
 641  * @param filename name of file to hash
 642  * @param blocksize number of bytes to process in one task
 643  * @param callback function to call upon completion
 644  * @param callback_cls closure for @a callback
 645  * @return NULL on (immediate) errror
 646  */
 647 struct GNUNET_CRYPTO_FileHashContext *
 648 GNUNET_CRYPTO_hash_file (enum GNUNET_SCHEDULER_Priority priority,
 649                          const char *filename, size_t blocksize,
 650                          GNUNET_CRYPTO_HashCompletedCallback callback,
 651                          void *callback_cls);
 652
 653
 654 /**
 655  * Cancel a file hashing operation.
 656  *
 657  * @param fhc operation to cancel (callback must not yet have been invoked)
 658  */
 659 void
 660 GNUNET_CRYPTO_hash_file_cancel (struct GNUNET_CRYPTO_FileHashContext *fhc);
 661
 662
 663 /**
 664  * @ingroup hash
 665  * Create a random hash code.
 666  *
 667  * @param mode desired quality level
 668  * @param result hash code that is randomized
 669  */
 670 void
 671 GNUNET_CRYPTO_hash_create_random (enum GNUNET_CRYPTO_Quality mode,
 672                                   struct GNUNET_HashCode *result);
 673
 674
 675 /**
 676  * @ingroup hash
 677  * compute @a result = @a b - @a a
 678  *
 679  * @param a some hash code
 680  * @param b some hash code
 681  * @param result set to @a b - @a a
 682  */
 683 void
 684 GNUNET_CRYPTO_hash_difference (const struct GNUNET_HashCode *a,
 685                                const struct GNUNET_HashCode *b,
 686                                struct GNUNET_HashCode *result);
 687
 688
 689 /**
 690  * @ingroup hash
 691  * compute @a result = @a a + @a delta
 692  *
 693  * @param a some hash code
 694  * @param delta some hash code
 695  * @param result set to @a a + @a delta
 696  */
 697 void
 698 GNUNET_CRYPTO_hash_sum (const struct GNUNET_HashCode *a,
 699                         const struct GNUNET_HashCode *delta,
 700                         struct GNUNET_HashCode *result);
 701
 702
 703 /**
 704  * @ingroup hash
 705  * compute result = a ^ b
 706  *
 707  * @param a some hash code
 708  * @param b some hash code
 709  * @param result set to @a a ^ @a b
 710  */
 711 void
 712 GNUNET_CRYPTO_hash_xor (const struct GNUNET_HashCode * a, const struct GNUNET_HashCode * b,
 713                         struct GNUNET_HashCode * result);
 714
 715
 716 /**
 717  * @ingroup hash
 718  * Convert a hashcode into a key.
 719  *
 720  * @param hc hash code that serves to generate the key
 721  * @param skey set to a valid session key
 722  * @param iv set to a valid initialization vector
 723  */
 724 void
 725 GNUNET_CRYPTO_hash_to_aes_key (const struct GNUNET_HashCode * hc,
 726                                struct GNUNET_CRYPTO_SymmetricSessionKey *skey,
 727                                struct GNUNET_CRYPTO_SymmetricInitializationVector *iv);
 728
 729
 730 /**
 731  * @ingroup hash
 732  * Obtain a bit from a hashcode.
 733  *
 734  * @param code the `struct GNUNET_HashCode` to index bit-wise
 735  * @param bit index into the hashcode, [0...159]
 736  * @return Bit \a bit from hashcode \a code, -1 for invalid index
 737  */
 738 int
 739 GNUNET_CRYPTO_hash_get_bit (const struct GNUNET_HashCode *code,
 740                             unsigned int bit);
 741
 742
 743 /**
 744  * @ingroup hash
 745  * Determine how many low order bits match in two
 746  * `struct GNUNET_HashCodes`.  i.e. - 010011 and 011111 share
 747  * the first two lowest order bits, and therefore the
 748  * return value is two (NOT XOR distance, nor how many
 749  * bits match absolutely!).
 750  *
 751  * @param first the first hashcode
 752  * @param second the hashcode to compare first to
 753  * @return the number of bits that match
 754  */
 755 unsigned int
 756 GNUNET_CRYPTO_hash_matching_bits (const struct GNUNET_HashCode *first,
 757                                   const struct GNUNET_HashCode *second);
 758
 759
 760 /**
 761  * @ingroup hash
 762  * Compare function for HashCodes, producing a total ordering
 763  * of all hashcodes.
 764  *
 765  * @param h1 some hash code
 766  * @param h2 some hash code
 767  * @return 1 if @a h1 > @a h2, -1 if @a h1 < @a h2 and 0 if @a h1 == @a h2.
 768  */
 769 int
 770 GNUNET_CRYPTO_hash_cmp (const struct GNUNET_HashCode *h1,
 771                         const struct GNUNET_HashCode *h2);
 772
 773
 774 /**
 775  * @ingroup hash
 776  * Find out which of the two GNUNET_CRYPTO_hash codes is closer to target
 777  * in the XOR metric (Kademlia).
 778  *
 779  * @param h1 some hash code
 780  * @param h2 some hash code
 781  * @param target some hash code
 782  * @return -1 if @a h1 is closer, 1 if @a h2 is closer and 0 if @a h1== @a h2.
 783  */
 784 int
 785 GNUNET_CRYPTO_hash_xorcmp (const struct GNUNET_HashCode *h1,
 786                            const struct GNUNET_HashCode *h2,
 787                            const struct GNUNET_HashCode *target);
 788
 789
 790 /**
 791  * @ingroup hash
 792  * @brief Derive an authentication key
 793  * @param key authentication key
 794  * @param rkey root key
 795  * @param salt salt
 796  * @param salt_len size of the salt
 797  * @param argp pair of void * & size_t for context chunks, terminated by NULL
 798  */
 799 void
 800 GNUNET_CRYPTO_hmac_derive_key_v (struct GNUNET_CRYPTO_AuthKey *key,
 801                                  const struct GNUNET_CRYPTO_SymmetricSessionKey *rkey,
 802                                  const void *salt, size_t salt_len,
 803                                  va_list argp);
 804
 805
 806 /**
 807  * @ingroup hash
 808  * @brief Derive an authentication key
 809  * @param key authentication key
 810  * @param rkey root key
 811  * @param salt salt
 812  * @param salt_len size of the salt
 813  * @param ... pair of void * & size_t for context chunks, terminated by NULL
 814  */
 815 void
 816 GNUNET_CRYPTO_hmac_derive_key (struct GNUNET_CRYPTO_AuthKey *key,
 817                                const struct GNUNET_CRYPTO_SymmetricSessionKey *rkey,
 818                                const void *salt, size_t salt_len, ...);
 819
 820
 821 /**
 822  * @ingroup hash
 823  * @brief Derive key
 824  * @param result buffer for the derived key, allocated by caller
 825  * @param out_len desired length of the derived key
 826  * @param xtr_algo hash algorithm for the extraction phase, GCRY_MD_...
 827  * @param prf_algo hash algorithm for the expansion phase, GCRY_MD_...
 828  * @param xts salt
 829  * @param xts_len length of @a xts
 830  * @param skm source key material
 831  * @param skm_len length of @a skm
 832  * @param ... pair of void * & size_t for context chunks, terminated by NULL
 833  * @return #GNUNET_YES on success
 834  */
 835 int
 836 GNUNET_CRYPTO_hkdf (void *result, size_t out_len, int xtr_algo, int prf_algo,
 837                     const void *xts, size_t xts_len, const void *skm,
 838                     size_t skm_len, ...);
 839
 840
 841 /**
 842  * @ingroup hash
 843  * @brief Derive key
 844  * @param result buffer for the derived key, allocated by caller
 845  * @param out_len desired length of the derived key
 846  * @param xtr_algo hash algorithm for the extraction phase, GCRY_MD_...
 847  * @param prf_algo hash algorithm for the expansion phase, GCRY_MD_...
 848  * @param xts salt
 849  * @param xts_len length of @a xts
 850  * @param skm source key material
 851  * @param skm_len length of @a skm
 852  * @param argp va_list of void * & size_t pairs for context chunks
 853  * @return #GNUNET_YES on success
 854  */
 855 int
 856 GNUNET_CRYPTO_hkdf_v (void *result, size_t out_len, int xtr_algo, int prf_algo,
 857                       const void *xts, size_t xts_len, const void *skm,
 858                       size_t skm_len, va_list argp);
 859
 860
 861 /**
 862  * @brief Derive key
 863  * @param result buffer for the derived key, allocated by caller
 864  * @param out_len desired length of the derived key
 865  * @param xts salt
 866  * @param xts_len length of @a xts
 867  * @param skm source key material
 868  * @param skm_len length of @a skm
 869  * @param argp va_list of void * & size_t pairs for context chunks
 870  * @return #GNUNET_YES on success
 871  */
 872 int
 873 GNUNET_CRYPTO_kdf_v (void *result, size_t out_len, const void *xts,
 874                      size_t xts_len, const void *skm, size_t skm_len,
 875                      va_list argp);
 876
 877
 878 /**
 879  * @ingroup hash
 880  * @brief Derive key
 881  * @param result buffer for the derived key, allocated by caller
 882  * @param out_len desired length of the derived key
 883  * @param xts salt
 884  * @param xts_len length of @a xts
 885  * @param skm source key material
 886  * @param skm_len length of @a skm
 887  * @param ... void * & size_t pairs for context chunks
 888  * @return #GNUNET_YES on success
 889  */
 890 int
 891 GNUNET_CRYPTO_kdf (void *result, size_t out_len, const void *xts,
 892                    size_t xts_len, const void *skm, size_t skm_len, ...);
 893
 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_ecdsa_key_get_public (const struct GNUNET_CRYPTO_EcdsaPrivateKey *priv,
 904                                     struct GNUNET_CRYPTO_EcdsaPublicKey *pub);
 905
 906 /**
 907  * @ingroup crypto
 908  * Extract the public key for the given private key.
 909  *
 910  * @param priv the private key
 911  * @param pub where to write the public key
 912  */
 913 void
 914 GNUNET_CRYPTO_eddsa_key_get_public (const struct GNUNET_CRYPTO_EddsaPrivateKey *priv,
 915                                     struct GNUNET_CRYPTO_EddsaPublicKey *pub);
 916
 917
 918 /**
 919  * @ingroup crypto
 920  * Extract the public key for the given private key.
 921  *
 922  * @param priv the private key
 923  * @param pub where to write the public key
 924  */
 925 void
 926 GNUNET_CRYPTO_ecdhe_key_get_public (const struct GNUNET_CRYPTO_EcdhePrivateKey *priv,
 927                                     struct GNUNET_CRYPTO_EcdhePublicKey *pub);
 928
 929
 930 /**
 931  * Convert a public key to a string.
 932  *
 933  * @param pub key to convert
 934  * @return string representing @a pub
 935  */
 936 char *
 937 GNUNET_CRYPTO_ecdsa_public_key_to_string (const struct GNUNET_CRYPTO_EcdsaPublicKey *pub);
 938
 939
 940 /**
 941  * Convert a public key to a string.
 942  *
 943  * @param pub key to convert
 944  * @return string representing @a pub
 945  */
 946 char *
 947 GNUNET_CRYPTO_eddsa_public_key_to_string (const struct GNUNET_CRYPTO_EddsaPublicKey *pub);
 948
 949
 950 /**
 951  * Convert a string representing a public key to a public key.
 952  *
 953  * @param enc encoded public key
 954  * @param enclen number of bytes in @a enc (without 0-terminator)
 955  * @param pub where to store the public key
 956  * @return #GNUNET_OK on success
 957  */
 958 int
 959 GNUNET_CRYPTO_ecdsa_public_key_from_string (const char *enc,
 960                                             size_t enclen,
 961                                             struct GNUNET_CRYPTO_EcdsaPublicKey *pub);
 962
 963
 964 /**
 965  * Convert a string representing a public key to a public key.
 966  *
 967  * @param enc encoded public key
 968  * @param enclen number of bytes in @a enc (without 0-terminator)
 969  * @param pub where to store the public key
 970  * @return #GNUNET_OK on success
 971  */
 972 int
 973 GNUNET_CRYPTO_eddsa_public_key_from_string (const char *enc,
 974                                             size_t enclen,
 975                                             struct GNUNET_CRYPTO_EddsaPublicKey *pub);
 976
 977
 978 /**
 979  * @ingroup crypto
 980  * Create a new private key by reading it from a file.  If the
 981  * files does not exist, create a new key and write it to the
 982  * file.  Caller must free return value.  Note that this function
 983  * can not guarantee that another process might not be trying
 984  * the same operation on the same file at the same time.
 985  * If the contents of the file
 986  * are invalid the old file is deleted and a fresh key is
 987  * created.
 988  *
 989  * @param filename name of file to use to store the key
 990  * @return new private key, NULL on error (for example,
 991  *   permission denied); free using #GNUNET_free
 992  */
 993 struct GNUNET_CRYPTO_EcdsaPrivateKey *
 994 GNUNET_CRYPTO_ecdsa_key_create_from_file (const char *filename);
 995
 996
 997 /**
 998  * @ingroup crypto
 999  * Create a new private key by reading it from a file.  If the
1000  * files does not exist, create a new key and write it to the
1001  * file.  Caller must free return value.  Note that this function
1002  * can not guarantee that another process might not be trying
1003  * the same operation on the same file at the same time.
1004  * If the contents of the file
1005  * are invalid the old file is deleted and a fresh key is
1006  * created.
1007  *
1008  * @param filename name of file to use to store the key
1009  * @return new private key, NULL on error (for example,
1010  *   permission denied); free using #GNUNET_free
1011  */
1012 struct GNUNET_CRYPTO_EddsaPrivateKey *
1013 GNUNET_CRYPTO_eddsa_key_create_from_file (const char *filename);
1014
1015
1016 /**
1017  * @ingroup crypto
1018  * Create a new private key by reading our peer's key from
1019  * the file specified in the configuration.
1020  *
1021  * @param cfg the configuration to use
1022  * @return new private key, NULL on error (for example,
1023  *   permission denied); free using #GNUNET_free
1024  */
1025 struct GNUNET_CRYPTO_EddsaPrivateKey *
1026 GNUNET_CRYPTO_eddsa_key_create_from_configuration (const struct GNUNET_CONFIGURATION_Handle *cfg);
1027
1028
1029 /**
1030  * @ingroup crypto
1031  * Create a new private key. Caller must free return value.
1032  *
1033  * @return fresh private key; free using #GNUNET_free
1034  */
1035 struct GNUNET_CRYPTO_EcdsaPrivateKey *
1036 GNUNET_CRYPTO_ecdsa_key_create (void);
1037
1038
1039 /**
1040  * @ingroup crypto
1041  * Create a new private key. Caller must free return value.
1042  *
1043  * @return fresh private key; free using #GNUNET_free
1044  */
1045 struct GNUNET_CRYPTO_EddsaPrivateKey *
1046 GNUNET_CRYPTO_eddsa_key_create (void);
1047
1048
1049 /**
1050  * @ingroup crypto
1051  * Create a new private key. Caller must free return value.
1052  *
1053  * @return fresh private key; free using #GNUNET_free
1054  */
1055 struct GNUNET_CRYPTO_EcdhePrivateKey *
1056 GNUNET_CRYPTO_ecdhe_key_create (void);
1057
1058
1059 /**
1060  * @ingroup crypto
1061  * Clear memory that was used to store a private key.
1062  *
1063  * @param pk location of the key
1064  */
1065 void
1066 GNUNET_CRYPTO_eddsa_key_clear (struct GNUNET_CRYPTO_EddsaPrivateKey *pk);
1067
1068
1069 /**
1070  * @ingroup crypto
1071  * Clear memory that was used to store a private key.
1072  *
1073  * @param pk location of the key
1074  */
1075 void
1076 GNUNET_CRYPTO_ecdsa_key_clear (struct GNUNET_CRYPTO_EcdsaPrivateKey *pk);
1077
1078 /**
1079  * @ingroup crypto
1080  * Clear memory that was used to store a private key.
1081  *
1082  * @param pk location of the key
1083  */
1084 void
1085 GNUNET_CRYPTO_ecdhe_key_clear (struct GNUNET_CRYPTO_EcdhePrivateKey *pk);
1086
1087
1088 /**
1089  * @ingroup crypto
1090  * Get the shared private key we use for anonymous users.
1091  *
1092  * @return "anonymous" private key; do not free
1093  */
1094 const struct GNUNET_CRYPTO_EcdsaPrivateKey *
1095 GNUNET_CRYPTO_ecdsa_key_get_anonymous (void);
1096
1097
1098 /**
1099  * @ingroup crypto
1100  * Setup a hostkey file for a peer given the name of the
1101  * configuration file (!).  This function is used so that
1102  * at a later point code can be certain that reading a
1103  * hostkey is fast (for example in time-dependent testcases).
1104 *
1105  * @param cfg_name name of the configuration file to use
1106  */
1107 void
1108 GNUNET_CRYPTO_eddsa_setup_hostkey (const char *cfg_name);
1109
1110
1111 /**
1112  * @ingroup crypto
1113  * Retrieve the identity of the host's peer.
1114  *
1115  * @param cfg configuration to use
1116  * @param dst pointer to where to write the peer identity
1117  * @return #GNUNET_OK on success, #GNUNET_SYSERR if the identity
1118  *         could not be retrieved
1119  */
1120 int
1121 GNUNET_CRYPTO_get_peer_identity (const struct GNUNET_CONFIGURATION_Handle *cfg,
1122                                  struct GNUNET_PeerIdentity *dst);
1123
1124
1125 /**
1126  * @ingroup crypto
1127  * Derive key material from a public and a private ECC key.
1128  *
1129  * @param priv private key to use for the ECDH (x)
1130  * @param pub public key to use for the ECDH (yG)
1131  * @param key_material where to write the key material (xyG)
1132  * @return #GNUNET_SYSERR on error, #GNUNET_OK on success
1133  */
1134 int
1135 GNUNET_CRYPTO_ecc_ecdh (const struct GNUNET_CRYPTO_EcdhePrivateKey *priv,
1136                         const struct GNUNET_CRYPTO_EcdhePublicKey *pub,
1137                         struct GNUNET_HashCode *key_material);
1138
1139
1140 /**
1141  * @ingroup crypto
1142  * EdDSA sign a given block.
1143  *
1144  * @param priv private key to use for the signing
1145  * @param purpose what to sign (size, purpose)
1146  * @param sig where to write the signature
1147  * @return #GNUNET_SYSERR on error, #GNUNET_OK on success
1148  */
1149 int
1150 GNUNET_CRYPTO_eddsa_sign (const struct GNUNET_CRYPTO_EddsaPrivateKey *priv,
1151                           const struct GNUNET_CRYPTO_EccSignaturePurpose *purpose,
1152                           struct GNUNET_CRYPTO_EddsaSignature *sig);
1153
1154
1155 /**
1156  * @ingroup crypto
1157  * ECDSA Sign a given block.
1158  *
1159  * @param priv private key to use for the signing
1160  * @param purpose what to sign (size, purpose)
1161  * @param sig where to write the signature
1162  * @return #GNUNET_SYSERR on error, #GNUNET_OK on success
1163  */
1164 int
1165 GNUNET_CRYPTO_ecdsa_sign (const struct GNUNET_CRYPTO_EcdsaPrivateKey *priv,
1166                           const struct GNUNET_CRYPTO_EccSignaturePurpose *purpose,
1167                           struct GNUNET_CRYPTO_EcdsaSignature *sig);
1168
1169 /**
1170  * @ingroup crypto
1171  * Verify EdDSA signature.
1172  *
1173  * @param purpose what is the purpose that the signature should have?
1174  * @param validate block to validate (size, purpose, data)
1175  * @param sig signature that is being validated
1176  * @param pub public key of the signer
1177  * @returns #GNUNET_OK if ok, #GNUNET_SYSERR if invalid
1178  */
1179 int
1180 GNUNET_CRYPTO_eddsa_verify (uint32_t purpose,
1181                             const struct GNUNET_CRYPTO_EccSignaturePurpose *validate,
1182                             const struct GNUNET_CRYPTO_EddsaSignature *sig,
1183                             const struct GNUNET_CRYPTO_EddsaPublicKey *pub);
1184
1185
1186
1187 /**
1188  * @ingroup crypto
1189  * Verify ECDSA signature.
1190  *
1191  * @param purpose what is the purpose that the signature should have?
1192  * @param validate block to validate (size, purpose, data)
1193  * @param sig signature that is being validated
1194  * @param pub public key of the signer
1195  * @returns #GNUNET_OK if ok, #GNUNET_SYSERR if invalid
1196  */
1197 int
1198 GNUNET_CRYPTO_ecdsa_verify (uint32_t purpose,
1199                             const struct GNUNET_CRYPTO_EccSignaturePurpose *validate,
1200                             const struct GNUNET_CRYPTO_EcdsaSignature *sig,
1201                             const struct GNUNET_CRYPTO_EcdsaPublicKey *pub);
1202
1203
1204 /**
1205  * @ingroup crypto
1206  * Derive a private key from a given private key and a label.
1207  * Essentially calculates a private key 'h = H(l,P) * d mod n'
1208  * where n is the size of the ECC group and P is the public
1209  * key associated with the private key 'd'.
1210  *
1211  * @param priv original private key
1212  * @param label label to use for key deriviation
1213  * @param context additional context to use for HKDF of 'h';
1214  *        typically the name of the subsystem/application
1215  * @return derived private key
1216  */
1217 struct GNUNET_CRYPTO_EcdsaPrivateKey *
1218 GNUNET_CRYPTO_ecdsa_private_key_derive (const struct GNUNET_CRYPTO_EcdsaPrivateKey *priv,
1219                                         const char *label,
1220                                         const char *context);
1221
1222
1223 /**
1224  * @ingroup crypto
1225  * Derive a public key from a given public key and a label.
1226  * Essentially calculates a public key 'V = H(l,P) * P'.
1227  *
1228  * @param pub original public key
1229  * @param label label to use for key deriviation
1230  * @param context additional context to use for HKDF of 'h'.
1231  *        typically the name of the subsystem/application
1232  * @param result where to write the derived public key
1233  */
1234 void
1235 GNUNET_CRYPTO_ecdsa_public_key_derive (const struct GNUNET_CRYPTO_EcdsaPublicKey *pub,
1236                                        const char *label,
1237                                        const char *context,
1238                                        struct GNUNET_CRYPTO_EcdsaPublicKey *result);
1239
1240
1241 #if 0                           /* keep Emacsens' auto-indent happy */
1242 {
1243 #endif
1244 #ifdef __cplusplus
1245 }
1246 #endif
1247
1248
1249 /* ifndef GNUNET_CRYPTO_LIB_H */
1250 #endif
1251 /* end of gnunet_crypto_lib.h */