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