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 salt salt to use in pow calculation
 661  * @param buf data to hash
 662  * @param buf_len number of bytes in @a buf
 663  * @param result where to write the resulting hash
 664  */
 665 void
 666 GNUNET_CRYPTO_pow_hash (const char *salt,
 667                         const void *buf,
 668                         size_t buf_len,
 669                         struct GNUNET_HashCode *result);
 670
 671
 672 /**
 673  * Context for cummulative hashing.
 674  */
 675 struct GNUNET_HashContext;
 676
 677
 678 /**
 679  * Start incremental hashing operation.
 680  *
 681  * @return context for incremental hash computation
 682  */
 683 struct GNUNET_HashContext *
 684 GNUNET_CRYPTO_hash_context_start (void);
 685
 686
 687 /**
 688  * Add data to be hashed.
 689  *
 690  * @param hc cummulative hash context
 691  * @param buf data to add
 692  * @param size number of bytes in @a buf
 693  */
 694 void
 695 GNUNET_CRYPTO_hash_context_read (struct GNUNET_HashContext *hc,
 696                                  const void *buf,
 697                                  size_t size);
 698
 699
 700 /**
 701  * Finish the hash computation.
 702  *
 703  * @param hc hash context to use, is freed in the process
 704  * @param r_hash where to write the latest / final hash code
 705  */
 706 void
 707 GNUNET_CRYPTO_hash_context_finish (struct GNUNET_HashContext *hc,
 708                                    struct GNUNET_HashCode *r_hash);
 709
 710
 711 /**
 712  * Abort hashing, do not bother calculating final result.
 713  *
 714  * @param hc hash context to destroy
 715  */
 716 void
 717 GNUNET_CRYPTO_hash_context_abort (struct GNUNET_HashContext *hc);
 718
 719
 720 /**
 721  * Calculate HMAC of a message (RFC 2104)
 722  * TODO: Shouldn' this be the standard hmac function and
 723  * the above be renamed?
 724  *
 725  * @param key secret key
 726  * @param key_len secret key length
 727  * @param plaintext input plaintext
 728  * @param plaintext_len length of @a plaintext
 729  * @param hmac where to store the hmac
 730  */
 731 void
 732 GNUNET_CRYPTO_hmac_raw (const void *key,
 733                         size_t key_len,
 734                         const void *plaintext,
 735                         size_t plaintext_len,
 736                         struct GNUNET_HashCode *hmac);
 737
 738
 739 /**
 740  * @ingroup hash
 741  * Calculate HMAC of a message (RFC 2104)
 742  *
 743  * @param key secret key
 744  * @param plaintext input plaintext
 745  * @param plaintext_len length of @a plaintext
 746  * @param hmac where to store the hmac
 747  */
 748 void
 749 GNUNET_CRYPTO_hmac (const struct GNUNET_CRYPTO_AuthKey *key,
 750                     const void *plaintext,
 751                     size_t plaintext_len,
 752                     struct GNUNET_HashCode *hmac);
 753
 754
 755 /**
 756  * Function called once the hash computation over the
 757  * specified file has completed.
 758  *
 759  * @param cls closure
 760  * @param res resulting hash, NULL on error
 761  */
 762 typedef void (*GNUNET_CRYPTO_HashCompletedCallback) (
 763   void *cls,
 764   const struct GNUNET_HashCode *res);
 765
 766
 767 /**
 768  * Handle to file hashing operation.
 769  */
 770 struct GNUNET_CRYPTO_FileHashContext;
 771
 772
 773 /**
 774  * @ingroup hash
 775  * Compute the hash of an entire file.
 776  *
 777  * @param priority scheduling priority to use
 778  * @param filename name of file to hash
 779  * @param blocksize number of bytes to process in one task
 780  * @param callback function to call upon completion
 781  * @param callback_cls closure for @a callback
 782  * @return NULL on (immediate) errror
 783  */
 784 struct GNUNET_CRYPTO_FileHashContext *
 785 GNUNET_CRYPTO_hash_file (enum GNUNET_SCHEDULER_Priority priority,
 786                          const char *filename,
 787                          size_t blocksize,
 788                          GNUNET_CRYPTO_HashCompletedCallback callback,
 789                          void *callback_cls);
 790
 791
 792 /**
 793  * Cancel a file hashing operation.
 794  *
 795  * @param fhc operation to cancel (callback must not yet have been invoked)
 796  */
 797 void
 798 GNUNET_CRYPTO_hash_file_cancel (struct GNUNET_CRYPTO_FileHashContext *fhc);
 799
 800
 801 /**
 802  * @ingroup hash
 803  * Create a random hash code.
 804  *
 805  * @param mode desired quality level
 806  * @param result hash code that is randomized
 807  */
 808 void
 809 GNUNET_CRYPTO_hash_create_random (enum GNUNET_CRYPTO_Quality mode,
 810                                   struct GNUNET_HashCode *result);
 811
 812
 813 /**
 814  * @ingroup hash
 815  * compute @a result = @a b - @a a
 816  *
 817  * @param a some hash code
 818  * @param b some hash code
 819  * @param result set to @a b - @a a
 820  */
 821 void
 822 GNUNET_CRYPTO_hash_difference (const struct GNUNET_HashCode *a,
 823                                const struct GNUNET_HashCode *b,
 824                                struct GNUNET_HashCode *result);
 825
 826
 827 /**
 828  * @ingroup hash
 829  * compute @a result = @a a + @a delta
 830  *
 831  * @param a some hash code
 832  * @param delta some hash code
 833  * @param result set to @a a + @a delta
 834  */
 835 void
 836 GNUNET_CRYPTO_hash_sum (const struct GNUNET_HashCode *a,
 837                         const struct GNUNET_HashCode *delta,
 838                         struct GNUNET_HashCode *result);
 839
 840
 841 /**
 842  * @ingroup hash
 843  * compute result = a ^ b
 844  *
 845  * @param a some hash code
 846  * @param b some hash code
 847  * @param result set to @a a ^ @a b
 848  */
 849 void
 850 GNUNET_CRYPTO_hash_xor (const struct GNUNET_HashCode *a,
 851                         const struct GNUNET_HashCode *b,
 852                         struct GNUNET_HashCode *result);
 853
 854
 855 /**
 856  * @ingroup hash
 857  * Convert a hashcode into a key.
 858  *
 859  * @param hc hash code that serves to generate the key
 860  * @param skey set to a valid session key
 861  * @param iv set to a valid initialization vector
 862  */
 863 void
 864 GNUNET_CRYPTO_hash_to_aes_key (
 865   const struct GNUNET_HashCode *hc,
 866   struct GNUNET_CRYPTO_SymmetricSessionKey *skey,
 867   struct GNUNET_CRYPTO_SymmetricInitializationVector *iv);
 868
 869
 870 /**
 871  * @ingroup hash
 872  * Obtain a bit from a hashcode.
 873  *
 874  * @param code the `struct GNUNET_HashCode` to index bit-wise
 875  * @param bit index into the hashcode, [0...159]
 876  * @return Bit \a bit from hashcode \a code, -1 for invalid index
 877  */
 878 int
 879 GNUNET_CRYPTO_hash_get_bit (const struct GNUNET_HashCode *code,
 880                             unsigned int bit);
 881
 882
 883 /**
 884  * @ingroup hash
 885  * Determine how many low order bits match in two
 886  * `struct GNUNET_HashCodes`.  i.e. - 010011 and 011111 share
 887  * the first two lowest order bits, and therefore the
 888  * return value is two (NOT XOR distance, nor how many
 889  * bits match absolutely!).
 890  *
 891  * @param first the first hashcode
 892  * @param second the hashcode to compare first to
 893  * @return the number of bits that match
 894  */
 895 unsigned int
 896 GNUNET_CRYPTO_hash_matching_bits (const struct GNUNET_HashCode *first,
 897                                   const struct GNUNET_HashCode *second);
 898
 899
 900 /**
 901  * @ingroup hash
 902  * Compare function for HashCodes, producing a total ordering
 903  * of all hashcodes.
 904  *
 905  * @param h1 some hash code
 906  * @param h2 some hash code
 907  * @return 1 if @a h1 > @a h2, -1 if @a h1 < @a h2 and 0 if @a h1 == @a h2.
 908  */
 909 int
 910 GNUNET_CRYPTO_hash_cmp (const struct GNUNET_HashCode *h1,
 911                         const struct GNUNET_HashCode *h2);
 912
 913
 914 /**
 915  * @ingroup hash
 916  * Find out which of the two GNUNET_CRYPTO_hash codes is closer to target
 917  * in the XOR metric (Kademlia).
 918  *
 919  * @param h1 some hash code
 920  * @param h2 some hash code
 921  * @param target some hash code
 922  * @return -1 if @a h1 is closer, 1 if @a h2 is closer and 0 if @a h1== @a h2.
 923  */
 924 int
 925 GNUNET_CRYPTO_hash_xorcmp (const struct GNUNET_HashCode *h1,
 926                            const struct GNUNET_HashCode *h2,
 927                            const struct GNUNET_HashCode *target);
 928
 929
 930 /**
 931  * @ingroup hash
 932  * @brief Derive an authentication key
 933  * @param key authentication key
 934  * @param rkey root key
 935  * @param salt salt
 936  * @param salt_len size of the salt
 937  * @param argp pair of void * & size_t for context chunks, terminated by NULL
 938  */
 939 void
 940 GNUNET_CRYPTO_hmac_derive_key_v (
 941   struct GNUNET_CRYPTO_AuthKey *key,
 942   const struct GNUNET_CRYPTO_SymmetricSessionKey *rkey,
 943   const void *salt,
 944   size_t salt_len,
 945   va_list argp);
 946
 947
 948 /**
 949  * @ingroup hash
 950  * @brief Derive an authentication key
 951  * @param key authentication key
 952  * @param rkey root key
 953  * @param salt salt
 954  * @param salt_len size of the salt
 955  * @param ... pair of void * & size_t for context chunks, terminated by NULL
 956  */
 957 void
 958 GNUNET_CRYPTO_hmac_derive_key (
 959   struct GNUNET_CRYPTO_AuthKey *key,
 960   const struct GNUNET_CRYPTO_SymmetricSessionKey *rkey,
 961   const void *salt,
 962   size_t salt_len,
 963   ...);
 964
 965
 966 /**
 967  * @ingroup hash
 968  * @brief Derive key
 969  * @param result buffer for the derived key, allocated by caller
 970  * @param out_len desired length of the derived key
 971  * @param xtr_algo hash algorithm for the extraction phase, GCRY_MD_...
 972  * @param prf_algo hash algorithm for the expansion phase, GCRY_MD_...
 973  * @param xts salt
 974  * @param xts_len length of @a xts
 975  * @param skm source key material
 976  * @param skm_len length of @a skm
 977  * @param ... pair of void * & size_t for context chunks, terminated by NULL
 978  * @return #GNUNET_YES on success
 979  */
 980 int
 981 GNUNET_CRYPTO_hkdf (void *result,
 982                     size_t out_len,
 983                     int xtr_algo,
 984                     int prf_algo,
 985                     const void *xts,
 986                     size_t xts_len,
 987                     const void *skm,
 988                     size_t skm_len,
 989                     ...);
 990
 991
 992 /**
 993  * @ingroup hash
 994  * @brief Derive key
 995  * @param result buffer for the derived key, allocated by caller
 996  * @param out_len desired length of the derived key
 997  * @param xtr_algo hash algorithm for the extraction phase, GCRY_MD_...
 998  * @param prf_algo hash algorithm for the expansion phase, GCRY_MD_...
 999  * @param xts salt
1000  * @param xts_len length of @a xts
1001  * @param skm source key material
1002  * @param skm_len length of @a skm
1003  * @param argp va_list of void * & size_t pairs for context chunks
1004  * @return #GNUNET_YES on success
1005  */
1006 int
1007 GNUNET_CRYPTO_hkdf_v (void *result,
1008                       size_t out_len,
1009                       int xtr_algo,
1010                       int prf_algo,
1011                       const void *xts,
1012                       size_t xts_len,
1013                       const void *skm,
1014                       size_t skm_len,
1015                       va_list argp);
1016
1017
1018 /**
1019  * @brief Derive key
1020  * @param result buffer for the derived key, allocated by caller
1021  * @param out_len desired length of the derived key
1022  * @param xts salt
1023  * @param xts_len length of @a xts
1024  * @param skm source key material
1025  * @param skm_len length of @a skm
1026  * @param argp va_list of void * & size_t pairs for context chunks
1027  * @return #GNUNET_YES on success
1028  */
1029 int
1030 GNUNET_CRYPTO_kdf_v (void *result,
1031                      size_t out_len,
1032                      const void *xts,
1033                      size_t xts_len,
1034                      const void *skm,
1035                      size_t skm_len,
1036                      va_list argp);
1037
1038
1039 /**
1040  * Deterministically generate a pseudo-random number uniformly from the
1041  * integers modulo a libgcrypt mpi.
1042  *
1043  * @param[out] r MPI value set to the FDH
1044  * @param n MPI to work modulo
1045  * @param xts salt
1046  * @param xts_len length of @a xts
1047  * @param skm source key material
1048  * @param skm_len length of @a skm
1049  * @param ctx context string
1050  */
1051 void
1052 GNUNET_CRYPTO_kdf_mod_mpi (gcry_mpi_t *r,
1053                            gcry_mpi_t n,
1054                            const void *xts,
1055                            size_t xts_len,
1056                            const void *skm,
1057                            size_t skm_len,
1058                            const char *ctx);
1059
1060
1061 /**
1062  * @ingroup hash
1063  * @brief Derive key
1064  * @param result buffer for the derived key, allocated by caller
1065  * @param out_len desired length of the derived key
1066  * @param xts salt
1067  * @param xts_len length of @a xts
1068  * @param skm source key material
1069  * @param skm_len length of @a skm
1070  * @param ... void * & size_t pairs for context chunks
1071  * @return #GNUNET_YES on success
1072  */
1073 int
1074 GNUNET_CRYPTO_kdf (void *result,
1075                    size_t out_len,
1076                    const void *xts,
1077                    size_t xts_len,
1078                    const void *skm,
1079                    size_t skm_len,
1080                    ...);
1081
1082
1083 /**
1084  * @ingroup crypto
1085  * Extract the public key for the given private key.
1086  *
1087  * @param priv the private key
1088  * @param pub where to write the public key
1089  */
1090 void
1091 GNUNET_CRYPTO_ecdsa_key_get_public (
1092   const struct GNUNET_CRYPTO_EcdsaPrivateKey *priv,
1093   struct GNUNET_CRYPTO_EcdsaPublicKey *pub);
1094
1095 /**
1096  * @ingroup crypto
1097  * Extract the public key for the given private key.
1098  *
1099  * @param priv the private key
1100  * @param pub where to write the public key
1101  */
1102 void
1103 GNUNET_CRYPTO_eddsa_key_get_public (
1104   const struct GNUNET_CRYPTO_EddsaPrivateKey *priv,
1105   struct GNUNET_CRYPTO_EddsaPublicKey *pub);
1106
1107
1108 /**
1109  * @ingroup crypto
1110  * Extract the public key for the given private key.
1111  *
1112  * @param priv the private key
1113  * @param pub where to write the public key
1114  */
1115 void
1116 GNUNET_CRYPTO_ecdhe_key_get_public (
1117   const struct GNUNET_CRYPTO_EcdhePrivateKey *priv,
1118   struct GNUNET_CRYPTO_EcdhePublicKey *pub);
1119
1120
1121 /**
1122  * Convert a public key to a string.
1123  *
1124  * @param pub key to convert
1125  * @return string representing @a pub
1126  */
1127 char *
1128 GNUNET_CRYPTO_ecdsa_public_key_to_string (
1129   const struct GNUNET_CRYPTO_EcdsaPublicKey *pub);
1130
1131 /**
1132  * Convert a private key to a string.
1133  *
1134  * @param priv key to convert
1135  * @return string representing @a priv
1136  */
1137 char *
1138 GNUNET_CRYPTO_ecdsa_private_key_to_string (
1139   const struct GNUNET_CRYPTO_EcdsaPrivateKey *priv);
1140
1141
1142 /**
1143  * Convert a private key to a string.
1144  *
1145  * @param priv key to convert
1146  * @return string representing @a pub
1147  */
1148 char *
1149 GNUNET_CRYPTO_eddsa_private_key_to_string (
1150   const struct GNUNET_CRYPTO_EddsaPrivateKey *priv);
1151
1152
1153 /**
1154  * Convert a public key to a string.
1155  *
1156  * @param pub key to convert
1157  * @return string representing @a pub
1158  */
1159 char *
1160 GNUNET_CRYPTO_eddsa_public_key_to_string (
1161   const struct GNUNET_CRYPTO_EddsaPublicKey *pub);
1162
1163
1164 /**
1165  * Convert a string representing a public key to a public key.
1166  *
1167  * @param enc encoded public key
1168  * @param enclen number of bytes in @a enc (without 0-terminator)
1169  * @param pub where to store the public key
1170  * @return #GNUNET_OK on success
1171  */
1172 int
1173 GNUNET_CRYPTO_ecdsa_public_key_from_string (
1174   const char *enc,
1175   size_t enclen,
1176   struct GNUNET_CRYPTO_EcdsaPublicKey *pub);
1177
1178
1179 /**
1180  * Convert a string representing a private key to a private key.
1181  *
1182  * @param enc encoded public key
1183  * @param enclen number of bytes in @a enc (without 0-terminator)
1184  * @param priv where to store the private key
1185  * @return #GNUNET_OK on success
1186  */
1187 int
1188 GNUNET_CRYPTO_eddsa_private_key_from_string (
1189   const char *enc,
1190   size_t enclen,
1191   struct GNUNET_CRYPTO_EddsaPrivateKey *pub);
1192
1193
1194 /**
1195  * Convert a string representing a public key to a public key.
1196  *
1197  * @param enc encoded public key
1198  * @param enclen number of bytes in @a enc (without 0-terminator)
1199  * @param pub where to store the public key
1200  * @return #GNUNET_OK on success
1201  */
1202 int
1203 GNUNET_CRYPTO_eddsa_public_key_from_string (
1204   const char *enc,
1205   size_t enclen,
1206   struct GNUNET_CRYPTO_EddsaPublicKey *pub);
1207
1208
1209 /**
1210  * @ingroup crypto
1211  * Create a new private key by reading it from a file.  If the
1212  * files does not exist, create a new key and write it to the
1213  * file.  Caller must free return value.  Note that this function
1214  * can not guarantee that another process might not be trying
1215  * the same operation on the same file at the same time.
1216  * If the contents of the file
1217  * are invalid the old file is deleted and a fresh key is
1218  * created.
1219  *
1220  * @param filename name of file to use to store the key
1221  * @return new private key, NULL on error (for example,
1222  *   permission denied); free using #GNUNET_free
1223  */
1224 struct GNUNET_CRYPTO_EcdsaPrivateKey *
1225 GNUNET_CRYPTO_ecdsa_key_create_from_file (const char *filename);
1226
1227
1228 /**
1229  * @ingroup crypto
1230  * Create a new private key by reading it from a file.  If the
1231  * files does not exist, create a new key and write it to the
1232  * file.  Caller must free return value.  Note that this function
1233  * can not guarantee that another process might not be trying
1234  * the same operation on the same file at the same time.
1235  * If the contents of the file
1236  * are invalid the old file is deleted and a fresh key is
1237  * created.
1238  *
1239  * @param filename name of file to use to store the key
1240  * @return new private key, NULL on error (for example,
1241  *   permission denied); free using #GNUNET_free
1242  */
1243 struct GNUNET_CRYPTO_EddsaPrivateKey *
1244 GNUNET_CRYPTO_eddsa_key_create_from_file (const char *filename);
1245
1246
1247 /**
1248  * Forward declaration to simplify #include-structure.
1249  */
1250 struct GNUNET_CONFIGURATION_Handle;
1251
1252
1253 /**
1254  * @ingroup crypto
1255  * Create a new private key by reading our peer's key from
1256  * the file specified in the configuration.
1257  *
1258  * @param cfg the configuration to use
1259  * @return new private key, NULL on error (for example,
1260  *   permission denied); free using #GNUNET_free
1261  */
1262 struct GNUNET_CRYPTO_EddsaPrivateKey *
1263 GNUNET_CRYPTO_eddsa_key_create_from_configuration (
1264   const struct GNUNET_CONFIGURATION_Handle *cfg);
1265
1266
1267 /**
1268  * @ingroup crypto
1269  * Create a new private key. Caller must free return value.
1270  *
1271  * @return fresh private key; free using #GNUNET_free
1272  */
1273 struct GNUNET_CRYPTO_EcdsaPrivateKey *
1274 GNUNET_CRYPTO_ecdsa_key_create (void);
1275
1276
1277 /**
1278  * @ingroup crypto
1279  * Create a new private key. Caller must free return value.
1280  *
1281  * @return fresh private key; free using #GNUNET_free
1282  */
1283 struct GNUNET_CRYPTO_EddsaPrivateKey *
1284 GNUNET_CRYPTO_eddsa_key_create (void);
1285
1286
1287 /**
1288  * @ingroup crypto
1289  * Create a new private key.  Clear with #GNUNET_CRYPTO_ecdhe_key_clear().
1290  *
1291  * @param[out] pk set to fresh private key;
1292  * @return #GNUNET_OK on success, #GNUNET_SYSERR on failure
1293  */
1294 int
1295 GNUNET_CRYPTO_ecdhe_key_create2 (struct GNUNET_CRYPTO_EcdhePrivateKey *pk);
1296
1297
1298 /**
1299  * @ingroup crypto
1300  * Create a new private key. Caller must free return value.
1301  *
1302  * @return fresh private key; free using #GNUNET_free
1303  */
1304 struct GNUNET_CRYPTO_EcdhePrivateKey *
1305 GNUNET_CRYPTO_ecdhe_key_create (void);
1306
1307
1308 /**
1309  * @ingroup crypto
1310  * Clear memory that was used to store a private key.
1311  *
1312  * @param pk location of the key
1313  */
1314 void
1315 GNUNET_CRYPTO_eddsa_key_clear (struct GNUNET_CRYPTO_EddsaPrivateKey *pk);
1316
1317
1318 /**
1319  * @ingroup crypto
1320  * Clear memory that was used to store a private key.
1321  *
1322  * @param pk location of the key
1323  */
1324 void
1325 GNUNET_CRYPTO_ecdsa_key_clear (struct GNUNET_CRYPTO_EcdsaPrivateKey *pk);
1326
1327
1328 /**
1329  * @ingroup crypto
1330  * Clear memory that was used to store a private key.
1331  *
1332  * @param pk location of the key
1333  */
1334 void
1335 GNUNET_CRYPTO_ecdhe_key_clear (struct GNUNET_CRYPTO_EcdhePrivateKey *pk);
1336
1337
1338 /**
1339  * @ingroup crypto
1340  * Get the shared private key we use for anonymous users.
1341  *
1342  * @return "anonymous" private key; do not free
1343  */
1344 const struct GNUNET_CRYPTO_EcdsaPrivateKey *
1345 GNUNET_CRYPTO_ecdsa_key_get_anonymous (void);
1346
1347
1348 /**
1349  * @ingroup crypto
1350  * Setup a hostkey file for a peer given the name of the
1351  * configuration file (!).  This function is used so that
1352  * at a later point code can be certain that reading a
1353  * hostkey is fast (for example in time-dependent testcases).
1354  *
1355  * @param cfg_name name of the configuration file to use
1356  */
1357 void
1358 GNUNET_CRYPTO_eddsa_setup_hostkey (const char *cfg_name);
1359
1360
1361 /**
1362  * @ingroup crypto
1363  * Retrieve the identity of the host's peer.
1364  *
1365  * @param cfg configuration to use
1366  * @param dst pointer to where to write the peer identity
1367  * @return #GNUNET_OK on success, #GNUNET_SYSERR if the identity
1368  *         could not be retrieved
1369  */
1370 int
1371 GNUNET_CRYPTO_get_peer_identity (const struct GNUNET_CONFIGURATION_Handle *cfg,
1372                                  struct GNUNET_PeerIdentity *dst);
1373
1374
1375 /**
1376  * Internal structure used to cache pre-calculated values for DLOG calculation.
1377  */
1378 struct GNUNET_CRYPTO_EccDlogContext;
1379
1380
1381 /**
1382  * Point on a curve (always for Curve25519) encoded in a format suitable
1383  * for network transmission (ECDH), see http://cr.yp.to/ecdh.html.
1384  */
1385 struct GNUNET_CRYPTO_EccPoint
1386 {
1387   /**
1388    * Q consists of an x- and a y-value, each mod p (256 bits), given
1389    * here in affine coordinates and Ed25519 standard compact format.
1390    */
1391   unsigned char q_y[256 / 8];
1392 };
1393
1394
1395 /**
1396  * Do pre-calculation for ECC discrete logarithm for small factors.
1397  *
1398  * @param max maximum value the factor can be
1399  * @param mem memory to use (should be smaller than @a max), must not be zero.
1400  * @return NULL on error
1401  */
1402 struct GNUNET_CRYPTO_EccDlogContext *
1403 GNUNET_CRYPTO_ecc_dlog_prepare (unsigned int max, unsigned int mem);
1404
1405
1406 /**
1407  * Calculate ECC discrete logarithm for small factors.
1408  * Opposite of #GNUNET_CRYPTO_ecc_dexp().
1409  *
1410  * @param dlc precalculated values, determine range of factors
1411  * @param input point on the curve to factor
1412  * @return INT_MAX if dlog failed, otherwise the factor
1413  */
1414 int
1415 GNUNET_CRYPTO_ecc_dlog (struct GNUNET_CRYPTO_EccDlogContext *edc,
1416                         gcry_mpi_point_t input);
1417
1418
1419 /**
1420  * Multiply the generator g of the elliptic curve by @a val
1421  * to obtain the point on the curve representing @a val.
1422  * Afterwards, point addition will correspond to integer
1423  * addition.  #GNUNET_CRYPTO_ecc_dlog() can be used to
1424  * convert a point back to an integer (as long as the
1425  * integer is smaller than the MAX of the @a edc context).
1426  *
1427  * @param edc calculation context for ECC operations
1428  * @param val value to encode into a point
1429  * @return representation of the value as an ECC point,
1430  *         must be freed using #GNUNET_CRYPTO_ecc_free()
1431  */
1432 gcry_mpi_point_t
1433 GNUNET_CRYPTO_ecc_dexp (struct GNUNET_CRYPTO_EccDlogContext *edc, int val);
1434
1435
1436 /**
1437  * Multiply the generator g of the elliptic curve by @a val
1438  * to obtain the point on the curve representing @a val.
1439  *
1440  * @param edc calculation context for ECC operations
1441  * @param val (positive) value to encode into a point
1442  * @return representation of the value as an ECC point,
1443  *         must be freed using #GNUNET_CRYPTO_ecc_free()
1444  */
1445 gcry_mpi_point_t
1446 GNUNET_CRYPTO_ecc_dexp_mpi (struct GNUNET_CRYPTO_EccDlogContext *edc,
1447                             gcry_mpi_t val);
1448
1449
1450 /**
1451  * Multiply the point @a p on the elliptic curve by @a val.
1452  *
1453  * @param edc calculation context for ECC operations
1454  * @param p point to multiply
1455  * @param val (positive) value to encode into a point
1456  * @return representation of the value as an ECC point,
1457  *         must be freed using #GNUNET_CRYPTO_ecc_free()
1458  */
1459 gcry_mpi_point_t
1460 GNUNET_CRYPTO_ecc_pmul_mpi (struct GNUNET_CRYPTO_EccDlogContext *edc,
1461                             gcry_mpi_point_t p,
1462                             gcry_mpi_t val);
1463
1464
1465 /**
1466  * Convert point value to binary representation.
1467  *
1468  * @param edc calculation context for ECC operations
1469  * @param point computational point representation
1470  * @param[out] bin binary point representation
1471  */
1472 void
1473 GNUNET_CRYPTO_ecc_point_to_bin (struct GNUNET_CRYPTO_EccDlogContext *edc,
1474                                 gcry_mpi_point_t point,
1475                                 struct GNUNET_CRYPTO_EccPoint *bin);
1476
1477
1478 /**
1479  * Convert binary representation of a point to computational representation.
1480  *
1481  * @param edc calculation context for ECC operations
1482  * @param bin binary point representation
1483  * @return computational representation
1484  */
1485 gcry_mpi_point_t
1486 GNUNET_CRYPTO_ecc_bin_to_point (struct GNUNET_CRYPTO_EccDlogContext *edc,
1487                                 const struct GNUNET_CRYPTO_EccPoint *bin);
1488
1489
1490 /**
1491  * Add two points on the elliptic curve.
1492  *
1493  * @param edc calculation context for ECC operations
1494  * @param a some value
1495  * @param b some value
1496  * @return @a a + @a b, must be freed using #GNUNET_CRYPTO_ecc_free()
1497  */
1498 gcry_mpi_point_t
1499 GNUNET_CRYPTO_ecc_add (struct GNUNET_CRYPTO_EccDlogContext *edc,
1500                        gcry_mpi_point_t a,
1501                        gcry_mpi_point_t b);
1502
1503
1504 /**
1505  * Obtain a random point on the curve and its
1506  * additive inverse. Both returned values
1507  * must be freed using #GNUNET_CRYPTO_ecc_free().
1508  *
1509  * @param edc calculation context for ECC operations
1510  * @param[out] r set to a random point on the curve
1511  * @param[out] r_inv set to the additive inverse of @a r
1512  */
1513 void
1514 GNUNET_CRYPTO_ecc_rnd (struct GNUNET_CRYPTO_EccDlogContext *edc,
1515                        gcry_mpi_point_t *r,
1516                        gcry_mpi_point_t *r_inv);
1517
1518
1519 /**
1520  * Obtain a random scalar for point multiplication on the curve and
1521  * its multiplicative inverse.
1522  *
1523  * @param edc calculation context for ECC operations
1524  * @param[out] r set to a random scalar on the curve
1525  * @param[out] r_inv set to the multiplicative inverse of @a r
1526  */
1527 void
1528 GNUNET_CRYPTO_ecc_rnd_mpi (struct GNUNET_CRYPTO_EccDlogContext *edc,
1529                            gcry_mpi_t *r,
1530                            gcry_mpi_t *r_inv);
1531
1532
1533 /**
1534  * Generate a random value mod n.
1535  *
1536  * @param edc ECC context
1537  * @return random value mod n.
1538  */
1539 gcry_mpi_t
1540 GNUNET_CRYPTO_ecc_random_mod_n (struct GNUNET_CRYPTO_EccDlogContext *edc);
1541
1542
1543 /**
1544  * Free a point value returned by the API.
1545  *
1546  * @param p point to free
1547  */
1548 void
1549 GNUNET_CRYPTO_ecc_free (gcry_mpi_point_t p);
1550
1551
1552 /**
1553  * Release precalculated values.
1554  *
1555  * @param dlc dlog context
1556  */
1557 void
1558 GNUNET_CRYPTO_ecc_dlog_release (struct GNUNET_CRYPTO_EccDlogContext *dlc);
1559
1560
1561 /**
1562  * @ingroup crypto
1563  * Derive key material from a public and a private ECC key.
1564  *
1565  * @param priv private key to use for the ECDH (x)
1566  * @param pub public key to use for the ECDH (yG)
1567  * @param key_material where to write the key material (xyG)
1568  * @return #GNUNET_SYSERR on error, #GNUNET_OK on success
1569  */
1570 int
1571 GNUNET_CRYPTO_ecc_ecdh (const struct GNUNET_CRYPTO_EcdhePrivateKey *priv,
1572                         const struct GNUNET_CRYPTO_EcdhePublicKey *pub,
1573                         struct GNUNET_HashCode *key_material);
1574
1575
1576 /**
1577  * @ingroup crypto
1578  * Derive key material from a ECDH public key and a private EdDSA key.
1579  * Dual to #GNUNET_CRRYPTO_ecdh_eddsa.
1580  *
1581  * @param priv private key from EdDSA to use for the ECDH (x)
1582  * @param pub public key to use for the ECDH (yG)
1583  * @param key_material where to write the key material H(h(x)yG)
1584  * @return #GNUNET_SYSERR on error, #GNUNET_OK on success
1585  */
1586 int
1587 GNUNET_CRYPTO_eddsa_ecdh (const struct GNUNET_CRYPTO_EddsaPrivateKey *priv,
1588                           const struct GNUNET_CRYPTO_EcdhePublicKey *pub,
1589                           struct GNUNET_HashCode *key_material);
1590
1591 /**
1592  * @ingroup crypto
1593  * Derive key material from a ECDH public key and a private ECDSA key.
1594  * Dual to #GNUNET_CRRYPTO_ecdh_ecdsa.
1595  *
1596  * @param priv private key from ECDSA to use for the ECDH (x)
1597  * @param pub public key to use for the ECDH (yG)
1598  * @param key_material where to write the key material H(h(x)yG)
1599  * @return #GNUNET_SYSERR on error, #GNUNET_OK on success
1600  */
1601 int
1602 GNUNET_CRYPTO_ecdsa_ecdh (const struct GNUNET_CRYPTO_EcdsaPrivateKey *priv,
1603                           const struct GNUNET_CRYPTO_EcdhePublicKey *pub,
1604                           struct GNUNET_HashCode *key_material);
1605
1606
1607 /**
1608  * @ingroup crypto
1609  * Derive key material from a EdDSA public key and a private ECDH key.
1610  * Dual to #GNUNET_CRRYPTO_eddsa_ecdh.
1611  *
1612  * @param priv private key to use for the ECDH (y)
1613  * @param pub public key from EdDSA to use for the ECDH (X=h(x)G)
1614  * @param key_material where to write the key material H(yX)=H(h(x)yG)
1615  * @return #GNUNET_SYSERR on error, #GNUNET_OK on success
1616  */
1617 int
1618 GNUNET_CRYPTO_ecdh_eddsa (const struct GNUNET_CRYPTO_EcdhePrivateKey *priv,
1619                           const struct GNUNET_CRYPTO_EddsaPublicKey *pub,
1620                           struct GNUNET_HashCode *key_material);
1621
1622 /**
1623  * @ingroup crypto
1624  * Derive key material from a EcDSA public key and a private ECDH key.
1625  * Dual to #GNUNET_CRRYPTO_ecdsa_ecdh.
1626  *
1627  * @param priv private key to use for the ECDH (y)
1628  * @param pub public key from ECDSA to use for the ECDH (X=h(x)G)
1629  * @param key_material where to write the key material H(yX)=H(h(x)yG)
1630  * @return #GNUNET_SYSERR on error, #GNUNET_OK on success
1631  */
1632 int
1633 GNUNET_CRYPTO_ecdh_ecdsa (const struct GNUNET_CRYPTO_EcdhePrivateKey *priv,
1634                           const struct GNUNET_CRYPTO_EcdsaPublicKey *pub,
1635                           struct GNUNET_HashCode *key_material);
1636
1637
1638 /**
1639  * @ingroup crypto
1640  * EdDSA sign a given block.
1641  *
1642  * @param priv private key to use for the signing
1643  * @param purpose what to sign (size, purpose)
1644  * @param sig where to write the signature
1645  * @return #GNUNET_SYSERR on error, #GNUNET_OK on success
1646  */
1647 int
1648 GNUNET_CRYPTO_eddsa_sign (
1649   const struct GNUNET_CRYPTO_EddsaPrivateKey *priv,
1650   const struct GNUNET_CRYPTO_EccSignaturePurpose *purpose,
1651   struct GNUNET_CRYPTO_EddsaSignature *sig);
1652
1653
1654 /**
1655  * @ingroup crypto
1656  * ECDSA Sign a given block.
1657  *
1658  * @param priv private key to use for the signing
1659  * @param purpose what to sign (size, purpose)
1660  * @param sig where to write the signature
1661  * @return #GNUNET_SYSERR on error, #GNUNET_OK on success
1662  */
1663 int
1664 GNUNET_CRYPTO_ecdsa_sign (
1665   const struct GNUNET_CRYPTO_EcdsaPrivateKey *priv,
1666   const struct GNUNET_CRYPTO_EccSignaturePurpose *purpose,
1667   struct GNUNET_CRYPTO_EcdsaSignature *sig);
1668
1669 /**
1670  * @ingroup crypto
1671  * Verify EdDSA signature.
1672  *
1673  * @param purpose what is the purpose that the signature should have?
1674  * @param validate block to validate (size, purpose, data)
1675  * @param sig signature that is being validated
1676  * @param pub public key of the signer
1677  * @returns #GNUNET_OK if ok, #GNUNET_SYSERR if invalid
1678  */
1679 int
1680 GNUNET_CRYPTO_eddsa_verify (
1681   uint32_t purpose,
1682   const struct GNUNET_CRYPTO_EccSignaturePurpose *validate,
1683   const struct GNUNET_CRYPTO_EddsaSignature *sig,
1684   const struct GNUNET_CRYPTO_EddsaPublicKey *pub);
1685
1686
1687 /**
1688  * @ingroup crypto
1689  * Verify ECDSA signature.
1690  *
1691  * @param purpose what is the purpose that the signature should have?
1692  * @param validate block to validate (size, purpose, data)
1693  * @param sig signature that is being validated
1694  * @param pub public key of the signer
1695  * @returns #GNUNET_OK if ok, #GNUNET_SYSERR if invalid
1696  */
1697 int
1698 GNUNET_CRYPTO_ecdsa_verify (
1699   uint32_t purpose,
1700   const struct GNUNET_CRYPTO_EccSignaturePurpose *validate,
1701   const struct GNUNET_CRYPTO_EcdsaSignature *sig,
1702   const struct GNUNET_CRYPTO_EcdsaPublicKey *pub);
1703
1704
1705 /**
1706  * @ingroup crypto
1707  * Derive a private key from a given private key and a label.
1708  * Essentially calculates a private key 'h = H(l,P) * d mod n'
1709  * where n is the size of the ECC group and P is the public
1710  * key associated with the private key 'd'.
1711  *
1712  * @param priv original private key
1713  * @param label label to use for key deriviation
1714  * @param context additional context to use for HKDF of 'h';
1715  *        typically the name of the subsystem/application
1716  * @return derived private key
1717  */
1718 struct GNUNET_CRYPTO_EcdsaPrivateKey *
1719 GNUNET_CRYPTO_ecdsa_private_key_derive (
1720   const struct GNUNET_CRYPTO_EcdsaPrivateKey *priv,
1721   const char *label,
1722   const char *context);
1723
1724
1725 /**
1726  * @ingroup crypto
1727  * Derive a public key from a given public key and a label.
1728  * Essentially calculates a public key 'V = H(l,P) * P'.
1729  *
1730  * @param pub original public key
1731  * @param label label to use for key deriviation
1732  * @param context additional context to use for HKDF of 'h'.
1733  *        typically the name of the subsystem/application
1734  * @param result where to write the derived public key
1735  */
1736 void
1737 GNUNET_CRYPTO_ecdsa_public_key_derive (
1738   const struct GNUNET_CRYPTO_EcdsaPublicKey *pub,
1739   const char *label,
1740   const char *context,
1741   struct GNUNET_CRYPTO_EcdsaPublicKey *result);
1742
1743
1744 /**
1745  * Output the given MPI value to the given buffer in network
1746  * byte order.  The MPI @a val may not be negative.
1747  *
1748  * @param buf where to output to
1749  * @param size number of bytes in @a buf
1750  * @param val value to write to @a buf
1751  */
1752 void
1753 GNUNET_CRYPTO_mpi_print_unsigned (void *buf, size_t size, gcry_mpi_t val);
1754
1755
1756 /**
1757  * Convert data buffer into MPI value.
1758  * The buffer is interpreted as network
1759  * byte order, unsigned integer.
1760  *
1761  * @param result where to store MPI value (allocated)
1762  * @param data raw data (GCRYMPI_FMT_USG)
1763  * @param size number of bytes in @a data
1764  */
1765 void
1766 GNUNET_CRYPTO_mpi_scan_unsigned (gcry_mpi_t *result,
1767                                  const void *data,
1768                                  size_t size);
1769
1770
1771 /**
1772  * Create a freshly generated paillier public key.
1773  *
1774  * @param[out] public_key Where to store the public key?
1775  * @param[out] private_key Where to store the private key?
1776  */
1777 void
1778 GNUNET_CRYPTO_paillier_create (
1779   struct GNUNET_CRYPTO_PaillierPublicKey *public_key,
1780   struct GNUNET_CRYPTO_PaillierPrivateKey *private_key);
1781
1782
1783 /**
1784  * Encrypt a plaintext with a paillier public key.
1785  *
1786  * @param public_key Public key to use.
1787  * @param m Plaintext to encrypt.
1788  * @param desired_ops How many homomorphic ops the caller intends to use
1789  * @param[out] ciphertext Encrytion of @a plaintext with @a public_key.
1790  * @return guaranteed number of supported homomorphic operations >= 1,
1791  *         or desired_ops, in case that is lower,
1792  *         or -1 if less than one homomorphic operation is possible
1793  */
1794 int
1795 GNUNET_CRYPTO_paillier_encrypt (
1796   const struct GNUNET_CRYPTO_PaillierPublicKey *public_key,
1797   const gcry_mpi_t m,
1798   int desired_ops,
1799   struct GNUNET_CRYPTO_PaillierCiphertext *ciphertext);
1800
1801
1802 /**
1803  * Decrypt a paillier ciphertext with a private key.
1804  *
1805  * @param private_key Private key to use for decryption.
1806  * @param public_key Public key to use for decryption.
1807  * @param ciphertext Ciphertext to decrypt.
1808  * @param[out] m Decryption of @a ciphertext with @private_key.
1809  */
1810 void
1811 GNUNET_CRYPTO_paillier_decrypt (
1812   const struct GNUNET_CRYPTO_PaillierPrivateKey *private_key,
1813   const struct GNUNET_CRYPTO_PaillierPublicKey *public_key,
1814   const struct GNUNET_CRYPTO_PaillierCiphertext *ciphertext,
1815   gcry_mpi_t m);
1816
1817
1818 /**
1819  * Compute a ciphertext that represents the sum of the plaintext in @a x1 and @a x2
1820  *
1821  * Note that this operation can only be done a finite number of times
1822  * before an overflow occurs.
1823  *
1824  * @param public_key Public key to use for encryption.
1825  * @param c1 Paillier cipher text.
1826  * @param c2 Paillier cipher text.
1827  * @param[out] result Result of the homomorphic operation.
1828  * @return #GNUNET_OK if the result could be computed,
1829  *         #GNUNET_SYSERR if no more homomorphic operations are remaining.
1830  */
1831 int
1832 GNUNET_CRYPTO_paillier_hom_add (
1833   const struct GNUNET_CRYPTO_PaillierPublicKey *public_key,
1834   const struct GNUNET_CRYPTO_PaillierCiphertext *c1,
1835   const struct GNUNET_CRYPTO_PaillierCiphertext *c2,
1836   struct GNUNET_CRYPTO_PaillierCiphertext *result);
1837
1838
1839 /**
1840  * Get the number of remaining supported homomorphic operations.
1841  *
1842  * @param c Paillier cipher text.
1843  * @return the number of remaining homomorphic operations
1844  */
1845 int
1846 GNUNET_CRYPTO_paillier_hom_get_remaining (
1847   const struct GNUNET_CRYPTO_PaillierCiphertext *c);
1848
1849
1850 /* ********* Chaum-style RSA-based blind signatures ******************* */
1851
1852
1853 /**
1854  * The private information of an RSA key pair.
1855  */
1856 struct GNUNET_CRYPTO_RsaPrivateKey;
1857
1858 /**
1859  * The public information of an RSA key pair.
1860  */
1861 struct GNUNET_CRYPTO_RsaPublicKey;
1862
1863 /**
1864  * Constant-size pre-secret for blinding key generation.
1865  */
1866 struct GNUNET_CRYPTO_RsaBlindingKeySecret
1867 {
1868   /**
1869    * Bits used to generate the blinding key.  256 bits
1870    * of entropy is enough.
1871    */
1872   uint32_t pre_secret[8] GNUNET_PACKED;
1873 };
1874
1875 /**
1876  * @brief an RSA signature
1877  */
1878 struct GNUNET_CRYPTO_RsaSignature;
1879
1880
1881 /**
1882  * Create a new private key. Caller must free return value.
1883  *
1884  * @param len length of the key in bits (i.e. 2048)
1885  * @return fresh private key
1886  */
1887 struct GNUNET_CRYPTO_RsaPrivateKey *
1888 GNUNET_CRYPTO_rsa_private_key_create (unsigned int len);
1889
1890
1891 /**
1892  * Free memory occupied by the private key.
1893  *
1894  * @param key pointer to the memory to free
1895  */
1896 void
1897 GNUNET_CRYPTO_rsa_private_key_free (struct GNUNET_CRYPTO_RsaPrivateKey *key);
1898
1899
1900 /**
1901  * Encode the private key in a format suitable for
1902  * storing it into a file.
1903  *
1904  * @param key the private key
1905  * @param[out] buffer set to a buffer with the encoded key
1906  * @return size of memory allocatedin @a buffer
1907  */
1908 size_t
1909 GNUNET_CRYPTO_rsa_private_key_encode (
1910   const struct GNUNET_CRYPTO_RsaPrivateKey *key,
1911   char **buffer);
1912
1913
1914 /**
1915  * Decode the private key from the data-format back
1916  * to the "normal", internal format.
1917  *
1918  * @param buf the buffer where the private key data is stored
1919  * @param len the length of the data in @a buf
1920  * @return NULL on error
1921  */
1922 struct GNUNET_CRYPTO_RsaPrivateKey *
1923 GNUNET_CRYPTO_rsa_private_key_decode (const char *buf, size_t len);
1924
1925
1926 /**
1927  * Duplicate the given private key
1928  *
1929  * @param key the private key to duplicate
1930  * @return the duplicate key; NULL upon error
1931  */
1932 struct GNUNET_CRYPTO_RsaPrivateKey *
1933 GNUNET_CRYPTO_rsa_private_key_dup (
1934   const struct GNUNET_CRYPTO_RsaPrivateKey *key);
1935
1936
1937 /**
1938  * Extract the public key of the given private key.
1939  *
1940  * @param priv the private key
1941  * @retur NULL on error, otherwise the public key
1942  */
1943 struct GNUNET_CRYPTO_RsaPublicKey *
1944 GNUNET_CRYPTO_rsa_private_key_get_public (
1945   const struct GNUNET_CRYPTO_RsaPrivateKey *priv);
1946
1947
1948 /**
1949  * Compute hash over the public key.
1950  *
1951  * @param key public key to hash
1952  * @param hc where to store the hash code
1953  */
1954 void
1955 GNUNET_CRYPTO_rsa_public_key_hash (const struct GNUNET_CRYPTO_RsaPublicKey *key,
1956                                    struct GNUNET_HashCode *hc);
1957
1958
1959 /**
1960  * Obtain the length of the RSA key in bits.
1961  *
1962  * @param key the public key to introspect
1963  * @return length of the key in bits
1964  */
1965 unsigned int
1966 GNUNET_CRYPTO_rsa_public_key_len (const struct GNUNET_CRYPTO_RsaPublicKey *key);
1967
1968
1969 /**
1970  * Free memory occupied by the public key.
1971  *
1972  * @param key pointer to the memory to free
1973  */
1974 void
1975 GNUNET_CRYPTO_rsa_public_key_free (struct GNUNET_CRYPTO_RsaPublicKey *key);
1976
1977
1978 /**
1979  * Encode the public key in a format suitable for
1980  * storing it into a file.
1981  *
1982  * @param key the private key
1983  * @param[out] buffer set to a buffer with the encoded key
1984  * @return size of memory allocated in @a buffer
1985  */
1986 size_t
1987 GNUNET_CRYPTO_rsa_public_key_encode (
1988   const struct GNUNET_CRYPTO_RsaPublicKey *key,
1989   char **buffer);
1990
1991
1992 /**
1993  * Decode the public key from the data-format back
1994  * to the "normal", internal format.
1995  *
1996  * @param buf the buffer where the public key data is stored
1997  * @param len the length of the data in @a buf
1998  * @return NULL on error
1999  */
2000 struct GNUNET_CRYPTO_RsaPublicKey *
2001 GNUNET_CRYPTO_rsa_public_key_decode (const char *buf, size_t len);
2002
2003
2004 /**
2005  * Duplicate the given public key
2006  *
2007  * @param key the public key to duplicate
2008  * @return the duplicate key; NULL upon error
2009  */
2010 struct GNUNET_CRYPTO_RsaPublicKey *
2011 GNUNET_CRYPTO_rsa_public_key_dup (const struct GNUNET_CRYPTO_RsaPublicKey *key);
2012
2013
2014 /**
2015  * Compare the values of two signatures.
2016  *
2017  * @param s1 one signature
2018  * @param s2 the other signature
2019  * @return 0 if the two are equal
2020  */
2021 int
2022 GNUNET_CRYPTO_rsa_signature_cmp (struct GNUNET_CRYPTO_RsaSignature *s1,
2023                                  struct GNUNET_CRYPTO_RsaSignature *s2);
2024
2025 /**
2026  * Compare the values of two private keys.
2027  *
2028  * @param p1 one private key
2029  * @param p2 the other private key
2030  * @return 0 if the two are equal
2031  */
2032 int
2033 GNUNET_CRYPTO_rsa_private_key_cmp (struct GNUNET_CRYPTO_RsaPrivateKey *p1,
2034                                    struct GNUNET_CRYPTO_RsaPrivateKey *p2);
2035
2036
2037 /**
2038  * Compare the values of two public keys.
2039  *
2040  * @param p1 one public key
2041  * @param p2 the other public key
2042  * @return 0 if the two are equal
2043  */
2044 int
2045 GNUNET_CRYPTO_rsa_public_key_cmp (struct GNUNET_CRYPTO_RsaPublicKey *p1,
2046                                   struct GNUNET_CRYPTO_RsaPublicKey *p2);
2047
2048
2049 /**
2050  * Blinds the given message with the given blinding key
2051  *
2052  * @param hash hash of the message to sign
2053  * @param bkey the blinding key
2054  * @param pkey the public key of the signer
2055  * @param[out] buf set to a buffer with the blinded message to be signed
2056  * @param[out] buf_size number of bytes stored in @a buf
2057  * @return #GNUNET_YES if successful, #GNUNET_NO if RSA key is malicious
2058  */
2059 int
2060 GNUNET_CRYPTO_rsa_blind (const struct GNUNET_HashCode *hash,
2061                          const struct GNUNET_CRYPTO_RsaBlindingKeySecret *bks,
2062                          struct GNUNET_CRYPTO_RsaPublicKey *pkey,
2063                          char **buf,
2064                          size_t *buf_size);
2065
2066
2067 /**
2068  * Sign a blinded value, which must be a full domain hash of a message.
2069  *
2070  * @param key private key to use for the signing
2071  * @param msg the (blinded) message to sign
2072  * @param msg_len number of bytes in @a msg to sign
2073  * @return NULL on error, signature on success
2074  */
2075 struct GNUNET_CRYPTO_RsaSignature *
2076 GNUNET_CRYPTO_rsa_sign_blinded (const struct GNUNET_CRYPTO_RsaPrivateKey *key,
2077                                 const void *msg,
2078                                 size_t msg_len);
2079
2080
2081 /**
2082  * Create and sign a full domain hash of a message.
2083  *
2084  * @param key private key to use for the signing
2085  * @param hash the hash of the message to sign
2086  * @return NULL on error, including a malicious RSA key, signature on success
2087  */
2088 struct GNUNET_CRYPTO_RsaSignature *
2089 GNUNET_CRYPTO_rsa_sign_fdh (const struct GNUNET_CRYPTO_RsaPrivateKey *key,
2090                             const struct GNUNET_HashCode *hash);
2091
2092
2093 /**
2094  * Free memory occupied by signature.
2095  *
2096  * @param sig memory to free
2097  */
2098 void
2099 GNUNET_CRYPTO_rsa_signature_free (struct GNUNET_CRYPTO_RsaSignature *sig);
2100
2101
2102 /**
2103  * Encode the given signature in a format suitable for storing it into a file.
2104  *
2105  * @param sig the signature
2106  * @param[out] buffer set to a buffer with the encoded key
2107  * @return size of memory allocated in @a buffer
2108  */
2109 size_t
2110 GNUNET_CRYPTO_rsa_signature_encode (
2111   const struct GNUNET_CRYPTO_RsaSignature *sig,
2112   char **buffer);
2113
2114
2115 /**
2116  * Decode the signature from the data-format back to the "normal", internal
2117  * format.
2118  *
2119  * @param buf the buffer where the public key data is stored
2120  * @param len the length of the data in @a buf
2121  * @return NULL on error
2122  */
2123 struct GNUNET_CRYPTO_RsaSignature *
2124 GNUNET_CRYPTO_rsa_signature_decode (const char *buf, size_t len);
2125
2126
2127 /**
2128  * Duplicate the given rsa signature
2129  *
2130  * @param sig the signature to duplicate
2131  * @return the duplicate key; NULL upon error
2132  */
2133 struct GNUNET_CRYPTO_RsaSignature *
2134 GNUNET_CRYPTO_rsa_signature_dup (const struct GNUNET_CRYPTO_RsaSignature *sig);
2135
2136
2137 /**
2138  * Unblind a blind-signed signature.  The signature should have been generated
2139  * with #GNUNET_CRYPTO_rsa_sign() using a hash that was blinded with
2140  * #GNUNET_CRYPTO_rsa_blind().
2141  *
2142  * @param sig the signature made on the blinded signature purpose
2143  * @param bks the blinding key secret used to blind the signature purpose
2144  * @param pkey the public key of the signer
2145  * @return unblinded signature on success, NULL if RSA key is bad or malicious.
2146  */
2147 struct GNUNET_CRYPTO_RsaSignature *
2148 GNUNET_CRYPTO_rsa_unblind (const struct GNUNET_CRYPTO_RsaSignature *sig,
2149                            const struct GNUNET_CRYPTO_RsaBlindingKeySecret *bks,
2150                            struct GNUNET_CRYPTO_RsaPublicKey *pkey);
2151
2152
2153 /**
2154  * Verify whether the given hash corresponds to the given signature and the
2155  * signature is valid with respect to the given public key.
2156  *
2157  * @param hash the message to verify to match the @a sig
2158  * @param sig signature that is being validated
2159  * @param public_key public key of the signer
2160  * @returns #GNUNET_YES if ok, #GNUNET_NO if RSA key is malicious, #GNUNET_SYSERR if signature
2161  */
2162 int
2163 GNUNET_CRYPTO_rsa_verify (const struct GNUNET_HashCode *hash,
2164                           const struct GNUNET_CRYPTO_RsaSignature *sig,
2165                           const struct GNUNET_CRYPTO_RsaPublicKey *public_key);
2166
2167
2168 #if 0 /* keep Emacsens' auto-indent happy */
2169 {
2170 #endif
2171 #ifdef __cplusplus
2172 }
2173 #endif
2174
2175
2176 /* ifndef GNUNET_CRYPTO_LIB_H */
2177 #endif
2178 /* end of gnunet_crypto_lib.h */