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