src/include/gnunet_crypto_lib.h

   1 /*
   2      This file is part of GNUnet.
   3      Copyright (C) 2001-2013 GNUnet e.V.
   4
   5      GNUnet is free software: you can redistribute it and/or modify it
   6      under the terms of the GNU Affero General Public License as published
   7      by the Free Software Foundation, either version 3 of the License,
   8      or (at your 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      Affero General Public License for more details.
  14
  15      You should have received a copy of the GNU Affero General Public License
  16      along with this program.  If not, see <http://www.gnu.org/licenses/>.
  17
  18      SPDX-License-Identifier: AGPL3.0-or-later
  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  * @author Jeffrey Burdges <burdges@gnunet.org>
  31  *
  32  * @defgroup crypto  Crypto library: cryptographic operations
  33  * Provides cryptographic primitives.
  34  *
  35  * @see [Documentation](https://gnunet.org/crypto-api)
  36  *
  37  * @defgroup hash  Crypto library: hash operations
  38  * Provides hashing and operations on hashes.
  39  *
  40  * @see [Documentation](https://gnunet.org/crypto-api)
  41  */
  42
  43 #ifndef GNUNET_CRYPTO_LIB_H
  44 #define GNUNET_CRYPTO_LIB_H
  45
  46 #ifdef __cplusplus
  47 extern "C" {
  48 #if 0 /* keep Emacsens' auto-indent happy */
  49 }
  50 #endif
  51 #endif
  52
  53
  54 /**
  55  * The identity of the host (wraps the signing key of the peer).
  56  */
  57 struct GNUNET_PeerIdentity;
  58
  59 #include "gnunet_common.h"
  60 #include <gcrypt.h>
  61
  62
  63 /**
  64  * Maximum length of an ECC signature.
  65  * Note: round up to multiple of 8 minus 2 for alignment.
  66  */
  67 #define GNUNET_CRYPTO_ECC_SIGNATURE_DATA_ENCODING_LENGTH 126
  68
  69
  70 /**
  71  * Desired quality level for random numbers.
  72  * @ingroup crypto
  73  */
  74 enum GNUNET_CRYPTO_Quality
  75 {
  76   /**
  77    * No good quality of the operation is needed (i.e.,
  78    * random numbers can be pseudo-random).
  79    * @ingroup crypto
  80    */
  81   GNUNET_CRYPTO_QUALITY_WEAK,
  82
  83   /**
  84    * High-quality operations are desired.
  85    * @ingroup crypto
  86    */
  87   GNUNET_CRYPTO_QUALITY_STRONG,
  88
  89   /**
  90    * Randomness for IVs etc. is required.
  91    * @ingroup crypto
  92    */
  93   GNUNET_CRYPTO_QUALITY_NONCE
  94 };
  95
  96
  97 /**
  98  * @brief length of the sessionkey in bytes (256 BIT sessionkey)
  99  */
 100 #define GNUNET_CRYPTO_AES_KEY_LENGTH (256 / 8)
 101
 102 /**
 103  * Length of a hash value
 104  */
 105 #define GNUNET_CRYPTO_HASH_LENGTH (512 / 8)
 106
 107 /**
 108  * How many characters (without 0-terminator) are our ASCII-encoded
 109  * public keys (ECDSA/EDDSA/ECDHE).
 110  */
 111 #define GNUNET_CRYPTO_PKEY_ASCII_LENGTH 52
 112
 113 /**
 114  * @brief 0-terminated ASCII encoding of a struct GNUNET_HashCode.
 115  */
 116 struct GNUNET_CRYPTO_HashAsciiEncoded
 117 {
 118   unsigned char encoding[104];
 119 };
 120
 121
 122 GNUNET_NETWORK_STRUCT_BEGIN
 123
 124
 125 /**
 126  * @brief header of what an ECC signature signs
 127  *        this must be followed by "size - 8" bytes of
 128  *        the actual signed data
 129  */
 130 struct GNUNET_CRYPTO_EccSignaturePurpose
 131 {
 132   /**
 133    * How many bytes does this signature sign?
 134    * (including this purpose header); in network
 135    * byte order (!).
 136    */
 137   uint32_t size GNUNET_PACKED;
 138
 139   /**
 140    * What does this signature vouch for?  This
 141    * must contain a GNUNET_SIGNATURE_PURPOSE_XXX
 142    * constant (from gnunet_signatures.h).  In
 143    * network byte order!
 144    */
 145   uint32_t purpose GNUNET_PACKED;
 146 };
 147
 148
 149 /**
 150  * @brief an ECC signature using EdDSA.
 151  * See cr.yp.to/papers.html#ed25519
 152  */
 153 struct GNUNET_CRYPTO_EddsaSignature
 154 {
 155   /**
 156    * R value.
 157    */
 158   unsigned char r[256 / 8];
 159
 160   /**
 161    * S value.
 162    */
 163   unsigned char s[256 / 8];
 164 };
 165
 166
 167 /**
 168  * @brief an ECC signature using ECDSA
 169  */
 170 struct GNUNET_CRYPTO_EcdsaSignature
 171 {
 172   /**
 173    * R value.
 174    */
 175   unsigned char r[256 / 8];
 176
 177   /**
 178    * S value.
 179    */
 180   unsigned char s[256 / 8];
 181 };
 182
 183
 184 /**
 185  * Public ECC key (always for curve Ed25519) encoded in a format
 186  * suitable for network transmission and EdDSA signatures.
 187  */
 188 struct GNUNET_CRYPTO_EddsaPublicKey
 189 {
 190   /**
 191    * Point Q consists of a y-value mod p (256 bits); the x-value is
 192    * always positive. The point is stored in Ed25519 standard
 193    * compact format.
 194    */
 195   unsigned char q_y[256 / 8];
 196 };
 197
 198
 199 /**
 200  * Public ECC key (always for Curve25519) encoded in a format suitable
 201  * for network transmission and ECDSA signatures.
 202  */
 203 struct GNUNET_CRYPTO_EcdsaPublicKey
 204 {
 205   /**
 206    * Q consists of an x- and a y-value, each mod p (256 bits), given
 207    * here in affine coordinates and Ed25519 standard compact format.
 208    */
 209   unsigned char q_y[256 / 8];
 210 };
 211
 212
 213 /**
 214  * The identity of the host (wraps the signing key of the peer).
 215  */
 216 struct GNUNET_PeerIdentity
 217 {
 218   struct GNUNET_CRYPTO_EddsaPublicKey public_key;
 219 };
 220
 221
 222 /**
 223  * Public ECC key (always for Curve25519) encoded in a format suitable
 224  * for network transmission and encryption (ECDH),
 225  * See http://cr.yp.to/ecdh.html
 226  */
 227 struct GNUNET_CRYPTO_EcdhePublicKey
 228 {
 229   /**
 230    * Q consists of an x- and a y-value, each mod p (256 bits), given
 231    * here in affine coordinates and Ed25519 standard compact format.
 232    */
 233   unsigned char q_y[256 / 8];
 234 };
 235
 236
 237 /**
 238  * Private ECC key encoded for transmission.  To be used only for ECDH
 239  * key exchange (ECDHE to be precise).
 240  */
 241 struct GNUNET_CRYPTO_EcdhePrivateKey
 242 {
 243   /**
 244    * d is a value mod n, where n has at most 256 bits.
 245    */
 246   unsigned char d[256 / 8];
 247 };
 248
 249 /**
 250  * Private ECC key encoded for transmission.  To be used only for ECDSA
 251  * signatures.
 252  */
 253 struct GNUNET_CRYPTO_EcdsaPrivateKey
 254 {
 255   /**
 256    * d is a value mod n, where n has at most 256 bits.
 257    */
 258   unsigned char d[256 / 8];
 259 };
 260
 261 /**
 262  * Private ECC key encoded for transmission.  To be used only for EdDSA
 263  * signatures.
 264  */
 265 struct GNUNET_CRYPTO_EddsaPrivateKey
 266 {
 267   /**
 268    * d is a value mod n, where n has at most 256 bits.
 269    */
 270   unsigned char d[256 / 8];
 271 };
 272
 273
 274 /**
 275  * @brief type for session keys
 276  */
 277 struct GNUNET_CRYPTO_SymmetricSessionKey
 278 {
 279   /**
 280    * Actual key for AES.
 281    */
 282   unsigned char aes_key[GNUNET_CRYPTO_AES_KEY_LENGTH];
 283
 284   /**
 285    * Actual key for TwoFish.
 286    */
 287   unsigned char twofish_key[GNUNET_CRYPTO_AES_KEY_LENGTH];
 288 };
 289
 290 GNUNET_NETWORK_STRUCT_END
 291
 292 /**
 293  * @brief IV for sym cipher
 294  *
 295  * NOTE: must be smaller (!) in size than the
 296  * `struct GNUNET_HashCode`.
 297  */
 298 struct GNUNET_CRYPTO_SymmetricInitializationVector
 299 {
 300   unsigned char aes_iv[GNUNET_CRYPTO_AES_KEY_LENGTH / 2];
 301
 302   unsigned char twofish_iv[GNUNET_CRYPTO_AES_KEY_LENGTH / 2];
 303 };
 304
 305
 306 /**
 307  * @brief type for (message) authentication keys
 308  */
 309 struct GNUNET_CRYPTO_AuthKey
 310 {
 311   unsigned char key[GNUNET_CRYPTO_HASH_LENGTH];
 312 };
 313
 314
 315 /**
 316  * Size of paillier plain texts and public keys.
 317  * Private keys and ciphertexts are twice this size.
 318  */
 319 #define GNUNET_CRYPTO_PAILLIER_BITS 2048
 320
 321
 322 /**
 323  * Paillier public key.
 324  */
 325 struct GNUNET_CRYPTO_PaillierPublicKey
 326 {
 327   /**
 328    * N value.
 329    */
 330   unsigned char n[GNUNET_CRYPTO_PAILLIER_BITS / 8];
 331 };
 332
 333
 334 /**
 335  * Paillier private key.
 336  */
 337 struct GNUNET_CRYPTO_PaillierPrivateKey
 338 {
 339   /**
 340    * Lambda-component of the private key.
 341    */
 342   unsigned char lambda[GNUNET_CRYPTO_PAILLIER_BITS / 8];
 343   /**
 344    * Mu-component of the private key.
 345    */
 346   unsigned char mu[GNUNET_CRYPTO_PAILLIER_BITS / 8];
 347 };
 348
 349
 350 /**
 351  * Paillier ciphertext.
 352  */
 353 struct GNUNET_CRYPTO_PaillierCiphertext
 354 {
 355   /**
 356    * Guaranteed minimum number of homomorphic operations with this ciphertext,
 357    * in network byte order (NBO).
 358    */
 359   int32_t remaining_ops GNUNET_PACKED;
 360
 361   /**
 362    * The bits of the ciphertext.
 363    */
 364   unsigned char bits[GNUNET_CRYPTO_PAILLIER_BITS * 2 / 8];
 365 };
 366
 367
 368 /* **************** Functions and Macros ************* */
 369
 370 /**
 371  * @ingroup crypto
 372  * Seed a weak random generator. Only #GNUNET_CRYPTO_QUALITY_WEAK-mode generator
 373  * can be seeded.
 374  *
 375  * @param seed the seed to use
 376  */
 377 void
 378 GNUNET_CRYPTO_seed_weak_random (int32_t seed);
 379
 380
 381 /**
 382  * @ingroup hash
 383  * Calculate the checksum of a buffer in one step.
 384  *
 385  * @param buf buffer to calculate CRC over
 386  * @param len number of bytes in @a buf
 387  * @return crc8 value
 388  */
 389 uint8_t
 390 GNUNET_CRYPTO_crc8_n (const void *buf, size_t len);
 391
 392
 393 /**
 394  * Perform an incremental step in a CRC16 (for TCP/IP) calculation.
 395  *
 396  * @param sum current sum, initially 0
 397  * @param buf buffer to calculate CRC over (must be 16-bit aligned)
 398  * @param len number of bytes in @a buf, must be multiple of 2
 399  * @return updated crc sum (must be subjected to #GNUNET_CRYPTO_crc16_finish to get actual crc16)
 400  */
 401 uint32_t
 402 GNUNET_CRYPTO_crc16_step (uint32_t sum, const void *buf, size_t len);
 403
 404
 405 /**
 406  * Convert results from GNUNET_CRYPTO_crc16_step to final crc16.
 407  *
 408  * @param sum cummulative sum
 409  * @return crc16 value
 410  */
 411 uint16_t
 412 GNUNET_CRYPTO_crc16_finish (uint32_t sum);
 413
 414
 415 /**
 416  * @ingroup hash
 417  * Calculate the checksum of a buffer in one step.
 418  *
 419  * @param buf buffer to calculate CRC over (must be 16-bit aligned)
 420  * @param len number of bytes in @a buf, must be multiple of 2
 421  * @return crc16 value
 422  */
 423 uint16_t
 424 GNUNET_CRYPTO_crc16_n (const void *buf, size_t len);
 425
 426
 427 /**
 428  * @ingroup hash
 429  * Compute the CRC32 checksum for the first len
 430  * bytes of the buffer.
 431  *
 432  * @param buf the data over which we're taking the CRC
 433  * @param len the length of the buffer @a buf in bytes
 434  * @return the resulting CRC32 checksum
 435  */
 436 int32_t
 437 GNUNET_CRYPTO_crc32_n (const void *buf, size_t len);
 438
 439 /**
 440  * @ingroup crypto
 441  * Zero out @a buffer, securely against compiler optimizations.
 442  * Used to delete key material.
 443  *
 444  * @param buffer the buffer to zap
 445  * @param length buffer length
 446  */
 447 void
 448 GNUNET_CRYPTO_zero_keys (void *buffer, size_t length);
 449
 450
 451 /**
 452  * @ingroup crypto
 453  * Fill block with a random values.
 454  *
 455  * @param mode desired quality of the random number
 456  * @param buffer the buffer to fill
 457  * @param length buffer length
 458  */
 459 void
 460 GNUNET_CRYPTO_random_block (enum GNUNET_CRYPTO_Quality mode,
 461                             void *buffer,
 462                             size_t length);
 463
 464 /**
 465  * @ingroup crypto
 466  * Produce a random value.
 467  *
 468  * @param mode desired quality of the random number
 469  * @param i the upper limit (exclusive) for the random number
 470  * @return a random value in the interval [0,@a i) (exclusive).
 471  */
 472 uint32_t
 473 GNUNET_CRYPTO_random_u32 (enum GNUNET_CRYPTO_Quality mode, uint32_t i);
 474
 475
 476 /**
 477  * @ingroup crypto
 478  * Random on unsigned 64-bit values.
 479  *
 480  * @param mode desired quality of the random number
 481  * @param max value returned will be in range [0,@a max) (exclusive)
 482  * @return random 64-bit number
 483  */
 484 uint64_t
 485 GNUNET_CRYPTO_random_u64 (enum GNUNET_CRYPTO_Quality mode, uint64_t max);
 486
 487
 488 /**
 489  * @ingroup crypto
 490  * Get an array with a random permutation of the
 491  * numbers 0...n-1.
 492  * @param mode #GNUNET_CRYPTO_QUALITY_STRONG if the strong (but expensive) PRNG should be used,
 493  *             #GNUNET_CRYPTO_QUALITY_WEAK or #GNUNET_CRYPTO_QUALITY_NONCE otherwise
 494  * @param n the size of the array
 495  * @return the permutation array (allocated from heap)
 496  */
 497 unsigned int *
 498 GNUNET_CRYPTO_random_permute (enum GNUNET_CRYPTO_Quality mode, unsigned int n);
 499
 500
 501 /**
 502  * @ingroup crypto
 503  * Create a new random session key.
 504  *
 505  * @param key key to initialize
 506  */
 507 void
 508 GNUNET_CRYPTO_symmetric_create_session_key (
 509   struct GNUNET_CRYPTO_SymmetricSessionKey *key);
 510
 511
 512 /**
 513  * @ingroup crypto
 514  * Encrypt a block using a symmetric sessionkey.
 515  *
 516  * @param block the block to encrypt
 517  * @param size the size of the @a block
 518  * @param sessionkey the key used to encrypt
 519  * @param iv the initialization vector to use, use INITVALUE
 520  *        for streams.
 521  * @return the size of the encrypted block, -1 for errors
 522  */
 523 ssize_t
 524 GNUNET_CRYPTO_symmetric_encrypt (
 525   const void *block,
 526   size_t size,
 527   const struct GNUNET_CRYPTO_SymmetricSessionKey *sessionkey,
 528   const struct GNUNET_CRYPTO_SymmetricInitializationVector *iv,
 529   void *result);
 530
 531
 532 /**
 533  * @ingroup crypto
 534  * Decrypt a given block using a symmetric sessionkey.
 535  *
 536  * @param block the data to decrypt, encoded as returned by encrypt
 537  * @param size how big is the block?
 538  * @param sessionkey the key used to decrypt
 539  * @param iv the initialization vector to use
 540  * @param result address to store the result at
 541  * @return -1 on failure, size of decrypted block on success
 542  */
 543 ssize_t
 544 GNUNET_CRYPTO_symmetric_decrypt (
 545   const void *block,
 546   size_t size,
 547   const struct GNUNET_CRYPTO_SymmetricSessionKey *sessionkey,
 548   const struct GNUNET_CRYPTO_SymmetricInitializationVector *iv,
 549   void *result);
 550
 551
 552 /**
 553  * @ingroup crypto
 554  * @brief Derive an IV
 555  * @param iv initialization vector
 556  * @param skey session key
 557  * @param salt salt for the derivation
 558  * @param salt_len size of the @a salt
 559  * @param ... pairs of void * & size_t for context chunks, terminated by NULL
 560  */
 561 void
 562 GNUNET_CRYPTO_symmetric_derive_iv (
 563   struct GNUNET_CRYPTO_SymmetricInitializationVector *iv,
 564   const struct GNUNET_CRYPTO_SymmetricSessionKey *skey,
 565   const void *salt,
 566   size_t salt_len,
 567   ...);
 568
 569
 570 /**
 571  * @brief Derive an IV
 572  * @param iv initialization vector
 573  * @param skey session key
 574  * @param salt salt for the derivation
 575  * @param salt_len size of the @a salt
 576  * @param argp pairs of void * & size_t for context chunks, terminated by NULL
 577  */
 578 void
 579 GNUNET_CRYPTO_symmetric_derive_iv_v (
 580   struct GNUNET_CRYPTO_SymmetricInitializationVector *iv,
 581   const struct GNUNET_CRYPTO_SymmetricSessionKey *skey,
 582   const void *salt,
 583   size_t salt_len,
 584   va_list argp);
 585
 586
 587 /**
 588  * @ingroup hash
 589  * Convert hash to ASCII encoding.
 590  * @param block the hash code
 591  * @param result where to store the encoding (struct GNUNET_CRYPTO_HashAsciiEncoded can be
 592  *  safely cast to char*, a '\\0' termination is set).
 593  */
 594 void
 595 GNUNET_CRYPTO_hash_to_enc (const struct GNUNET_HashCode *block,
 596                            struct GNUNET_CRYPTO_HashAsciiEncoded *result);
 597
 598
 599 /**
 600  * @ingroup hash
 601  * Convert ASCII encoding back to a 'struct GNUNET_HashCode'
 602  *
 603  * @param enc the encoding
 604  * @param enclen number of characters in @a enc (without 0-terminator, which can be missing)
 605  * @param result where to store the hash code
 606  * @return #GNUNET_OK on success, #GNUNET_SYSERR if result has the wrong encoding
 607  */
 608 int
 609 GNUNET_CRYPTO_hash_from_string2 (const char *enc,
 610                                  size_t enclen,
 611                                  struct GNUNET_HashCode *result);
 612
 613
 614 /**
 615  * @ingroup hash
 616  * Convert ASCII encoding back to `struct GNUNET_HashCode`
 617  *
 618  * @param enc the encoding
 619  * @param result where to store the hash code
 620  * @return #GNUNET_OK on success, #GNUNET_SYSERR if result has the wrong encoding
 621  */
 622 #define GNUNET_CRYPTO_hash_from_string(enc, result) \
 623   GNUNET_CRYPTO_hash_from_string2 (enc, strlen (enc), result)
 624
 625
 626 /**
 627  * @ingroup hash
 628  *
 629  * Compute the distance between 2 hashcodes.  The
 630  * computation must be fast, not involve @a a[0] or @a a[4] (they're used
 631  * elsewhere), and be somewhat consistent. And of course, the result
 632  * should be a positive number.
 633  *
 634  * @param a some hash code
 635  * @param b some hash code
 636  * @return number between 0 and UINT32_MAX
 637  */
 638 uint32_t
 639 GNUNET_CRYPTO_hash_distance_u32 (const struct GNUNET_HashCode *a,
 640                                  const struct GNUNET_HashCode *b);
 641
 642
 643 /**
 644  * @ingroup hash
 645  * Compute hash of a given block.
 646  *
 647  * @param block the data to hash
 648  * @param size size of the @a block
 649  * @param ret pointer to where to write the hashcode
 650  */
 651 void
 652 GNUNET_CRYPTO_hash (const void *block,
 653                     size_t size,
 654                     struct GNUNET_HashCode *ret);
 655
 656
 657 /**
 658  * Calculate the 'proof-of-work' hash (an expensive hash).
 659  *
 660  * @param buf data to hash
 661  * @param buf_len number of bytes in @a buf
 662  * @param result where to write the resulting hash
 663  */
 664 void
 665 GNUNET_CRYPTO_pow_hash (const void *buf,
 666                         size_t buf_len,
 667                         struct GNUNET_HashCode *result);
 668
 669
 670 /**
 671  * Context for cummulative hashing.
 672  */
 673 struct GNUNET_HashContext;
 674
 675
 676 /**
 677  * Start incremental hashing operation.
 678  *
 679  * @return context for incremental hash computation
 680  */
 681 struct GNUNET_HashContext *
 682 GNUNET_CRYPTO_hash_context_start (void);
 683
 684
 685 /**
 686  * Add data to be hashed.
 687  *
 688  * @param hc cummulative hash context
 689  * @param buf data to add
 690  * @param size number of bytes in @a buf
 691  */
 692 void
 693 GNUNET_CRYPTO_hash_context_read (struct GNUNET_HashContext *hc,
 694                                  const void *buf,
 695                                  size_t size);
 696
 697
 698 /**
 699  * Finish the hash computation.
 700  *
 701  * @param hc hash context to use, is freed in the process
 702  * @param r_hash where to write the latest / final hash code
 703  */
 704 void
 705 GNUNET_CRYPTO_hash_context_finish (struct GNUNET_HashContext *hc,
 706                                    struct GNUNET_HashCode *r_hash);
 707
 708
 709 /**
 710  * Abort hashing, do not bother calculating final result.
 711  *
 712  * @param hc hash context to destroy
 713  */
 714 void
 715 GNUNET_CRYPTO_hash_context_abort (struct GNUNET_HashContext *hc);
 716
 717
 718 /**
 719  * Calculate HMAC of a message (RFC 2104)
 720  * TODO: Shouldn' this be the standard hmac function and
 721  * the above be renamed?
 722  *
 723  * @param key secret key
 724  * @param key_len secret key length
 725  * @param plaintext input plaintext
 726  * @param plaintext_len length of @a plaintext
 727  * @param hmac where to store the hmac
 728  */
 729 void
 730 GNUNET_CRYPTO_hmac_raw (const void *key,
 731                         size_t key_len,
 732                         const void *plaintext,
 733                         size_t plaintext_len,
 734                         struct GNUNET_HashCode *hmac);
 735
 736
 737 /**
 738  * @ingroup hash
 739  * Calculate HMAC of a message (RFC 2104)
 740  *
 741  * @param key secret key
 742  * @param plaintext input plaintext
 743  * @param plaintext_len length of @a plaintext
 744  * @param hmac where to store the hmac
 745  */
 746 void
 747 GNUNET_CRYPTO_hmac (const struct GNUNET_CRYPTO_AuthKey *key,
 748                     const void *plaintext,
 749                     size_t plaintext_len,
 750                     struct GNUNET_HashCode *hmac);
 751
 752
 753 /**
 754  * Function called once the hash computation over the
 755  * specified file has completed.
 756  *
 757  * @param cls closure
 758  * @param res resulting hash, NULL on error
 759  */
 760 typedef void (*GNUNET_CRYPTO_HashCompletedCallback) (
 761   void *cls,
 762   const struct GNUNET_HashCode *res);
 763
 764
 765 /**
 766  * Handle to file hashing operation.
 767  */
 768 struct GNUNET_CRYPTO_FileHashContext;
 769
 770
 771 /**
 772  * @ingroup hash
 773  * Compute the hash of an entire file.
 774  *
 775  * @param priority scheduling priority to use
 776  * @param filename name of file to hash
 777  * @param blocksize number of bytes to process in one task
 778  * @param callback function to call upon completion
 779  * @param callback_cls closure for @a callback
 780  * @return NULL on (immediate) errror
 781  */
 782 struct GNUNET_CRYPTO_FileHashContext *
 783 GNUNET_CRYPTO_hash_file (enum GNUNET_SCHEDULER_Priority priority,
 784                          const char *filename,
 785                          size_t blocksize,
 786                          GNUNET_CRYPTO_HashCompletedCallback callback,
 787                          void *callback_cls);
 788
 789
 790 /**
 791  * Cancel a file hashing operation.
 792  *
 793  * @param fhc operation to cancel (callback must not yet have been invoked)
 794  */
 795 void
 796 GNUNET_CRYPTO_hash_file_cancel (struct GNUNET_CRYPTO_FileHashContext *fhc);
 797
 798
 799 /**
 800  * @ingroup hash
 801  * Create a random hash code.
 802  *
 803  * @param mode desired quality level
 804  * @param result hash code that is randomized
 805  */
 806 void
 807 GNUNET_CRYPTO_hash_create_random (enum GNUNET_CRYPTO_Quality mode,
 808                                   struct GNUNET_HashCode *result);
 809
 810
 811 /**
 812  * @ingroup hash
 813  * compute @a result = @a b - @a a
 814  *
 815  * @param a some hash code
 816  * @param b some hash code
 817  * @param result set to @a b - @a a
 818  */
 819 void
 820 GNUNET_CRYPTO_hash_difference (const struct GNUNET_HashCode *a,
 821                                const struct GNUNET_HashCode *b,
 822                                struct GNUNET_HashCode *result);
 823
 824
 825 /**
 826  * @ingroup hash
 827  * compute @a result = @a a + @a delta
 828  *
 829  * @param a some hash code
 830  * @param delta some hash code
 831  * @param result set to @a a + @a delta
 832  */
 833 void
 834 GNUNET_CRYPTO_hash_sum (const struct GNUNET_HashCode *a,
 835                         const struct GNUNET_HashCode *delta,
 836                         struct GNUNET_HashCode *result);
 837
 838
 839 /**
 840  * @ingroup hash
 841  * compute result = a ^ b
 842  *
 843  * @param a some hash code
 844  * @param b some hash code
 845  * @param result set to @a a ^ @a b
 846  */
 847 void
 848 GNUNET_CRYPTO_hash_xor (const struct GNUNET_HashCode *a,
 849                         const struct GNUNET_HashCode *b,
 850                         struct GNUNET_HashCode *result);
 851
 852
 853 /**
 854  * @ingroup hash
 855  * Convert a hashcode into a key.
 856  *
 857  * @param hc hash code that serves to generate the key
 858  * @param skey set to a valid session key
 859  * @param iv set to a valid initialization vector
 860  */
 861 void
 862 GNUNET_CRYPTO_hash_to_aes_key (
 863   const struct GNUNET_HashCode *hc,
 864   struct GNUNET_CRYPTO_SymmetricSessionKey *skey,
 865   struct GNUNET_CRYPTO_SymmetricInitializationVector *iv);
 866
 867
 868 /**
 869  * @ingroup hash
 870  * Obtain a bit from a hashcode.
 871  *
 872  * @param code the `struct GNUNET_HashCode` to index bit-wise
 873  * @param bit index into the hashcode, [0...159]
 874  * @return Bit \a bit from hashcode \a code, -1 for invalid index
 875  */
 876 int
 877 GNUNET_CRYPTO_hash_get_bit (const struct GNUNET_HashCode *code,
 878                             unsigned int bit);
 879
 880
 881 /**
 882  * @ingroup hash
 883  * Determine how many low order bits match in two
 884  * `struct GNUNET_HashCodes`.  i.e. - 010011 and 011111 share
 885  * the first two lowest order bits, and therefore the
 886  * return value is two (NOT XOR distance, nor how many
 887  * bits match absolutely!).
 888  *
 889  * @param first the first hashcode
 890  * @param second the hashcode to compare first to
 891  * @return the number of bits that match
 892  */
 893 unsigned int
 894 GNUNET_CRYPTO_hash_matching_bits (const struct GNUNET_HashCode *first,
 895                                   const struct GNUNET_HashCode *second);
 896
 897
 898 /**
 899  * @ingroup hash
 900  * Compare function for HashCodes, producing a total ordering
 901  * of all hashcodes.
 902  *
 903  * @param h1 some hash code
 904  * @param h2 some hash code
 905  * @return 1 if @a h1 > @a h2, -1 if @a h1 < @a h2 and 0 if @a h1 == @a h2.
 906  */
 907 int
 908 GNUNET_CRYPTO_hash_cmp (const struct GNUNET_HashCode *h1,
 909                         const struct GNUNET_HashCode *h2);
 910
 911
 912 /**
 913  * @ingroup hash
 914  * Find out which of the two GNUNET_CRYPTO_hash codes is closer to target
 915  * in the XOR metric (Kademlia).
 916  *
 917  * @param h1 some hash code
 918  * @param h2 some hash code
 919  * @param target some hash code
 920  * @return -1 if @a h1 is closer, 1 if @a h2 is closer and 0 if @a h1== @a h2.
 921  */
 922 int
 923 GNUNET_CRYPTO_hash_xorcmp (const struct GNUNET_HashCode *h1,
 924                            const struct GNUNET_HashCode *h2,
 925                            const struct GNUNET_HashCode *target);
 926
 927
 928 /**
 929  * @ingroup hash
 930  * @brief Derive an authentication key
 931  * @param key authentication key
 932  * @param rkey root key
 933  * @param salt salt
 934  * @param salt_len size of the salt
 935  * @param argp pair of void * & size_t for context chunks, terminated by NULL
 936  */
 937 void
 938 GNUNET_CRYPTO_hmac_derive_key_v (
 939   struct GNUNET_CRYPTO_AuthKey *key,
 940   const struct GNUNET_CRYPTO_SymmetricSessionKey *rkey,
 941   const void *salt,
 942   size_t salt_len,
 943   va_list argp);
 944
 945
 946 /**
 947  * @ingroup hash
 948  * @brief Derive an authentication key
 949  * @param key authentication key
 950  * @param rkey root key
 951  * @param salt salt
 952  * @param salt_len size of the salt
 953  * @param ... pair of void * & size_t for context chunks, terminated by NULL
 954  */
 955 void
 956 GNUNET_CRYPTO_hmac_derive_key (
 957   struct GNUNET_CRYPTO_AuthKey *key,
 958   const struct GNUNET_CRYPTO_SymmetricSessionKey *rkey,
 959   const void *salt,
 960   size_t salt_len,
 961   ...);
 962
 963
 964 /**
 965  * @ingroup hash
 966  * @brief Derive key
 967  * @param result buffer for the derived key, allocated by caller
 968  * @param out_len desired length of the derived key
 969  * @param xtr_algo hash algorithm for the extraction phase, GCRY_MD_...
 970  * @param prf_algo hash algorithm for the expansion phase, GCRY_MD_...
 971  * @param xts salt
 972  * @param xts_len length of @a xts
 973  * @param skm source key material
 974  * @param skm_len length of @a skm
 975  * @param ... pair of void * & size_t for context chunks, terminated by NULL
 976  * @return #GNUNET_YES on success
 977  */
 978 int
 979 GNUNET_CRYPTO_hkdf (void *result,
 980                     size_t out_len,
 981                     int xtr_algo,
 982                     int prf_algo,
 983                     const void *xts,
 984                     size_t xts_len,
 985                     const void *skm,
 986                     size_t skm_len,
 987                     ...);
 988
 989
 990 /**
 991  * @ingroup hash
 992  * @brief Derive key
 993  * @param result buffer for the derived key, allocated by caller
 994  * @param out_len desired length of the derived key
 995  * @param xtr_algo hash algorithm for the extraction phase, GCRY_MD_...
 996  * @param prf_algo hash algorithm for the expansion phase, GCRY_MD_...
 997  * @param xts salt
 998  * @param xts_len length of @a xts
 999  * @param skm source key material
1000  * @param skm_len length of @a skm
1001  * @param argp va_list of void * & size_t pairs for context chunks
1002  * @return #GNUNET_YES on success
1003  */
1004 int
1005 GNUNET_CRYPTO_hkdf_v (void *result,
1006                       size_t out_len,
1007                       int xtr_algo,
1008                       int prf_algo,
1009                       const void *xts,
1010                       size_t xts_len,
1011                       const void *skm,
1012                       size_t skm_len,
1013                       va_list argp);
1014
1015
1016 /**
1017  * @brief Derive key
1018  * @param result buffer for the derived key, allocated by caller
1019  * @param out_len desired length of the derived key
1020  * @param xts salt
1021  * @param xts_len length of @a xts
1022  * @param skm source key material
1023  * @param skm_len length of @a skm
1024  * @param argp va_list of void * & size_t pairs for context chunks
1025  * @return #GNUNET_YES on success
1026  */
1027 int
1028 GNUNET_CRYPTO_kdf_v (void *result,
1029                      size_t out_len,
1030                      const void *xts,
1031                      size_t xts_len,
1032                      const void *skm,
1033                      size_t skm_len,
1034                      va_list argp);
1035
1036
1037 /**
1038  * Deterministically generate a pseudo-random number uniformly from the
1039  * integers modulo a libgcrypt mpi.
1040  *
1041  * @param[out] r MPI value set to the FDH
1042  * @param n MPI to work modulo
1043  * @param xts salt
1044  * @param xts_len length of @a xts
1045  * @param skm source key material
1046  * @param skm_len length of @a skm
1047  * @param ctx context string
1048  */
1049 void
1050 GNUNET_CRYPTO_kdf_mod_mpi (gcry_mpi_t *r,
1051                            gcry_mpi_t n,
1052                            const void *xts,
1053                            size_t xts_len,
1054                            const void *skm,
1055                            size_t skm_len,
1056                            const char *ctx);
1057
1058
1059 /**
1060  * @ingroup hash
1061  * @brief Derive key
1062  * @param result buffer for the derived key, allocated by caller
1063  * @param out_len desired length of the derived key
1064  * @param xts salt
1065  * @param xts_len length of @a xts
1066  * @param skm source key material
1067  * @param skm_len length of @a skm
1068  * @param ... void * & size_t pairs for context chunks
1069  * @return #GNUNET_YES on success
1070  */
1071 int
1072 GNUNET_CRYPTO_kdf (void *result,
1073                    size_t out_len,
1074                    const void *xts,
1075                    size_t xts_len,
1076                    const void *skm,
1077                    size_t skm_len,
1078                    ...);
1079
1080
1081 /**
1082  * @ingroup crypto
1083  * Extract the public key for the given private key.
1084  *
1085  * @param priv the private key
1086  * @param pub where to write the public key
1087  */
1088 void
1089 GNUNET_CRYPTO_ecdsa_key_get_public (
1090   const struct GNUNET_CRYPTO_EcdsaPrivateKey *priv,
1091   struct GNUNET_CRYPTO_EcdsaPublicKey *pub);
1092
1093 /**
1094  * @ingroup crypto
1095  * Extract the public key for the given private key.
1096  *
1097  * @param priv the private key
1098  * @param pub where to write the public key
1099  */
1100 void
1101 GNUNET_CRYPTO_eddsa_key_get_public (
1102   const struct GNUNET_CRYPTO_EddsaPrivateKey *priv,
1103   struct GNUNET_CRYPTO_EddsaPublicKey *pub);
1104
1105
1106 /**
1107  * @ingroup crypto
1108  * Extract the public key for the given private key.
1109  *
1110  * @param priv the private key
1111  * @param pub where to write the public key
1112  */
1113 void
1114 GNUNET_CRYPTO_ecdhe_key_get_public (
1115   const struct GNUNET_CRYPTO_EcdhePrivateKey *priv,
1116   struct GNUNET_CRYPTO_EcdhePublicKey *pub);
1117
1118
1119 /**
1120  * Convert a public key to a string.
1121  *
1122  * @param pub key to convert
1123  * @return string representing @a pub
1124  */
1125 char *
1126 GNUNET_CRYPTO_ecdsa_public_key_to_string (
1127   const struct GNUNET_CRYPTO_EcdsaPublicKey *pub);
1128
1129 /**
1130  * Convert a private key to a string.
1131  *
1132  * @param priv key to convert
1133  * @return string representing @a priv
1134  */
1135 char *
1136 GNUNET_CRYPTO_ecdsa_private_key_to_string (
1137   const struct GNUNET_CRYPTO_EcdsaPrivateKey *priv);
1138
1139
1140 /**
1141  * Convert a private key to a string.
1142  *
1143  * @param priv key to convert
1144  * @return string representing @a pub
1145  */
1146 char *
1147 GNUNET_CRYPTO_eddsa_private_key_to_string (
1148   const struct GNUNET_CRYPTO_EddsaPrivateKey *priv);
1149
1150
1151 /**
1152  * Convert a public key to a string.
1153  *
1154  * @param pub key to convert
1155  * @return string representing @a pub
1156  */
1157 char *
1158 GNUNET_CRYPTO_eddsa_public_key_to_string (
1159   const struct GNUNET_CRYPTO_EddsaPublicKey *pub);
1160
1161
1162 /**
1163  * Convert a string representing a public key to a public key.
1164  *
1165  * @param enc encoded public key
1166  * @param enclen number of bytes in @a enc (without 0-terminator)
1167  * @param pub where to store the public key
1168  * @return #GNUNET_OK on success
1169  */
1170 int
1171 GNUNET_CRYPTO_ecdsa_public_key_from_string (
1172   const char *enc,
1173   size_t enclen,
1174   struct GNUNET_CRYPTO_EcdsaPublicKey *pub);
1175
1176
1177 /**
1178  * Convert a string representing a private key to a private key.
1179  *
1180  * @param enc encoded public key
1181  * @param enclen number of bytes in @a enc (without 0-terminator)
1182  * @param priv where to store the private key
1183  * @return #GNUNET_OK on success
1184  */
1185 int
1186 GNUNET_CRYPTO_eddsa_private_key_from_string (
1187   const char *enc,
1188   size_t enclen,
1189   struct GNUNET_CRYPTO_EddsaPrivateKey *pub);
1190
1191
1192 /**
1193  * Convert a string representing a public key to a public key.
1194  *
1195  * @param enc encoded public key
1196  * @param enclen number of bytes in @a enc (without 0-terminator)
1197  * @param pub where to store the public key
1198  * @return #GNUNET_OK on success
1199  */
1200 int
1201 GNUNET_CRYPTO_eddsa_public_key_from_string (
1202   const char *enc,
1203   size_t enclen,
1204   struct GNUNET_CRYPTO_EddsaPublicKey *pub);
1205
1206
1207 /**
1208  * @ingroup crypto
1209  * Create a new private key by reading it from a file.  If the
1210  * files does not exist, create a new key and write it to the
1211  * file.  Caller must free return value.  Note that this function
1212  * can not guarantee that another process might not be trying
1213  * the same operation on the same file at the same time.
1214  * If the contents of the file
1215  * are invalid the old file is deleted and a fresh key is
1216  * created.
1217  *
1218  * @param filename name of file to use to store the key
1219  * @return new private key, NULL on error (for example,
1220  *   permission denied); free using #GNUNET_free
1221  */
1222 struct GNUNET_CRYPTO_EcdsaPrivateKey *
1223 GNUNET_CRYPTO_ecdsa_key_create_from_file (const char *filename);
1224
1225
1226 /**
1227  * @ingroup crypto
1228  * Create a new private key by reading it from a file.  If the
1229  * files does not exist, create a new key and write it to the
1230  * file.  Caller must free return value.  Note that this function
1231  * can not guarantee that another process might not be trying
1232  * the same operation on the same file at the same time.
1233  * If the contents of the file
1234  * are invalid the old file is deleted and a fresh key is
1235  * created.
1236  *
1237  * @param filename name of file to use to store the key
1238  * @return new private key, NULL on error (for example,
1239  *   permission denied); free using #GNUNET_free
1240  */
1241 struct GNUNET_CRYPTO_EddsaPrivateKey *
1242 GNUNET_CRYPTO_eddsa_key_create_from_file (const char *filename);
1243
1244
1245 /**
1246  * Forward declaration to simplify #include-structure.
1247  */
1248 struct GNUNET_CONFIGURATION_Handle;
1249
1250
1251 /**
1252  * @ingroup crypto
1253  * Create a new private key by reading our peer's key from
1254  * the file specified in the configuration.
1255  *
1256  * @param cfg the configuration to use
1257  * @return new private key, NULL on error (for example,
1258  *   permission denied); free using #GNUNET_free
1259  */
1260 struct GNUNET_CRYPTO_EddsaPrivateKey *
1261 GNUNET_CRYPTO_eddsa_key_create_from_configuration (
1262   const struct GNUNET_CONFIGURATION_Handle *cfg);
1263
1264
1265 /**
1266  * @ingroup crypto
1267  * Create a new private key. Caller must free return value.
1268  *
1269  * @return fresh private key; free using #GNUNET_free
1270  */
1271 struct GNUNET_CRYPTO_EcdsaPrivateKey *
1272 GNUNET_CRYPTO_ecdsa_key_create (void);
1273
1274
1275 /**
1276  * @ingroup crypto
1277  * Create a new private key. Caller must free return value.
1278  *
1279  * @return fresh private key; free using #GNUNET_free
1280  */
1281 struct GNUNET_CRYPTO_EddsaPrivateKey *
1282 GNUNET_CRYPTO_eddsa_key_create (void);
1283
1284
1285 /**
1286  * @ingroup crypto
1287  * Create a new private key.  Clear with #GNUNET_CRYPTO_ecdhe_key_clear().
1288  *
1289  * @param[out] pk set to fresh private key;
1290  * @return #GNUNET_OK on success, #GNUNET_SYSERR on failure
1291  */
1292 int
1293 GNUNET_CRYPTO_ecdhe_key_create2 (struct GNUNET_CRYPTO_EcdhePrivateKey *pk);
1294
1295
1296 /**
1297  * @ingroup crypto
1298  * Create a new private key. Caller must free return value.
1299  *
1300  * @return fresh private key; free using #GNUNET_free
1301  */
1302 struct GNUNET_CRYPTO_EcdhePrivateKey *
1303 GNUNET_CRYPTO_ecdhe_key_create (void);
1304
1305
1306 /**
1307  * @ingroup crypto
1308  * Clear memory that was used to store a private key.
1309  *
1310  * @param pk location of the key
1311  */
1312 void
1313 GNUNET_CRYPTO_eddsa_key_clear (struct GNUNET_CRYPTO_EddsaPrivateKey *pk);
1314
1315
1316 /**
1317  * @ingroup crypto
1318  * Clear memory that was used to store a private key.
1319  *
1320  * @param pk location of the key
1321  */
1322 void
1323 GNUNET_CRYPTO_ecdsa_key_clear (struct GNUNET_CRYPTO_EcdsaPrivateKey *pk);
1324
1325
1326 /**
1327  * @ingroup crypto
1328  * Clear memory that was used to store a private key.
1329  *
1330  * @param pk location of the key
1331  */
1332 void
1333 GNUNET_CRYPTO_ecdhe_key_clear (struct GNUNET_CRYPTO_EcdhePrivateKey *pk);
1334
1335
1336 /**
1337  * @ingroup crypto
1338  * Get the shared private key we use for anonymous users.
1339  *
1340  * @return "anonymous" private key; do not free
1341  */
1342 const struct GNUNET_CRYPTO_EcdsaPrivateKey *
1343 GNUNET_CRYPTO_ecdsa_key_get_anonymous (void);
1344
1345
1346 /**
1347  * @ingroup crypto
1348  * Setup a hostkey file for a peer given the name of the
1349  * configuration file (!).  This function is used so that
1350  * at a later point code can be certain that reading a
1351  * hostkey is fast (for example in time-dependent testcases).
1352  *
1353  * @param cfg_name name of the configuration file to use
1354  */
1355 void
1356 GNUNET_CRYPTO_eddsa_setup_hostkey (const char *cfg_name);
1357
1358
1359 /**
1360  * @ingroup crypto
1361  * Retrieve the identity of the host's peer.
1362  *
1363  * @param cfg configuration to use
1364  * @param dst pointer to where to write the peer identity
1365  * @return #GNUNET_OK on success, #GNUNET_SYSERR if the identity
1366  *         could not be retrieved
1367  */
1368 int
1369 GNUNET_CRYPTO_get_peer_identity (const struct GNUNET_CONFIGURATION_Handle *cfg,
1370                                  struct GNUNET_PeerIdentity *dst);
1371
1372
1373 /**
1374  * Internal structure used to cache pre-calculated values for DLOG calculation.
1375  */
1376 struct GNUNET_CRYPTO_EccDlogContext;
1377
1378
1379 /**
1380  * Point on a curve (always for Curve25519) encoded in a format suitable
1381  * for network transmission (ECDH), see http://cr.yp.to/ecdh.html.
1382  */
1383 struct GNUNET_CRYPTO_EccPoint
1384 {
1385   /**
1386    * Q consists of an x- and a y-value, each mod p (256 bits), given
1387    * here in affine coordinates and Ed25519 standard compact format.
1388    */
1389   unsigned char q_y[256 / 8];
1390 };
1391
1392
1393 /**
1394  * Do pre-calculation for ECC discrete logarithm for small factors.
1395  *
1396  * @param max maximum value the factor can be
1397  * @param mem memory to use (should be smaller than @a max), must not be zero.
1398  * @return NULL on error
1399  */
1400 struct GNUNET_CRYPTO_EccDlogContext *
1401 GNUNET_CRYPTO_ecc_dlog_prepare (unsigned int max, unsigned int mem);
1402
1403
1404 /**
1405  * Calculate ECC discrete logarithm for small factors.
1406  * Opposite of #GNUNET_CRYPTO_ecc_dexp().
1407  *
1408  * @param dlc precalculated values, determine range of factors
1409  * @param input point on the curve to factor
1410  * @return INT_MAX if dlog failed, otherwise the factor
1411  */
1412 int
1413 GNUNET_CRYPTO_ecc_dlog (struct GNUNET_CRYPTO_EccDlogContext *edc,
1414                         gcry_mpi_point_t input);
1415
1416
1417 /**
1418  * Multiply the generator g of the elliptic curve by @a val
1419  * to obtain the point on the curve representing @a val.
1420  * Afterwards, point addition will correspond to integer
1421  * addition.  #GNUNET_CRYPTO_ecc_dlog() can be used to
1422  * convert a point back to an integer (as long as the
1423  * integer is smaller than the MAX of the @a edc context).
1424  *
1425  * @param edc calculation context for ECC operations
1426  * @param val value to encode into a point
1427  * @return representation of the value as an ECC point,
1428  *         must be freed using #GNUNET_CRYPTO_ecc_free()
1429  */
1430 gcry_mpi_point_t
1431 GNUNET_CRYPTO_ecc_dexp (struct GNUNET_CRYPTO_EccDlogContext *edc, int val);
1432
1433
1434 /**
1435  * Multiply the generator g of the elliptic curve by @a val
1436  * to obtain the point on the curve representing @a val.
1437  *
1438  * @param edc calculation context for ECC operations
1439  * @param val (positive) value to encode into a point
1440  * @return representation of the value as an ECC point,
1441  *         must be freed using #GNUNET_CRYPTO_ecc_free()
1442  */
1443 gcry_mpi_point_t
1444 GNUNET_CRYPTO_ecc_dexp_mpi (struct GNUNET_CRYPTO_EccDlogContext *edc,
1445                             gcry_mpi_t val);
1446
1447
1448 /**
1449  * Multiply the point @a p on the elliptic curve by @a val.
1450  *
1451  * @param edc calculation context for ECC operations
1452  * @param p point to multiply
1453  * @param val (positive) value to encode into a point
1454  * @return representation of the value as an ECC point,
1455  *         must be freed using #GNUNET_CRYPTO_ecc_free()
1456  */
1457 gcry_mpi_point_t
1458 GNUNET_CRYPTO_ecc_pmul_mpi (struct GNUNET_CRYPTO_EccDlogContext *edc,
1459                             gcry_mpi_point_t p,
1460                             gcry_mpi_t val);
1461
1462
1463 /**
1464  * Convert point value to binary representation.
1465  *
1466  * @param edc calculation context for ECC operations
1467  * @param point computational point representation
1468  * @param[out] bin binary point representation
1469  */
1470 void
1471 GNUNET_CRYPTO_ecc_point_to_bin (struct GNUNET_CRYPTO_EccDlogContext *edc,
1472                                 gcry_mpi_point_t point,
1473                                 struct GNUNET_CRYPTO_EccPoint *bin);
1474
1475
1476 /**
1477  * Convert binary representation of a point to computational representation.
1478  *
1479  * @param edc calculation context for ECC operations
1480  * @param bin binary point representation
1481  * @return computational representation
1482  */
1483 gcry_mpi_point_t
1484 GNUNET_CRYPTO_ecc_bin_to_point (struct GNUNET_CRYPTO_EccDlogContext *edc,
1485                                 const struct GNUNET_CRYPTO_EccPoint *bin);
1486
1487
1488 /**
1489  * Add two points on the elliptic curve.
1490  *
1491  * @param edc calculation context for ECC operations
1492  * @param a some value
1493  * @param b some value
1494  * @return @a a + @a b, must be freed using #GNUNET_CRYPTO_ecc_free()
1495  */
1496 gcry_mpi_point_t
1497 GNUNET_CRYPTO_ecc_add (struct GNUNET_CRYPTO_EccDlogContext *edc,
1498                        gcry_mpi_point_t a,
1499                        gcry_mpi_point_t b);
1500
1501
1502 /**
1503  * Obtain a random point on the curve and its
1504  * additive inverse. Both returned values
1505  * must be freed using #GNUNET_CRYPTO_ecc_free().
1506  *
1507  * @param edc calculation context for ECC operations
1508  * @param[out] r set to a random point on the curve
1509  * @param[out] r_inv set to the additive inverse of @a r
1510  */
1511 void
1512 GNUNET_CRYPTO_ecc_rnd (struct GNUNET_CRYPTO_EccDlogContext *edc,
1513                        gcry_mpi_point_t *r,
1514                        gcry_mpi_point_t *r_inv);
1515
1516
1517 /**
1518  * Obtain a random scalar for point multiplication on the curve and
1519  * its multiplicative inverse.
1520  *
1521  * @param edc calculation context for ECC operations
1522  * @param[out] r set to a random scalar on the curve
1523  * @param[out] r_inv set to the multiplicative inverse of @a r
1524  */
1525 void
1526 GNUNET_CRYPTO_ecc_rnd_mpi (struct GNUNET_CRYPTO_EccDlogContext *edc,
1527                            gcry_mpi_t *r,
1528                            gcry_mpi_t *r_inv);
1529
1530
1531 /**
1532  * Generate a random value mod n.
1533  *
1534  * @param edc ECC context
1535  * @return random value mod n.
1536  */
1537 gcry_mpi_t
1538 GNUNET_CRYPTO_ecc_random_mod_n (struct GNUNET_CRYPTO_EccDlogContext *edc);
1539
1540
1541 /**
1542  * Free a point value returned by the API.
1543  *
1544  * @param p point to free
1545  */
1546 void
1547 GNUNET_CRYPTO_ecc_free (gcry_mpi_point_t p);
1548
1549
1550 /**
1551  * Release precalculated values.
1552  *
1553  * @param dlc dlog context
1554  */
1555 void
1556 GNUNET_CRYPTO_ecc_dlog_release (struct GNUNET_CRYPTO_EccDlogContext *dlc);
1557
1558
1559 /**
1560  * @ingroup crypto
1561  * Derive key material from a public and a private ECC key.
1562  *
1563  * @param priv private key to use for the ECDH (x)
1564  * @param pub public key to use for the ECDH (yG)
1565  * @param key_material where to write the key material (xyG)
1566  * @return #GNUNET_SYSERR on error, #GNUNET_OK on success
1567  */
1568 int
1569 GNUNET_CRYPTO_ecc_ecdh (const struct GNUNET_CRYPTO_EcdhePrivateKey *priv,
1570                         const struct GNUNET_CRYPTO_EcdhePublicKey *pub,
1571                         struct GNUNET_HashCode *key_material);
1572
1573
1574 /**
1575  * @ingroup crypto
1576  * Derive key material from a ECDH public key and a private EdDSA key.
1577  * Dual to #GNUNET_CRRYPTO_ecdh_eddsa.
1578  *
1579  * @param priv private key from EdDSA to use for the ECDH (x)
1580  * @param pub public key to use for the ECDH (yG)
1581  * @param key_material where to write the key material H(h(x)yG)
1582  * @return #GNUNET_SYSERR on error, #GNUNET_OK on success
1583  */
1584 int
1585 GNUNET_CRYPTO_eddsa_ecdh (const struct GNUNET_CRYPTO_EddsaPrivateKey *priv,
1586                           const struct GNUNET_CRYPTO_EcdhePublicKey *pub,
1587                           struct GNUNET_HashCode *key_material);
1588
1589 /**
1590  * @ingroup crypto
1591  * Derive key material from a ECDH public key and a private ECDSA key.
1592  * Dual to #GNUNET_CRRYPTO_ecdh_ecdsa.
1593  *
1594  * @param priv private key from ECDSA to use for the ECDH (x)
1595  * @param pub public key to use for the ECDH (yG)
1596  * @param key_material where to write the key material H(h(x)yG)
1597  * @return #GNUNET_SYSERR on error, #GNUNET_OK on success
1598  */
1599 int
1600 GNUNET_CRYPTO_ecdsa_ecdh (const struct GNUNET_CRYPTO_EcdsaPrivateKey *priv,
1601                           const struct GNUNET_CRYPTO_EcdhePublicKey *pub,
1602                           struct GNUNET_HashCode *key_material);
1603
1604
1605 /**
1606  * @ingroup crypto
1607  * Derive key material from a EdDSA public key and a private ECDH key.
1608  * Dual to #GNUNET_CRRYPTO_eddsa_ecdh.
1609  *
1610  * @param priv private key to use for the ECDH (y)
1611  * @param pub public key from EdDSA to use for the ECDH (X=h(x)G)
1612  * @param key_material where to write the key material H(yX)=H(h(x)yG)
1613  * @return #GNUNET_SYSERR on error, #GNUNET_OK on success
1614  */
1615 int
1616 GNUNET_CRYPTO_ecdh_eddsa (const struct GNUNET_CRYPTO_EcdhePrivateKey *priv,
1617                           const struct GNUNET_CRYPTO_EddsaPublicKey *pub,
1618                           struct GNUNET_HashCode *key_material);
1619
1620 /**
1621  * @ingroup crypto
1622  * Derive key material from a EcDSA public key and a private ECDH key.
1623  * Dual to #GNUNET_CRRYPTO_ecdsa_ecdh.
1624  *
1625  * @param priv private key to use for the ECDH (y)
1626  * @param pub public key from ECDSA to use for the ECDH (X=h(x)G)
1627  * @param key_material where to write the key material H(yX)=H(h(x)yG)
1628  * @return #GNUNET_SYSERR on error, #GNUNET_OK on success
1629  */
1630 int
1631 GNUNET_CRYPTO_ecdh_ecdsa (const struct GNUNET_CRYPTO_EcdhePrivateKey *priv,
1632                           const struct GNUNET_CRYPTO_EcdsaPublicKey *pub,
1633                           struct GNUNET_HashCode *key_material);
1634
1635
1636 /**
1637  * @ingroup crypto
1638  * EdDSA sign a given block.
1639  *
1640  * @param priv private key to use for the signing
1641  * @param purpose what to sign (size, purpose)
1642  * @param sig where to write the signature
1643  * @return #GNUNET_SYSERR on error, #GNUNET_OK on success
1644  */
1645 int
1646 GNUNET_CRYPTO_eddsa_sign (
1647   const struct GNUNET_CRYPTO_EddsaPrivateKey *priv,
1648   const struct GNUNET_CRYPTO_EccSignaturePurpose *purpose,
1649   struct GNUNET_CRYPTO_EddsaSignature *sig);
1650
1651
1652 /**
1653  * @ingroup crypto
1654  * ECDSA Sign a given block.
1655  *
1656  * @param priv private key to use for the signing
1657  * @param purpose what to sign (size, purpose)
1658  * @param sig where to write the signature
1659  * @return #GNUNET_SYSERR on error, #GNUNET_OK on success
1660  */
1661 int
1662 GNUNET_CRYPTO_ecdsa_sign (
1663   const struct GNUNET_CRYPTO_EcdsaPrivateKey *priv,
1664   const struct GNUNET_CRYPTO_EccSignaturePurpose *purpose,
1665   struct GNUNET_CRYPTO_EcdsaSignature *sig);
1666
1667 /**
1668  * @ingroup crypto
1669  * Verify EdDSA signature.
1670  *
1671  * @param purpose what is the purpose that the signature should have?
1672  * @param validate block to validate (size, purpose, data)
1673  * @param sig signature that is being validated
1674  * @param pub public key of the signer
1675  * @returns #GNUNET_OK if ok, #GNUNET_SYSERR if invalid
1676  */
1677 int
1678 GNUNET_CRYPTO_eddsa_verify (
1679   uint32_t purpose,
1680   const struct GNUNET_CRYPTO_EccSignaturePurpose *validate,
1681   const struct GNUNET_CRYPTO_EddsaSignature *sig,
1682   const struct GNUNET_CRYPTO_EddsaPublicKey *pub);
1683
1684
1685 /**
1686  * @ingroup crypto
1687  * Verify ECDSA signature.
1688  *
1689  * @param purpose what is the purpose that the signature should have?
1690  * @param validate block to validate (size, purpose, data)
1691  * @param sig signature that is being validated
1692  * @param pub public key of the signer
1693  * @returns #GNUNET_OK if ok, #GNUNET_SYSERR if invalid
1694  */
1695 int
1696 GNUNET_CRYPTO_ecdsa_verify (
1697   uint32_t purpose,
1698   const struct GNUNET_CRYPTO_EccSignaturePurpose *validate,
1699   const struct GNUNET_CRYPTO_EcdsaSignature *sig,
1700   const struct GNUNET_CRYPTO_EcdsaPublicKey *pub);
1701
1702
1703 /**
1704  * @ingroup crypto
1705  * Derive a private key from a given private key and a label.
1706  * Essentially calculates a private key 'h = H(l,P) * d mod n'
1707  * where n is the size of the ECC group and P is the public
1708  * key associated with the private key 'd'.
1709  *
1710  * @param priv original private key
1711  * @param label label to use for key deriviation
1712  * @param context additional context to use for HKDF of 'h';
1713  *        typically the name of the subsystem/application
1714  * @return derived private key
1715  */
1716 struct GNUNET_CRYPTO_EcdsaPrivateKey *
1717 GNUNET_CRYPTO_ecdsa_private_key_derive (
1718   const struct GNUNET_CRYPTO_EcdsaPrivateKey *priv,
1719   const char *label,
1720   const char *context);
1721
1722
1723 /**
1724  * @ingroup crypto
1725  * Derive a public key from a given public key and a label.
1726  * Essentially calculates a public key 'V = H(l,P) * P'.
1727  *
1728  * @param pub original public key
1729  * @param label label to use for key deriviation
1730  * @param context additional context to use for HKDF of 'h'.
1731  *        typically the name of the subsystem/application
1732  * @param result where to write the derived public key
1733  */
1734 void
1735 GNUNET_CRYPTO_ecdsa_public_key_derive (
1736   const struct GNUNET_CRYPTO_EcdsaPublicKey *pub,
1737   const char *label,
1738   const char *context,
1739   struct GNUNET_CRYPTO_EcdsaPublicKey *result);
1740
1741
1742 /**
1743  * Output the given MPI value to the given buffer in network
1744  * byte order.  The MPI @a val may not be negative.
1745  *
1746  * @param buf where to output to
1747  * @param size number of bytes in @a buf
1748  * @param val value to write to @a buf
1749  */
1750 void
1751 GNUNET_CRYPTO_mpi_print_unsigned (void *buf, size_t size, gcry_mpi_t val);
1752
1753
1754 /**
1755  * Convert data buffer into MPI value.
1756  * The buffer is interpreted as network
1757  * byte order, unsigned integer.
1758  *
1759  * @param result where to store MPI value (allocated)
1760  * @param data raw data (GCRYMPI_FMT_USG)
1761  * @param size number of bytes in @a data
1762  */
1763 void
1764 GNUNET_CRYPTO_mpi_scan_unsigned (gcry_mpi_t *result,
1765                                  const void *data,
1766                                  size_t size);
1767
1768
1769 /**
1770  * Create a freshly generated paillier public key.
1771  *
1772  * @param[out] public_key Where to store the public key?
1773  * @param[out] private_key Where to store the private key?
1774  */
1775 void
1776 GNUNET_CRYPTO_paillier_create (
1777   struct GNUNET_CRYPTO_PaillierPublicKey *public_key,
1778   struct GNUNET_CRYPTO_PaillierPrivateKey *private_key);
1779
1780
1781 /**
1782  * Encrypt a plaintext with a paillier public key.
1783  *
1784  * @param public_key Public key to use.
1785  * @param m Plaintext to encrypt.
1786  * @param desired_ops How many homomorphic ops the caller intends to use
1787  * @param[out] ciphertext Encrytion of @a plaintext with @a public_key.
1788  * @return guaranteed number of supported homomorphic operations >= 1,
1789  *         or desired_ops, in case that is lower,
1790  *         or -1 if less than one homomorphic operation is possible
1791  */
1792 int
1793 GNUNET_CRYPTO_paillier_encrypt (
1794   const struct GNUNET_CRYPTO_PaillierPublicKey *public_key,
1795   const gcry_mpi_t m,
1796   int desired_ops,
1797   struct GNUNET_CRYPTO_PaillierCiphertext *ciphertext);
1798
1799
1800 /**
1801  * Decrypt a paillier ciphertext with a private key.
1802  *
1803  * @param private_key Private key to use for decryption.
1804  * @param public_key Public key to use for decryption.
1805  * @param ciphertext Ciphertext to decrypt.
1806  * @param[out] m Decryption of @a ciphertext with @private_key.
1807  */
1808 void
1809 GNUNET_CRYPTO_paillier_decrypt (
1810   const struct GNUNET_CRYPTO_PaillierPrivateKey *private_key,
1811   const struct GNUNET_CRYPTO_PaillierPublicKey *public_key,
1812   const struct GNUNET_CRYPTO_PaillierCiphertext *ciphertext,
1813   gcry_mpi_t m);
1814
1815
1816 /**
1817  * Compute a ciphertext that represents the sum of the plaintext in @a x1 and @a x2
1818  *
1819  * Note that this operation can only be done a finite number of times
1820  * before an overflow occurs.
1821  *
1822  * @param public_key Public key to use for encryption.
1823  * @param c1 Paillier cipher text.
1824  * @param c2 Paillier cipher text.
1825  * @param[out] result Result of the homomorphic operation.
1826  * @return #GNUNET_OK if the result could be computed,
1827  *         #GNUNET_SYSERR if no more homomorphic operations are remaining.
1828  */
1829 int
1830 GNUNET_CRYPTO_paillier_hom_add (
1831   const struct GNUNET_CRYPTO_PaillierPublicKey *public_key,
1832   const struct GNUNET_CRYPTO_PaillierCiphertext *c1,
1833   const struct GNUNET_CRYPTO_PaillierCiphertext *c2,
1834   struct GNUNET_CRYPTO_PaillierCiphertext *result);
1835
1836
1837 /**
1838  * Get the number of remaining supported homomorphic operations.
1839  *
1840  * @param c Paillier cipher text.
1841  * @return the number of remaining homomorphic operations
1842  */
1843 int
1844 GNUNET_CRYPTO_paillier_hom_get_remaining (
1845   const struct GNUNET_CRYPTO_PaillierCiphertext *c);
1846
1847
1848 /* ********* Chaum-style RSA-based blind signatures ******************* */
1849
1850
1851 /**
1852  * The private information of an RSA key pair.
1853  */
1854 struct GNUNET_CRYPTO_RsaPrivateKey;
1855
1856 /**
1857  * The public information of an RSA key pair.
1858  */
1859 struct GNUNET_CRYPTO_RsaPublicKey;
1860
1861 /**
1862  * Constant-size pre-secret for blinding key generation.
1863  */
1864 struct GNUNET_CRYPTO_RsaBlindingKeySecret
1865 {
1866   /**
1867    * Bits used to generate the blinding key.  256 bits
1868    * of entropy is enough.
1869    */
1870   uint32_t pre_secret[8] GNUNET_PACKED;
1871 };
1872
1873 /**
1874  * @brief an RSA signature
1875  */
1876 struct GNUNET_CRYPTO_RsaSignature;
1877
1878
1879 /**
1880  * Create a new private key. Caller must free return value.
1881  *
1882  * @param len length of the key in bits (i.e. 2048)
1883  * @return fresh private key
1884  */
1885 struct GNUNET_CRYPTO_RsaPrivateKey *
1886 GNUNET_CRYPTO_rsa_private_key_create (unsigned int len);
1887
1888
1889 /**
1890  * Free memory occupied by the private key.
1891  *
1892  * @param key pointer to the memory to free
1893  */
1894 void
1895 GNUNET_CRYPTO_rsa_private_key_free (struct GNUNET_CRYPTO_RsaPrivateKey *key);
1896
1897
1898 /**
1899  * Encode the private key in a format suitable for
1900  * storing it into a file.
1901  *
1902  * @param key the private key
1903  * @param[out] buffer set to a buffer with the encoded key
1904  * @return size of memory allocatedin @a buffer
1905  */
1906 size_t
1907 GNUNET_CRYPTO_rsa_private_key_encode (
1908   const struct GNUNET_CRYPTO_RsaPrivateKey *key,
1909   char **buffer);
1910
1911
1912 /**
1913  * Decode the private key from the data-format back
1914  * to the "normal", internal format.
1915  *
1916  * @param buf the buffer where the private key data is stored
1917  * @param len the length of the data in @a buf
1918  * @return NULL on error
1919  */
1920 struct GNUNET_CRYPTO_RsaPrivateKey *
1921 GNUNET_CRYPTO_rsa_private_key_decode (const char *buf, size_t len);
1922
1923
1924 /**
1925  * Duplicate the given private key
1926  *
1927  * @param key the private key to duplicate
1928  * @return the duplicate key; NULL upon error
1929  */
1930 struct GNUNET_CRYPTO_RsaPrivateKey *
1931 GNUNET_CRYPTO_rsa_private_key_dup (
1932   const struct GNUNET_CRYPTO_RsaPrivateKey *key);
1933
1934
1935 /**
1936  * Extract the public key of the given private key.
1937  *
1938  * @param priv the private key
1939  * @retur NULL on error, otherwise the public key
1940  */
1941 struct GNUNET_CRYPTO_RsaPublicKey *
1942 GNUNET_CRYPTO_rsa_private_key_get_public (
1943   const struct GNUNET_CRYPTO_RsaPrivateKey *priv);
1944
1945
1946 /**
1947  * Compute hash over the public key.
1948  *
1949  * @param key public key to hash
1950  * @param hc where to store the hash code
1951  */
1952 void
1953 GNUNET_CRYPTO_rsa_public_key_hash (const struct GNUNET_CRYPTO_RsaPublicKey *key,
1954                                    struct GNUNET_HashCode *hc);
1955
1956
1957 /**
1958  * Obtain the length of the RSA key in bits.
1959  *
1960  * @param key the public key to introspect
1961  * @return length of the key in bits
1962  */
1963 unsigned int
1964 GNUNET_CRYPTO_rsa_public_key_len (const struct GNUNET_CRYPTO_RsaPublicKey *key);
1965
1966
1967 /**
1968  * Free memory occupied by the public key.
1969  *
1970  * @param key pointer to the memory to free
1971  */
1972 void
1973 GNUNET_CRYPTO_rsa_public_key_free (struct GNUNET_CRYPTO_RsaPublicKey *key);
1974
1975
1976 /**
1977  * Encode the public key in a format suitable for
1978  * storing it into a file.
1979  *
1980  * @param key the private key
1981  * @param[out] buffer set to a buffer with the encoded key
1982  * @return size of memory allocated in @a buffer
1983  */
1984 size_t
1985 GNUNET_CRYPTO_rsa_public_key_encode (
1986   const struct GNUNET_CRYPTO_RsaPublicKey *key,
1987   char **buffer);
1988
1989
1990 /**
1991  * Decode the public key from the data-format back
1992  * to the "normal", internal format.
1993  *
1994  * @param buf the buffer where the public key data is stored
1995  * @param len the length of the data in @a buf
1996  * @return NULL on error
1997  */
1998 struct GNUNET_CRYPTO_RsaPublicKey *
1999 GNUNET_CRYPTO_rsa_public_key_decode (const char *buf, size_t len);
2000
2001
2002 /**
2003  * Duplicate the given public key
2004  *
2005  * @param key the public key to duplicate
2006  * @return the duplicate key; NULL upon error
2007  */
2008 struct GNUNET_CRYPTO_RsaPublicKey *
2009 GNUNET_CRYPTO_rsa_public_key_dup (const struct GNUNET_CRYPTO_RsaPublicKey *key);
2010
2011
2012 /**
2013  * Compare the values of two signatures.
2014  *
2015  * @param s1 one signature
2016  * @param s2 the other signature
2017  * @return 0 if the two are equal
2018  */
2019 int
2020 GNUNET_CRYPTO_rsa_signature_cmp (struct GNUNET_CRYPTO_RsaSignature *s1,
2021                                  struct GNUNET_CRYPTO_RsaSignature *s2);
2022
2023 /**
2024  * Compare the values of two private keys.
2025  *
2026  * @param p1 one private key
2027  * @param p2 the other private key
2028  * @return 0 if the two are equal
2029  */
2030 int
2031 GNUNET_CRYPTO_rsa_private_key_cmp (struct GNUNET_CRYPTO_RsaPrivateKey *p1,
2032                                    struct GNUNET_CRYPTO_RsaPrivateKey *p2);
2033
2034
2035 /**
2036  * Compare the values of two public keys.
2037  *
2038  * @param p1 one public key
2039  * @param p2 the other public key
2040  * @return 0 if the two are equal
2041  */
2042 int
2043 GNUNET_CRYPTO_rsa_public_key_cmp (struct GNUNET_CRYPTO_RsaPublicKey *p1,
2044                                   struct GNUNET_CRYPTO_RsaPublicKey *p2);
2045
2046
2047 /**
2048  * Blinds the given message with the given blinding key
2049  *
2050  * @param hash hash of the message to sign
2051  * @param bkey the blinding key
2052  * @param pkey the public key of the signer
2053  * @param[out] buf set to a buffer with the blinded message to be signed
2054  * @param[out] buf_size number of bytes stored in @a buf
2055  * @return #GNUNET_YES if successful, #GNUNET_NO if RSA key is malicious
2056  */
2057 int
2058 GNUNET_CRYPTO_rsa_blind (const struct GNUNET_HashCode *hash,
2059                          const struct GNUNET_CRYPTO_RsaBlindingKeySecret *bks,
2060                          struct GNUNET_CRYPTO_RsaPublicKey *pkey,
2061                          char **buf,
2062                          size_t *buf_size);
2063
2064
2065 /**
2066  * Sign a blinded value, which must be a full domain hash of a message.
2067  *
2068  * @param key private key to use for the signing
2069  * @param msg the (blinded) message to sign
2070  * @param msg_len number of bytes in @a msg to sign
2071  * @return NULL on error, signature on success
2072  */
2073 struct GNUNET_CRYPTO_RsaSignature *
2074 GNUNET_CRYPTO_rsa_sign_blinded (const struct GNUNET_CRYPTO_RsaPrivateKey *key,
2075                                 const void *msg,
2076                                 size_t msg_len);
2077
2078
2079 /**
2080  * Create and sign a full domain hash of a message.
2081  *
2082  * @param key private key to use for the signing
2083  * @param hash the hash of the message to sign
2084  * @return NULL on error, including a malicious RSA key, signature on success
2085  */
2086 struct GNUNET_CRYPTO_RsaSignature *
2087 GNUNET_CRYPTO_rsa_sign_fdh (const struct GNUNET_CRYPTO_RsaPrivateKey *key,
2088                             const struct GNUNET_HashCode *hash);
2089
2090
2091 /**
2092  * Free memory occupied by signature.
2093  *
2094  * @param sig memory to free
2095  */
2096 void
2097 GNUNET_CRYPTO_rsa_signature_free (struct GNUNET_CRYPTO_RsaSignature *sig);
2098
2099
2100 /**
2101  * Encode the given signature in a format suitable for storing it into a file.
2102  *
2103  * @param sig the signature
2104  * @param[out] buffer set to a buffer with the encoded key
2105  * @return size of memory allocated in @a buffer
2106  */
2107 size_t
2108 GNUNET_CRYPTO_rsa_signature_encode (
2109   const struct GNUNET_CRYPTO_RsaSignature *sig,
2110   char **buffer);
2111
2112
2113 /**
2114  * Decode the signature from the data-format back to the "normal", internal
2115  * format.
2116  *
2117  * @param buf the buffer where the public key data is stored
2118  * @param len the length of the data in @a buf
2119  * @return NULL on error
2120  */
2121 struct GNUNET_CRYPTO_RsaSignature *
2122 GNUNET_CRYPTO_rsa_signature_decode (const char *buf, size_t len);
2123
2124
2125 /**
2126  * Duplicate the given rsa signature
2127  *
2128  * @param sig the signature to duplicate
2129  * @return the duplicate key; NULL upon error
2130  */
2131 struct GNUNET_CRYPTO_RsaSignature *
2132 GNUNET_CRYPTO_rsa_signature_dup (const struct GNUNET_CRYPTO_RsaSignature *sig);
2133
2134
2135 /**
2136  * Unblind a blind-signed signature.  The signature should have been generated
2137  * with #GNUNET_CRYPTO_rsa_sign() using a hash that was blinded with
2138  * #GNUNET_CRYPTO_rsa_blind().
2139  *
2140  * @param sig the signature made on the blinded signature purpose
2141  * @param bks the blinding key secret used to blind the signature purpose
2142  * @param pkey the public key of the signer
2143  * @return unblinded signature on success, NULL if RSA key is bad or malicious.
2144  */
2145 struct GNUNET_CRYPTO_RsaSignature *
2146 GNUNET_CRYPTO_rsa_unblind (const struct GNUNET_CRYPTO_RsaSignature *sig,
2147                            const struct GNUNET_CRYPTO_RsaBlindingKeySecret *bks,
2148                            struct GNUNET_CRYPTO_RsaPublicKey *pkey);
2149
2150
2151 /**
2152  * Verify whether the given hash corresponds to the given signature and the
2153  * signature is valid with respect to the given public key.
2154  *
2155  * @param hash the message to verify to match the @a sig
2156  * @param sig signature that is being validated
2157  * @param public_key public key of the signer
2158  * @returns #GNUNET_YES if ok, #GNUNET_NO if RSA key is malicious, #GNUNET_SYSERR if signature
2159  */
2160 int
2161 GNUNET_CRYPTO_rsa_verify (const struct GNUNET_HashCode *hash,
2162                           const struct GNUNET_CRYPTO_RsaSignature *sig,
2163                           const struct GNUNET_CRYPTO_RsaPublicKey *public_key);
2164
2165
2166 #if 0 /* keep Emacsens' auto-indent happy */
2167 {
2168 #endif
2169 #ifdef __cplusplus
2170 }
2171 #endif
2172
2173
2174 /* ifndef GNUNET_CRYPTO_LIB_H */
2175 #endif
2176 /* end of gnunet_crypto_lib.h */