src/include/gnunet_crypto_lib.h

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