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