2 This file is part of GNUnet.
3 Copyright (C) 2001-2013 Christian Grothoff (and other contributing authors)
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.
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.
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., 51 Franklin Street, Fifth Floor,
18 Boston, MA 02110-1301, USA.
22 * @file include/gnunet_crypto_lib.h
23 * @brief cryptographic primitives for GNUnet
25 * @author Christian Grothoff
26 * @author Krista Bennett
27 * @author Gerd Knorr <kraxel@bytesex.org>
28 * @author Ioana Patrascu
29 * @author Tzvetan Horozov
31 * @defgroup crypto Crypto library: cryptographic operations
33 * @defgroup hash Crypto library: hash operations
34 * Hashing and operations on hashes
37 #ifndef GNUNET_CRYPTO_LIB_H
38 #define GNUNET_CRYPTO_LIB_H
43 #if 0 /* keep Emacsens' auto-indent happy */
49 * @brief A 512-bit hashcode
51 struct GNUNET_HashCode;
54 * The identity of the host (wraps the signing key of the peer).
56 struct GNUNET_PeerIdentity;
58 #include "gnunet_common.h"
63 * @brief A 512-bit hashcode
65 struct GNUNET_HashCode
67 uint32_t bits[512 / 8 / sizeof (uint32_t)]; /* = 16 */
72 * Maximum length of an ECC signature.
73 * Note: round up to multiple of 8 minus 2 for alignment.
75 #define GNUNET_CRYPTO_ECC_SIGNATURE_DATA_ENCODING_LENGTH 126
79 * Desired quality level for random numbers.
82 enum GNUNET_CRYPTO_Quality
85 * No good quality of the operation is needed (i.e.,
86 * random numbers can be pseudo-random).
89 GNUNET_CRYPTO_QUALITY_WEAK,
92 * High-quality operations are desired.
95 GNUNET_CRYPTO_QUALITY_STRONG,
98 * Randomness for IVs etc. is required.
101 GNUNET_CRYPTO_QUALITY_NONCE
106 * @brief length of the sessionkey in bytes (256 BIT sessionkey)
108 #define GNUNET_CRYPTO_AES_KEY_LENGTH (256/8)
111 * Length of a hash value
113 #define GNUNET_CRYPTO_HASH_LENGTH (512/8)
116 * How many characters (without 0-terminator) are our ASCII-encoded
117 * public keys (ECDSA/EDDSA/ECDHE).
119 #define GNUNET_CRYPTO_PKEY_ASCII_LENGTH 52
122 * @brief 0-terminated ASCII encoding of a struct GNUNET_HashCode.
124 struct GNUNET_CRYPTO_HashAsciiEncoded
126 unsigned char encoding[104];
130 GNUNET_NETWORK_STRUCT_BEGIN
134 * @brief header of what an ECC signature signs
135 * this must be followed by "size - 8" bytes of
136 * the actual signed data
138 struct GNUNET_CRYPTO_EccSignaturePurpose
141 * How many bytes does this signature sign?
142 * (including this purpose header); in network
145 uint32_t size GNUNET_PACKED;
148 * What does this signature vouch for? This
149 * must contain a GNUNET_SIGNATURE_PURPOSE_XXX
150 * constant (from gnunet_signatures.h). In
151 * network byte order!
153 uint32_t purpose GNUNET_PACKED;
159 * @brief an ECC signature using EdDSA.
160 * See https://gnunet.org/ed25519
162 struct GNUNET_CRYPTO_EddsaSignature
168 unsigned char r[256 / 8];
173 unsigned char s[256 / 8];
180 * @brief an ECC signature using ECDSA
182 struct GNUNET_CRYPTO_EcdsaSignature
188 unsigned char r[256 / 8];
193 unsigned char s[256 / 8];
199 * Public ECC key (always for Curve25519) encoded in a format suitable
200 * for network transmission and EdDSA signatures.
202 struct GNUNET_CRYPTO_EddsaPublicKey
205 * Q consists of an x- and a y-value, each mod p (256 bits), given
206 * here in affine coordinates and Ed25519 standard compact format.
208 unsigned char q_y[256 / 8];
214 * Public ECC key (always for Curve25519) encoded in a format suitable
215 * for network transmission and ECDSA signatures.
217 struct GNUNET_CRYPTO_EcdsaPublicKey
220 * Q consists of an x- and a y-value, each mod p (256 bits), given
221 * here in affine coordinates and Ed25519 standard compact format.
223 unsigned char q_y[256 / 8];
229 * The identity of the host (wraps the signing key of the peer).
231 struct GNUNET_PeerIdentity
233 struct GNUNET_CRYPTO_EddsaPublicKey public_key;
238 * Public ECC key (always for Curve25519) encoded in a format suitable
239 * for network transmission and encryption (ECDH),
240 * See http://cr.yp.to/ecdh.html
242 struct GNUNET_CRYPTO_EcdhePublicKey
245 * Q consists of an x- and a y-value, each mod p (256 bits), given
246 * here in affine coordinates and Ed25519 standard compact format.
248 unsigned char q_y[256 / 8];
253 * Private ECC key encoded for transmission. To be used only for ECDH
254 * key exchange (ECDHE to be precise).
256 struct GNUNET_CRYPTO_EcdhePrivateKey
259 * d is a value mod n, where n has at most 256 bits.
261 unsigned char d[256 / 8];
266 * Private ECC key encoded for transmission. To be used only for ECDSA
269 struct GNUNET_CRYPTO_EcdsaPrivateKey
272 * d is a value mod n, where n has at most 256 bits.
274 unsigned char d[256 / 8];
279 * Private ECC key encoded for transmission. To be used only for EdDSA
282 struct GNUNET_CRYPTO_EddsaPrivateKey
285 * d is a value mod n, where n has at most 256 bits.
287 unsigned char d[256 / 8];
293 * @brief type for session keys
295 struct GNUNET_CRYPTO_SymmetricSessionKey
298 * Actual key for AES.
300 unsigned char aes_key[GNUNET_CRYPTO_AES_KEY_LENGTH];
303 * Actual key for TwoFish.
305 unsigned char twofish_key[GNUNET_CRYPTO_AES_KEY_LENGTH];
309 GNUNET_NETWORK_STRUCT_END
312 * @brief IV for sym cipher
314 * NOTE: must be smaller (!) in size than the
315 * `struct GNUNET_HashCode`.
317 struct GNUNET_CRYPTO_SymmetricInitializationVector
319 unsigned char aes_iv[GNUNET_CRYPTO_AES_KEY_LENGTH / 2];
321 unsigned char twofish_iv[GNUNET_CRYPTO_AES_KEY_LENGTH / 2];
326 * @brief type for (message) authentication keys
328 struct GNUNET_CRYPTO_AuthKey
330 unsigned char key[GNUNET_CRYPTO_HASH_LENGTH];
335 * Size of paillier plain texts and public keys.
336 * Private keys and ciphertexts are twice this size.
338 #define GNUNET_CRYPTO_PAILLIER_BITS 2048
342 * Paillier public key.
344 struct GNUNET_CRYPTO_PaillierPublicKey
349 unsigned char n[GNUNET_CRYPTO_PAILLIER_BITS / 8];
354 * Paillier public key.
356 struct GNUNET_CRYPTO_PaillierPrivateKey
359 * Lambda-component of the private key.
361 unsigned char lambda[GNUNET_CRYPTO_PAILLIER_BITS / 8];
363 * Mu-component of the private key.
365 unsigned char mu[GNUNET_CRYPTO_PAILLIER_BITS / 8];
370 * Paillier ciphertext.
372 struct GNUNET_CRYPTO_PaillierCiphertext
375 * Guaranteed minimum number of homomorphic operations with this ciphertext,
376 * in network byte order (NBO).
378 int32_t remaining_ops GNUNET_PACKED;
381 * The bits of the ciphertext.
383 unsigned char bits[GNUNET_CRYPTO_PAILLIER_BITS * 2 / 8];
387 /* **************** Functions and Macros ************* */
391 * Seed a weak random generator. Only #GNUNET_CRYPTO_QUALITY_WEAK-mode generator
394 * @param seed the seed to use
397 GNUNET_CRYPTO_seed_weak_random (int32_t seed);
401 * Perform an incremental step in a CRC16 (for TCP/IP) calculation.
403 * @param sum current sum, initially 0
404 * @param buf buffer to calculate CRC over (must be 16-bit aligned)
405 * @param len number of bytes in @a buf, must be multiple of 2
406 * @return updated crc sum (must be subjected to #GNUNET_CRYPTO_crc16_finish to get actual crc16)
409 GNUNET_CRYPTO_crc16_step (uint32_t sum,
415 * Convert results from GNUNET_CRYPTO_crc16_step to final crc16.
417 * @param sum cummulative sum
418 * @return crc16 value
421 GNUNET_CRYPTO_crc16_finish (uint32_t sum);
426 * Calculate the checksum of a buffer in one step.
428 * @param buf buffer to calculate CRC over (must be 16-bit aligned)
429 * @param len number of bytes in @a buf, must be multiple of 2
430 * @return crc16 value
433 GNUNET_CRYPTO_crc16_n (const void *buf,
439 * Compute the CRC32 checksum for the first len
440 * bytes of the buffer.
442 * @param buf the data over which we're taking the CRC
443 * @param len the length of the buffer @a buf in bytes
444 * @return the resulting CRC32 checksum
447 GNUNET_CRYPTO_crc32_n (const void *buf,
453 * Fill block with a random values.
455 * @param mode desired quality of the random number
456 * @param buffer the buffer to fill
457 * @param length buffer length
460 GNUNET_CRYPTO_random_block (enum GNUNET_CRYPTO_Quality mode,
466 * Produce a random value.
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).
473 GNUNET_CRYPTO_random_u32 (enum GNUNET_CRYPTO_Quality mode,
479 * Random on unsigned 64-bit values.
481 * @param mode desired quality of the random number
482 * @param max value returned will be in range [0,@a max) (exclusive)
483 * @return random 64-bit number
486 GNUNET_CRYPTO_random_u64 (enum GNUNET_CRYPTO_Quality mode,
492 * Get an array with a random permutation of the
494 * @param mode #GNUNET_CRYPTO_QUALITY_STRONG if the strong (but expensive) PRNG should be used,
495 * #GNUNET_CRYPTO_QUALITY_WEAK or #GNUNET_CRYPTO_QUALITY_NONCE otherwise
496 * @param n the size of the array
497 * @return the permutation array (allocated from heap)
500 GNUNET_CRYPTO_random_permute (enum GNUNET_CRYPTO_Quality mode,
506 * Create a new random session key.
508 * @param key key to initialize
511 GNUNET_CRYPTO_symmetric_create_session_key (struct GNUNET_CRYPTO_SymmetricSessionKey *key);
516 * Encrypt a block using a symmetric sessionkey.
518 * @param block the block to encrypt
519 * @param size the size of the @a block
520 * @param sessionkey the key used to encrypt
521 * @param iv the initialization vector to use, use INITVALUE
523 * @return the size of the encrypted block, -1 for errors
526 GNUNET_CRYPTO_symmetric_encrypt (const void *block,
528 const struct GNUNET_CRYPTO_SymmetricSessionKey *sessionkey,
529 const struct GNUNET_CRYPTO_SymmetricInitializationVector *iv,
535 * Decrypt a given block using a symmetric sessionkey.
537 * @param block the data to decrypt, encoded as returned by encrypt
538 * @param size how big is the block?
539 * @param sessionkey the key used to decrypt
540 * @param iv the initialization vector to use
541 * @param result address to store the result at
542 * @return -1 on failure, size of decrypted block on success
545 GNUNET_CRYPTO_symmetric_decrypt (const void *block,
547 const struct GNUNET_CRYPTO_SymmetricSessionKey *sessionkey,
548 const struct GNUNET_CRYPTO_SymmetricInitializationVector *iv,
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
562 GNUNET_CRYPTO_symmetric_derive_iv (struct GNUNET_CRYPTO_SymmetricInitializationVector *iv,
563 const struct GNUNET_CRYPTO_SymmetricSessionKey *skey,
565 size_t salt_len, ...);
569 * @brief Derive an IV
570 * @param iv initialization vector
571 * @param skey session key
572 * @param salt salt for the derivation
573 * @param salt_len size of the @a salt
574 * @param argp pairs of void * & size_t for context chunks, terminated by NULL
577 GNUNET_CRYPTO_symmetric_derive_iv_v (struct GNUNET_CRYPTO_SymmetricInitializationVector *iv,
578 const struct GNUNET_CRYPTO_SymmetricSessionKey *skey,
586 * Convert hash to ASCII encoding.
587 * @param block the hash code
588 * @param result where to store the encoding (struct GNUNET_CRYPTO_HashAsciiEncoded can be
589 * safely cast to char*, a '\\0' termination is set).
592 GNUNET_CRYPTO_hash_to_enc (const struct GNUNET_HashCode *block,
593 struct GNUNET_CRYPTO_HashAsciiEncoded *result);
598 * Convert ASCII encoding back to a 'struct GNUNET_HashCode'
600 * @param enc the encoding
601 * @param enclen number of characters in @a enc (without 0-terminator, which can be missing)
602 * @param result where to store the hash code
603 * @return #GNUNET_OK on success, #GNUNET_SYSERR if result has the wrong encoding
606 GNUNET_CRYPTO_hash_from_string2 (const char *enc,
608 struct GNUNET_HashCode *result);
613 * Convert ASCII encoding back to `struct GNUNET_HashCode`
615 * @param enc the encoding
616 * @param result where to store the hash code
617 * @return #GNUNET_OK on success, #GNUNET_SYSERR if result has the wrong encoding
619 #define GNUNET_CRYPTO_hash_from_string(enc, result) \
620 GNUNET_CRYPTO_hash_from_string2 (enc, strlen(enc), result)
626 * Compute the distance between 2 hashcodes. The
627 * computation must be fast, not involve @a a[0] or @a a[4] (they're used
628 * elsewhere), and be somewhat consistent. And of course, the result
629 * should be a positive number.
631 * @param a some hash code
632 * @param b some hash code
633 * @return number between 0 and UINT32_MAX
636 GNUNET_CRYPTO_hash_distance_u32 (const struct GNUNET_HashCode *a,
637 const struct GNUNET_HashCode *b);
642 * Compute hash of a given block.
644 * @param block the data to hash
645 * @param size size of the @a block
646 * @param ret pointer to where to write the hashcode
649 GNUNET_CRYPTO_hash (const void *block,
651 struct GNUNET_HashCode *ret);
655 * Context for cummulative hashing.
657 struct GNUNET_HashContext;
661 * Start incremental hashing operation.
663 * @return context for incremental hash computation
665 struct GNUNET_HashContext *
666 GNUNET_CRYPTO_hash_context_start (void);
670 * Add data to be hashed.
672 * @param hc cummulative hash context
673 * @param buf data to add
674 * @param size number of bytes in @a buf
677 GNUNET_CRYPTO_hash_context_read (struct GNUNET_HashContext *hc,
683 * Finish the hash computation.
685 * @param hc hash context to use, is freed in the process
686 * @param r_hash where to write the latest / final hash code
689 GNUNET_CRYPTO_hash_context_finish (struct GNUNET_HashContext *hc,
690 struct GNUNET_HashCode *r_hash);
694 * Abort hashing, do not bother calculating final result.
696 * @param hc hash context to destroy
699 GNUNET_CRYPTO_hash_context_abort (struct GNUNET_HashContext *hc);
704 * Calculate HMAC of a message (RFC 2104)
706 * @param key secret key
707 * @param plaintext input plaintext
708 * @param plaintext_len length of @a plaintext
709 * @param hmac where to store the hmac
712 GNUNET_CRYPTO_hmac (const struct GNUNET_CRYPTO_AuthKey *key,
713 const void *plaintext,
714 size_t plaintext_len,
715 struct GNUNET_HashCode *hmac);
719 * Function called once the hash computation over the
720 * specified file has completed.
723 * @param res resulting hash, NULL on error
726 (*GNUNET_CRYPTO_HashCompletedCallback) (void *cls,
727 const struct GNUNET_HashCode *res);
731 * Handle to file hashing operation.
733 struct GNUNET_CRYPTO_FileHashContext;
738 * Compute the hash of an entire file.
740 * @param priority scheduling priority to use
741 * @param filename name of file to hash
742 * @param blocksize number of bytes to process in one task
743 * @param callback function to call upon completion
744 * @param callback_cls closure for @a callback
745 * @return NULL on (immediate) errror
747 struct GNUNET_CRYPTO_FileHashContext *
748 GNUNET_CRYPTO_hash_file (enum GNUNET_SCHEDULER_Priority priority,
749 const char *filename,
751 GNUNET_CRYPTO_HashCompletedCallback callback,
756 * Cancel a file hashing operation.
758 * @param fhc operation to cancel (callback must not yet have been invoked)
761 GNUNET_CRYPTO_hash_file_cancel (struct GNUNET_CRYPTO_FileHashContext *fhc);
766 * Create a random hash code.
768 * @param mode desired quality level
769 * @param result hash code that is randomized
772 GNUNET_CRYPTO_hash_create_random (enum GNUNET_CRYPTO_Quality mode,
773 struct GNUNET_HashCode *result);
778 * compute @a result = @a b - @a a
780 * @param a some hash code
781 * @param b some hash code
782 * @param result set to @a b - @a a
785 GNUNET_CRYPTO_hash_difference (const struct GNUNET_HashCode *a,
786 const struct GNUNET_HashCode *b,
787 struct GNUNET_HashCode *result);
792 * compute @a result = @a a + @a delta
794 * @param a some hash code
795 * @param delta some hash code
796 * @param result set to @a a + @a delta
799 GNUNET_CRYPTO_hash_sum (const struct GNUNET_HashCode *a,
800 const struct GNUNET_HashCode *delta,
801 struct GNUNET_HashCode *result);
806 * compute result = a ^ b
808 * @param a some hash code
809 * @param b some hash code
810 * @param result set to @a a ^ @a b
813 GNUNET_CRYPTO_hash_xor (const struct GNUNET_HashCode *a,
814 const struct GNUNET_HashCode *b,
815 struct GNUNET_HashCode *result);
820 * Convert a hashcode into a key.
822 * @param hc hash code that serves to generate the key
823 * @param skey set to a valid session key
824 * @param iv set to a valid initialization vector
827 GNUNET_CRYPTO_hash_to_aes_key (const struct GNUNET_HashCode * hc,
828 struct GNUNET_CRYPTO_SymmetricSessionKey *skey,
829 struct GNUNET_CRYPTO_SymmetricInitializationVector *iv);
834 * Obtain a bit from a hashcode.
836 * @param code the `struct GNUNET_HashCode` to index bit-wise
837 * @param bit index into the hashcode, [0...159]
838 * @return Bit \a bit from hashcode \a code, -1 for invalid index
841 GNUNET_CRYPTO_hash_get_bit (const struct GNUNET_HashCode *code,
847 * Determine how many low order bits match in two
848 * `struct GNUNET_HashCodes`. i.e. - 010011 and 011111 share
849 * the first two lowest order bits, and therefore the
850 * return value is two (NOT XOR distance, nor how many
851 * bits match absolutely!).
853 * @param first the first hashcode
854 * @param second the hashcode to compare first to
855 * @return the number of bits that match
858 GNUNET_CRYPTO_hash_matching_bits (const struct GNUNET_HashCode *first,
859 const struct GNUNET_HashCode *second);
864 * Compare function for HashCodes, producing a total ordering
867 * @param h1 some hash code
868 * @param h2 some hash code
869 * @return 1 if @a h1 > @a h2, -1 if @a h1 < @a h2 and 0 if @a h1 == @a h2.
872 GNUNET_CRYPTO_hash_cmp (const struct GNUNET_HashCode *h1,
873 const struct GNUNET_HashCode *h2);
878 * Find out which of the two GNUNET_CRYPTO_hash codes is closer to target
879 * in the XOR metric (Kademlia).
881 * @param h1 some hash code
882 * @param h2 some hash code
883 * @param target some hash code
884 * @return -1 if @a h1 is closer, 1 if @a h2 is closer and 0 if @a h1== @a h2.
887 GNUNET_CRYPTO_hash_xorcmp (const struct GNUNET_HashCode *h1,
888 const struct GNUNET_HashCode *h2,
889 const struct GNUNET_HashCode *target);
894 * @brief Derive an authentication key
895 * @param key authentication key
896 * @param rkey root key
898 * @param salt_len size of the salt
899 * @param argp pair of void * & size_t for context chunks, terminated by NULL
902 GNUNET_CRYPTO_hmac_derive_key_v (struct GNUNET_CRYPTO_AuthKey *key,
903 const struct GNUNET_CRYPTO_SymmetricSessionKey *rkey,
904 const void *salt, size_t salt_len,
910 * @brief Derive an authentication key
911 * @param key authentication key
912 * @param rkey root key
914 * @param salt_len size of the salt
915 * @param ... pair of void * & size_t for context chunks, terminated by NULL
918 GNUNET_CRYPTO_hmac_derive_key (struct GNUNET_CRYPTO_AuthKey *key,
919 const struct GNUNET_CRYPTO_SymmetricSessionKey *rkey,
920 const void *salt, size_t salt_len,
927 * @param result buffer for the derived key, allocated by caller
928 * @param out_len desired length of the derived key
929 * @param xtr_algo hash algorithm for the extraction phase, GCRY_MD_...
930 * @param prf_algo hash algorithm for the expansion phase, GCRY_MD_...
932 * @param xts_len length of @a xts
933 * @param skm source key material
934 * @param skm_len length of @a skm
935 * @param ... pair of void * & size_t for context chunks, terminated by NULL
936 * @return #GNUNET_YES on success
939 GNUNET_CRYPTO_hkdf (void *result,
953 * @param result buffer for the derived key, allocated by caller
954 * @param out_len desired length of the derived key
955 * @param xtr_algo hash algorithm for the extraction phase, GCRY_MD_...
956 * @param prf_algo hash algorithm for the expansion phase, GCRY_MD_...
958 * @param xts_len length of @a xts
959 * @param skm source key material
960 * @param skm_len length of @a skm
961 * @param argp va_list of void * & size_t pairs for context chunks
962 * @return #GNUNET_YES on success
965 GNUNET_CRYPTO_hkdf_v (void *result,
978 * @param result buffer for the derived key, allocated by caller
979 * @param out_len desired length of the derived key
981 * @param xts_len length of @a xts
982 * @param skm source key material
983 * @param skm_len length of @a skm
984 * @param argp va_list of void * & size_t pairs for context chunks
985 * @return #GNUNET_YES on success
988 GNUNET_CRYPTO_kdf_v (void *result,
1000 * @param result buffer for the derived key, allocated by caller
1001 * @param out_len desired length of the derived key
1003 * @param xts_len length of @a xts
1004 * @param skm source key material
1005 * @param skm_len length of @a skm
1006 * @param ... void * & size_t pairs for context chunks
1007 * @return #GNUNET_YES on success
1010 GNUNET_CRYPTO_kdf (void *result,
1021 * Extract the public key for the given private key.
1023 * @param priv the private key
1024 * @param pub where to write the public key
1027 GNUNET_CRYPTO_ecdsa_key_get_public (const struct GNUNET_CRYPTO_EcdsaPrivateKey *priv,
1028 struct GNUNET_CRYPTO_EcdsaPublicKey *pub);
1032 * Extract the public key for the given private key.
1034 * @param priv the private key
1035 * @param pub where to write the public key
1038 GNUNET_CRYPTO_eddsa_key_get_public (const struct GNUNET_CRYPTO_EddsaPrivateKey *priv,
1039 struct GNUNET_CRYPTO_EddsaPublicKey *pub);
1045 * Extract the public key for the given private key.
1047 * @param priv the private key
1048 * @param pub where to write the public key
1051 GNUNET_CRYPTO_ecdhe_key_get_public (const struct GNUNET_CRYPTO_EcdhePrivateKey *priv,
1052 struct GNUNET_CRYPTO_EcdhePublicKey *pub);
1056 * Convert a public key to a string.
1058 * @param pub key to convert
1059 * @return string representing @a pub
1062 GNUNET_CRYPTO_ecdsa_public_key_to_string (const struct GNUNET_CRYPTO_EcdsaPublicKey *pub);
1066 * Convert a public key to a string.
1068 * @param pub key to convert
1069 * @return string representing @a pub
1072 GNUNET_CRYPTO_eddsa_public_key_to_string (const struct GNUNET_CRYPTO_EddsaPublicKey *pub);
1076 * Convert a string representing a public key to a public key.
1078 * @param enc encoded public key
1079 * @param enclen number of bytes in @a enc (without 0-terminator)
1080 * @param pub where to store the public key
1081 * @return #GNUNET_OK on success
1084 GNUNET_CRYPTO_ecdsa_public_key_from_string (const char *enc,
1086 struct GNUNET_CRYPTO_EcdsaPublicKey *pub);
1090 * Convert a string representing a private key to a private key.
1092 * @param enc encoded public key
1093 * @param enclen number of bytes in @a enc (without 0-terminator)
1094 * @param priv where to store the private key
1095 * @return #GNUNET_OK on success
1098 GNUNET_CRYPTO_eddsa_private_key_from_string (const char *enc,
1100 struct GNUNET_CRYPTO_EddsaPrivateKey *pub);
1104 * Convert a string representing a public key to a public key.
1106 * @param enc encoded public key
1107 * @param enclen number of bytes in @a enc (without 0-terminator)
1108 * @param pub where to store the public key
1109 * @return #GNUNET_OK on success
1112 GNUNET_CRYPTO_eddsa_public_key_from_string (const char *enc,
1114 struct GNUNET_CRYPTO_EddsaPublicKey *pub);
1119 * Create a new private key by reading it from a file. If the
1120 * files does not exist, create a new key and write it to the
1121 * file. Caller must free return value. Note that this function
1122 * can not guarantee that another process might not be trying
1123 * the same operation on the same file at the same time.
1124 * If the contents of the file
1125 * are invalid the old file is deleted and a fresh key is
1128 * @param filename name of file to use to store the key
1129 * @return new private key, NULL on error (for example,
1130 * permission denied); free using #GNUNET_free
1132 struct GNUNET_CRYPTO_EcdsaPrivateKey *
1133 GNUNET_CRYPTO_ecdsa_key_create_from_file (const char *filename);
1138 * Create a new private key by reading it from a file. If the
1139 * files does not exist, create a new key and write it to the
1140 * file. Caller must free return value. Note that this function
1141 * can not guarantee that another process might not be trying
1142 * the same operation on the same file at the same time.
1143 * If the contents of the file
1144 * are invalid the old file is deleted and a fresh key is
1147 * @param filename name of file to use to store the key
1148 * @return new private key, NULL on error (for example,
1149 * permission denied); free using #GNUNET_free
1151 struct GNUNET_CRYPTO_EddsaPrivateKey *
1152 GNUNET_CRYPTO_eddsa_key_create_from_file (const char *filename);
1156 * Forward declaration to simplify #include-structure.
1158 struct GNUNET_CONFIGURATION_Handle;
1163 * Create a new private key by reading our peer's key from
1164 * the file specified in the configuration.
1166 * @param cfg the configuration to use
1167 * @return new private key, NULL on error (for example,
1168 * permission denied); free using #GNUNET_free
1170 struct GNUNET_CRYPTO_EddsaPrivateKey *
1171 GNUNET_CRYPTO_eddsa_key_create_from_configuration (const struct GNUNET_CONFIGURATION_Handle *cfg);
1176 * Create a new private key. Caller must free return value.
1178 * @return fresh private key; free using #GNUNET_free
1180 struct GNUNET_CRYPTO_EcdsaPrivateKey *
1181 GNUNET_CRYPTO_ecdsa_key_create (void);
1186 * Create a new private key. Caller must free return value.
1188 * @return fresh private key; free using #GNUNET_free
1190 struct GNUNET_CRYPTO_EddsaPrivateKey *
1191 GNUNET_CRYPTO_eddsa_key_create (void);
1196 * Create a new private key. Caller must free return value.
1198 * @return fresh private key; free using #GNUNET_free
1200 struct GNUNET_CRYPTO_EcdhePrivateKey *
1201 GNUNET_CRYPTO_ecdhe_key_create (void);
1206 * Clear memory that was used to store a private key.
1208 * @param pk location of the key
1211 GNUNET_CRYPTO_eddsa_key_clear (struct GNUNET_CRYPTO_EddsaPrivateKey *pk);
1216 * Clear memory that was used to store a private key.
1218 * @param pk location of the key
1221 GNUNET_CRYPTO_ecdsa_key_clear (struct GNUNET_CRYPTO_EcdsaPrivateKey *pk);
1226 * Clear memory that was used to store a private key.
1228 * @param pk location of the key
1231 GNUNET_CRYPTO_ecdhe_key_clear (struct GNUNET_CRYPTO_EcdhePrivateKey *pk);
1236 * Get the shared private key we use for anonymous users.
1238 * @return "anonymous" private key; do not free
1240 const struct GNUNET_CRYPTO_EcdsaPrivateKey *
1241 GNUNET_CRYPTO_ecdsa_key_get_anonymous (void);
1246 * Setup a hostkey file for a peer given the name of the
1247 * configuration file (!). This function is used so that
1248 * at a later point code can be certain that reading a
1249 * hostkey is fast (for example in time-dependent testcases).
1251 * @param cfg_name name of the configuration file to use
1254 GNUNET_CRYPTO_eddsa_setup_hostkey (const char *cfg_name);
1259 * Retrieve the identity of the host's peer.
1261 * @param cfg configuration to use
1262 * @param dst pointer to where to write the peer identity
1263 * @return #GNUNET_OK on success, #GNUNET_SYSERR if the identity
1264 * could not be retrieved
1267 GNUNET_CRYPTO_get_peer_identity (const struct GNUNET_CONFIGURATION_Handle *cfg,
1268 struct GNUNET_PeerIdentity *dst);
1272 * Compare two Peer Identities.
1274 * @param first first peer identity
1275 * @param second second peer identity
1276 * @return bigger than 0 if first > second,
1277 * 0 if they are the same
1278 * smaller than 0 if second > first
1281 GNUNET_CRYPTO_cmp_peer_identity (const struct GNUNET_PeerIdentity *first,
1282 const struct GNUNET_PeerIdentity *second);
1286 * Internal structure used to cache pre-calculated values for DLOG calculation.
1288 struct GNUNET_CRYPTO_EccDlogContext;
1292 * Point on a curve (always for Curve25519) encoded in a format suitable
1293 * for network transmission (ECDH), see http://cr.yp.to/ecdh.html.
1295 struct GNUNET_CRYPTO_EccPoint
1298 * Q consists of an x- and a y-value, each mod p (256 bits), given
1299 * here in affine coordinates and Ed25519 standard compact format.
1301 unsigned char q_y[256 / 8];
1306 * Do pre-calculation for ECC discrete logarithm for small factors.
1308 * @param max maximum value the factor can be
1309 * @param mem memory to use (should be smaller than @a max), must not be zero.
1310 * @return @a max if dlog failed, otherwise the factor
1312 struct GNUNET_CRYPTO_EccDlogContext *
1313 GNUNET_CRYPTO_ecc_dlog_prepare (unsigned int max,
1318 * Calculate ECC discrete logarithm for small factors.
1319 * Opposite of #GNUNET_CRYPTO_ecc_dexp().
1321 * @param dlc precalculated values, determine range of factors
1322 * @param input point on the curve to factor
1323 * @return `dlc->max` if dlog failed, otherwise the factor
1326 GNUNET_CRYPTO_ecc_dlog (struct GNUNET_CRYPTO_EccDlogContext *edc,
1327 gcry_mpi_point_t input);
1331 * Multiply the generator g of the elliptic curve by @a val
1332 * to obtain the point on the curve representing @a val.
1333 * Afterwards, point addition will correspond to integer
1334 * addition. #GNUNET_CRYPTO_ecc_dlog() can be used to
1335 * convert a point back to an integer (as long as the
1336 * integer is smaller than the MAX of the @a edc context).
1338 * @param edc calculation context for ECC operations
1339 * @param val value to encode into a point
1340 * @return representation of the value as an ECC point,
1341 * must be freed using #GNUNET_CRYPTO_ecc_free()
1344 GNUNET_CRYPTO_ecc_dexp (struct GNUNET_CRYPTO_EccDlogContext *edc,
1349 * Multiply the generator g of the elliptic curve by @a val
1350 * to obtain the point on the curve representing @a val.
1352 * @param edc calculation context for ECC operations
1353 * @param val (positive) value to encode into a point
1354 * @return representation of the value as an ECC point,
1355 * must be freed using #GNUNET_CRYPTO_ecc_free()
1358 GNUNET_CRYPTO_ecc_dexp_mpi (struct GNUNET_CRYPTO_EccDlogContext *edc,
1363 * Multiply the point @a p on the elliptic curve by @a val.
1365 * @param edc calculation context for ECC operations
1366 * @param p point to multiply
1367 * @param val (positive) value to encode into a point
1368 * @return representation of the value as an ECC point,
1369 * must be freed using #GNUNET_CRYPTO_ecc_free()
1372 GNUNET_CRYPTO_ecc_pmul_mpi (struct GNUNET_CRYPTO_EccDlogContext *edc,
1378 * Convert point value to binary representation.
1380 * @param edc calculation context for ECC operations
1381 * @param point computational point representation
1382 * @param[out] bin binary point representation
1385 GNUNET_CRYPTO_ecc_point_to_bin (struct GNUNET_CRYPTO_EccDlogContext *edc,
1386 gcry_mpi_point_t point,
1387 struct GNUNET_CRYPTO_EccPoint *bin);
1391 * Convert binary representation of a point to computational representation.
1393 * @param edc calculation context for ECC operations
1394 * @param bin binary point representation
1395 * @return computational representation
1398 GNUNET_CRYPTO_ecc_bin_to_point (struct GNUNET_CRYPTO_EccDlogContext *edc,
1399 const struct GNUNET_CRYPTO_EccPoint *bin);
1403 * Add two points on the elliptic curve.
1405 * @param edc calculation context for ECC operations
1406 * @param a some value
1407 * @param b some value
1408 * @return @a a + @a b, must be freed using #GNUNET_CRYPTO_ecc_free()
1411 GNUNET_CRYPTO_ecc_add (struct GNUNET_CRYPTO_EccDlogContext *edc,
1413 gcry_mpi_point_t b);
1417 * Obtain a random point on the curve and its
1418 * additive inverse. Both returned values
1419 * must be freed using #GNUNET_CRYPTO_ecc_free().
1421 * @param edc calculation context for ECC operations
1422 * @param[out] r set to a random point on the curve
1423 * @param[out] r_inv set to the additive inverse of @a r
1426 GNUNET_CRYPTO_ecc_rnd (struct GNUNET_CRYPTO_EccDlogContext *edc,
1427 gcry_mpi_point_t *r,
1428 gcry_mpi_point_t *r_inv);
1432 * Obtain a random scalar for point multiplication on the curve and
1433 * its multiplicative inverse.
1435 * @param edc calculation context for ECC operations
1436 * @param[out] r set to a random scalar on the curve
1437 * @param[out] r_inv set to the multiplicative inverse of @a r
1440 GNUNET_CRYPTO_ecc_rnd_mpi (struct GNUNET_CRYPTO_EccDlogContext *edc,
1446 * Generate a random value mod n.
1448 * @param edc ECC context
1449 * @return random value mod n.
1452 GNUNET_CRYPTO_ecc_random_mod_n (struct GNUNET_CRYPTO_EccDlogContext *edc);
1456 * Free a point value returned by the API.
1458 * @param p point to free
1461 GNUNET_CRYPTO_ecc_free (gcry_mpi_point_t p);
1465 * Release precalculated values.
1467 * @param dlc dlog context
1470 GNUNET_CRYPTO_ecc_dlog_release (struct GNUNET_CRYPTO_EccDlogContext *dlc);
1475 * Derive key material from a public and a private ECC key.
1477 * @param priv private key to use for the ECDH (x)
1478 * @param pub public key to use for the ECDH (yG)
1479 * @param key_material where to write the key material (xyG)
1480 * @return #GNUNET_SYSERR on error, #GNUNET_OK on success
1483 GNUNET_CRYPTO_ecc_ecdh (const struct GNUNET_CRYPTO_EcdhePrivateKey *priv,
1484 const struct GNUNET_CRYPTO_EcdhePublicKey *pub,
1485 struct GNUNET_HashCode *key_material);
1490 * Derive key material from a ECDH public key and a private EdDSA key.
1491 * Dual to #GNUNET_CRRYPTO_ecdh_eddsa.
1493 * @param priv private key from EdDSA to use for the ECDH (x)
1494 * @param pub public key to use for the ECDH (yG)
1495 * @param key_material where to write the key material H(h(x)yG)
1496 * @return #GNUNET_SYSERR on error, #GNUNET_OK on success
1499 GNUNET_CRYPTO_eddsa_ecdh (const struct GNUNET_CRYPTO_EddsaPrivateKey *priv,
1500 const struct GNUNET_CRYPTO_EcdhePublicKey *pub,
1501 struct GNUNET_HashCode *key_material);
1505 * Derive key material from a ECDH public key and a private ECDSA key.
1506 * Dual to #GNUNET_CRRYPTO_ecdh_ecdsa.
1508 * @param priv private key from ECDSA to use for the ECDH (x)
1509 * @param pub public key to use for the ECDH (yG)
1510 * @param key_material where to write the key material H(h(x)yG)
1511 * @return #GNUNET_SYSERR on error, #GNUNET_OK on success
1514 GNUNET_CRYPTO_ecdsa_ecdh (const struct GNUNET_CRYPTO_EcdsaPrivateKey *priv,
1515 const struct GNUNET_CRYPTO_EcdhePublicKey *pub,
1516 struct GNUNET_HashCode *key_material);
1521 * Derive key material from a EdDSA public key and a private ECDH key.
1522 * Dual to #GNUNET_CRRYPTO_eddsa_ecdh.
1524 * @param priv private key to use for the ECDH (y)
1525 * @param pub public key from EdDSA to use for the ECDH (X=h(x)G)
1526 * @param key_material where to write the key material H(yX)=H(h(x)yG)
1527 * @return #GNUNET_SYSERR on error, #GNUNET_OK on success
1530 GNUNET_CRYPTO_ecdh_eddsa (const struct GNUNET_CRYPTO_EcdhePrivateKey *priv,
1531 const struct GNUNET_CRYPTO_EddsaPublicKey *pub,
1532 struct GNUNET_HashCode *key_material);
1536 * Derive key material from a EcDSA public key and a private ECDH key.
1537 * Dual to #GNUNET_CRRYPTO_ecdsa_ecdh.
1539 * @param priv private key to use for the ECDH (y)
1540 * @param pub public key from ECDSA to use for the ECDH (X=h(x)G)
1541 * @param key_material where to write the key material H(yX)=H(h(x)yG)
1542 * @return #GNUNET_SYSERR on error, #GNUNET_OK on success
1545 GNUNET_CRYPTO_ecdh_ecdsa (const struct GNUNET_CRYPTO_EcdhePrivateKey *priv,
1546 const struct GNUNET_CRYPTO_EcdsaPublicKey *pub,
1547 struct GNUNET_HashCode *key_material);
1552 * EdDSA sign a given block.
1554 * @param priv private key to use for the signing
1555 * @param purpose what to sign (size, purpose)
1556 * @param sig where to write the signature
1557 * @return #GNUNET_SYSERR on error, #GNUNET_OK on success
1560 GNUNET_CRYPTO_eddsa_sign (const struct GNUNET_CRYPTO_EddsaPrivateKey *priv,
1561 const struct GNUNET_CRYPTO_EccSignaturePurpose *purpose,
1562 struct GNUNET_CRYPTO_EddsaSignature *sig);
1567 * ECDSA Sign a given block.
1569 * @param priv private key to use for the signing
1570 * @param purpose what to sign (size, purpose)
1571 * @param sig where to write the signature
1572 * @return #GNUNET_SYSERR on error, #GNUNET_OK on success
1575 GNUNET_CRYPTO_ecdsa_sign (const struct GNUNET_CRYPTO_EcdsaPrivateKey *priv,
1576 const struct GNUNET_CRYPTO_EccSignaturePurpose *purpose,
1577 struct GNUNET_CRYPTO_EcdsaSignature *sig);
1581 * Verify EdDSA signature.
1583 * @param purpose what is the purpose that the signature should have?
1584 * @param validate block to validate (size, purpose, data)
1585 * @param sig signature that is being validated
1586 * @param pub public key of the signer
1587 * @returns #GNUNET_OK if ok, #GNUNET_SYSERR if invalid
1590 GNUNET_CRYPTO_eddsa_verify (uint32_t purpose,
1591 const struct GNUNET_CRYPTO_EccSignaturePurpose *validate,
1592 const struct GNUNET_CRYPTO_EddsaSignature *sig,
1593 const struct GNUNET_CRYPTO_EddsaPublicKey *pub);
1599 * Verify ECDSA signature.
1601 * @param purpose what is the purpose that the signature should have?
1602 * @param validate block to validate (size, purpose, data)
1603 * @param sig signature that is being validated
1604 * @param pub public key of the signer
1605 * @returns #GNUNET_OK if ok, #GNUNET_SYSERR if invalid
1608 GNUNET_CRYPTO_ecdsa_verify (uint32_t purpose,
1609 const struct GNUNET_CRYPTO_EccSignaturePurpose *validate,
1610 const struct GNUNET_CRYPTO_EcdsaSignature *sig,
1611 const struct GNUNET_CRYPTO_EcdsaPublicKey *pub);
1616 * Derive a private key from a given private key and a label.
1617 * Essentially calculates a private key 'h = H(l,P) * d mod n'
1618 * where n is the size of the ECC group and P is the public
1619 * key associated with the private key 'd'.
1621 * @param priv original private key
1622 * @param label label to use for key deriviation
1623 * @param context additional context to use for HKDF of 'h';
1624 * typically the name of the subsystem/application
1625 * @return derived private key
1627 struct GNUNET_CRYPTO_EcdsaPrivateKey *
1628 GNUNET_CRYPTO_ecdsa_private_key_derive (const struct GNUNET_CRYPTO_EcdsaPrivateKey *priv,
1630 const char *context);
1635 * Derive a public key from a given public key and a label.
1636 * Essentially calculates a public key 'V = H(l,P) * P'.
1638 * @param pub original public key
1639 * @param label label to use for key deriviation
1640 * @param context additional context to use for HKDF of 'h'.
1641 * typically the name of the subsystem/application
1642 * @param result where to write the derived public key
1645 GNUNET_CRYPTO_ecdsa_public_key_derive (const struct GNUNET_CRYPTO_EcdsaPublicKey *pub,
1647 const char *context,
1648 struct GNUNET_CRYPTO_EcdsaPublicKey *result);
1652 * Output the given MPI value to the given buffer in network
1653 * byte order. The MPI @a val may not be negative.
1655 * @param buf where to output to
1656 * @param size number of bytes in @a buf
1657 * @param val value to write to @a buf
1660 GNUNET_CRYPTO_mpi_print_unsigned (void *buf,
1666 * Convert data buffer into MPI value.
1667 * The buffer is interpreted as network
1668 * byte order, unsigned integer.
1670 * @param result where to store MPI value (allocated)
1671 * @param data raw data (GCRYMPI_FMT_USG)
1672 * @param size number of bytes in @a data
1675 GNUNET_CRYPTO_mpi_scan_unsigned (gcry_mpi_t *result,
1681 * Create a freshly generated paillier public key.
1683 * @param[out] public_key Where to store the public key?
1684 * @param[out] private_key Where to store the private key?
1687 GNUNET_CRYPTO_paillier_create (struct GNUNET_CRYPTO_PaillierPublicKey *public_key,
1688 struct GNUNET_CRYPTO_PaillierPrivateKey *private_key);
1692 * Encrypt a plaintext with a paillier public key.
1694 * @param public_key Public key to use.
1695 * @param m Plaintext to encrypt.
1696 * @param desired_ops How many homomorphic ops the caller intends to use
1697 * @param[out] ciphertext Encrytion of @a plaintext with @a public_key.
1698 * @return guaranteed number of supported homomorphic operations >= 1,
1699 * or desired_ops, in case that is lower,
1700 * or -1 if less than one homomorphic operation is possible
1703 GNUNET_CRYPTO_paillier_encrypt (const struct GNUNET_CRYPTO_PaillierPublicKey *public_key,
1706 struct GNUNET_CRYPTO_PaillierCiphertext *ciphertext);
1710 * Decrypt a paillier ciphertext with a private key.
1712 * @param private_key Private key to use for decryption.
1713 * @param public_key Public key to use for decryption.
1714 * @param ciphertext Ciphertext to decrypt.
1715 * @param[out] m Decryption of @a ciphertext with @private_key.
1718 GNUNET_CRYPTO_paillier_decrypt (const struct GNUNET_CRYPTO_PaillierPrivateKey *private_key,
1719 const struct GNUNET_CRYPTO_PaillierPublicKey *public_key,
1720 const struct GNUNET_CRYPTO_PaillierCiphertext *ciphertext,
1725 * Compute a ciphertext that represents the sum of the plaintext in @a x1 and @a x2
1727 * Note that this operation can only be done a finite number of times
1728 * before an overflow occurs.
1730 * @param public_key Public key to use for encryption.
1731 * @param c1 Paillier cipher text.
1732 * @param c2 Paillier cipher text.
1733 * @param[out] result Result of the homomorphic operation.
1734 * @return #GNUNET_OK if the result could be computed,
1735 * #GNUNET_SYSERR if no more homomorphic operations are remaining.
1738 GNUNET_CRYPTO_paillier_hom_add (const struct GNUNET_CRYPTO_PaillierPublicKey *public_key,
1739 const struct GNUNET_CRYPTO_PaillierCiphertext *c1,
1740 const struct GNUNET_CRYPTO_PaillierCiphertext *c2,
1741 struct GNUNET_CRYPTO_PaillierCiphertext *result);
1745 * Get the number of remaining supported homomorphic operations.
1747 * @param c Paillier cipher text.
1748 * @return the number of remaining homomorphic operations
1751 GNUNET_CRYPTO_paillier_hom_get_remaining (const struct GNUNET_CRYPTO_PaillierCiphertext *c);
1754 /* ********* Chaum-style RSA-based blind signatures ******************* */
1760 * The private information of an RSA key pair.
1762 struct GNUNET_CRYPTO_rsa_PrivateKey;
1765 * The public information of an RSA key pair.
1767 struct GNUNET_CRYPTO_rsa_PublicKey;
1770 * Key used to blind a message
1772 struct GNUNET_CRYPTO_rsa_BlindingKey;
1775 * @brief an RSA signature
1777 struct GNUNET_CRYPTO_rsa_Signature;
1781 * Create a new private key. Caller must free return value.
1783 * @param len length of the key in bits (i.e. 2048)
1784 * @return fresh private key
1786 struct GNUNET_CRYPTO_rsa_PrivateKey *
1787 GNUNET_CRYPTO_rsa_private_key_create (unsigned int len);
1791 * Free memory occupied by the private key.
1793 * @param key pointer to the memory to free
1796 GNUNET_CRYPTO_rsa_private_key_free (struct GNUNET_CRYPTO_rsa_PrivateKey *key);
1800 * Encode the private key in a format suitable for
1801 * storing it into a file.
1803 * @param key the private key
1804 * @param[out] buffer set to a buffer with the encoded key
1805 * @return size of memory allocatedin @a buffer
1808 GNUNET_CRYPTO_rsa_private_key_encode (const struct GNUNET_CRYPTO_rsa_PrivateKey *key,
1813 * Decode the private key from the data-format back
1814 * to the "normal", internal format.
1816 * @param buf the buffer where the private key data is stored
1817 * @param len the length of the data in @a buf
1818 * @return NULL on error
1820 struct GNUNET_CRYPTO_rsa_PrivateKey *
1821 GNUNET_CRYPTO_rsa_private_key_decode (const char *buf,
1826 * Duplicate the given private key
1828 * @param key the private key to duplicate
1829 * @return the duplicate key; NULL upon error
1831 struct GNUNET_CRYPTO_rsa_PrivateKey *
1832 GNUNET_CRYPTO_rsa_private_key_dup (const struct GNUNET_CRYPTO_rsa_PrivateKey *key);
1836 * Extract the public key of the given private key.
1838 * @param priv the private key
1839 * @retur NULL on error, otherwise the public key
1841 struct GNUNET_CRYPTO_rsa_PublicKey *
1842 GNUNET_CRYPTO_rsa_private_key_get_public (const struct GNUNET_CRYPTO_rsa_PrivateKey *priv);
1846 * Compute hash over the public key.
1848 * @param key public key to hash
1849 * @param hc where to store the hash code
1852 GNUNET_CRYPTO_rsa_public_key_hash (const struct GNUNET_CRYPTO_rsa_PublicKey *key,
1853 struct GNUNET_HashCode *hc);
1857 * Obtain the length of the RSA key in bits.
1859 * @param key the public key to introspect
1860 * @return length of the key in bits
1863 GNUNET_CRYPTO_rsa_public_key_len (const struct GNUNET_CRYPTO_rsa_PublicKey *key);
1867 * Free memory occupied by the public key.
1869 * @param key pointer to the memory to free
1872 GNUNET_CRYPTO_rsa_public_key_free (struct GNUNET_CRYPTO_rsa_PublicKey *key);
1876 * Encode the public key in a format suitable for
1877 * storing it into a file.
1879 * @param key the private key
1880 * @param[out] buffer set to a buffer with the encoded key
1881 * @return size of memory allocated in @a buffer
1884 GNUNET_CRYPTO_rsa_public_key_encode (const struct GNUNET_CRYPTO_rsa_PublicKey *key,
1889 * Decode the public key from the data-format back
1890 * to the "normal", internal format.
1892 * @param buf the buffer where the public key data is stored
1893 * @param len the length of the data in @a buf
1894 * @return NULL on error
1896 struct GNUNET_CRYPTO_rsa_PublicKey *
1897 GNUNET_CRYPTO_rsa_public_key_decode (const char *buf,
1902 * Duplicate the given public key
1904 * @param key the public key to duplicate
1905 * @return the duplicate key; NULL upon error
1907 struct GNUNET_CRYPTO_rsa_PublicKey *
1908 GNUNET_CRYPTO_rsa_public_key_dup (const struct GNUNET_CRYPTO_rsa_PublicKey *key);
1912 * Create a blinding key
1914 * @param len length of the key in bits (i.e. 2048)
1915 * @return the newly created blinding key
1917 struct GNUNET_CRYPTO_rsa_BlindingKey *
1918 GNUNET_CRYPTO_rsa_blinding_key_create (unsigned int len);
1922 * Compare the values of two blinding keys.
1925 * @param b2 the other key
1926 * @return 0 if the two are equal
1929 GNUNET_CRYPTO_rsa_blinding_key_cmp (struct GNUNET_CRYPTO_rsa_BlindingKey *b1,
1930 struct GNUNET_CRYPTO_rsa_BlindingKey *b2);
1934 * Compare the values of two signatures.
1936 * @param s1 one signature
1937 * @param s2 the other signature
1938 * @return 0 if the two are equal
1941 GNUNET_CRYPTO_rsa_signature_cmp (struct GNUNET_CRYPTO_rsa_Signature *s1,
1942 struct GNUNET_CRYPTO_rsa_Signature *s2);
1945 * Compare the values of two private keys.
1947 * @param p1 one private key
1948 * @param p2 the other private key
1949 * @return 0 if the two are equal
1952 GNUNET_CRYPTO_rsa_private_key_cmp (struct GNUNET_CRYPTO_rsa_PrivateKey *p1,
1953 struct GNUNET_CRYPTO_rsa_PrivateKey *p2);
1957 * Compare the values of two public keys.
1959 * @param p1 one public key
1960 * @param p2 the other public key
1961 * @return 0 if the two are equal
1964 GNUNET_CRYPTO_rsa_public_key_cmp (struct GNUNET_CRYPTO_rsa_PublicKey *p1,
1965 struct GNUNET_CRYPTO_rsa_PublicKey *p2);
1969 * Destroy a blinding key
1971 * @param bkey the blinding key to destroy
1974 GNUNET_CRYPTO_rsa_blinding_key_free (struct GNUNET_CRYPTO_rsa_BlindingKey *bkey);
1978 * Encode the blinding key in a format suitable for
1979 * storing it into a file.
1981 * @param bkey the blinding key
1982 * @param[out] buffer set to a buffer with the encoded key
1983 * @return size of memory allocated in @a buffer
1986 GNUNET_CRYPTO_rsa_blinding_key_encode (const struct GNUNET_CRYPTO_rsa_BlindingKey *bkey,
1991 * Decode the blinding key from the data-format back
1992 * to the "normal", internal format.
1994 * @param buf the buffer where the public key data is stored
1995 * @param len the length of the data in @a buf
1996 * @return NULL on error
1998 struct GNUNET_CRYPTO_rsa_BlindingKey *
1999 GNUNET_CRYPTO_rsa_blinding_key_decode (const char *buf,
2004 * Blinds the given message with the given blinding key
2006 * @param hash hash of the message to sign
2007 * @param bkey the blinding key
2008 * @param pkey the public key of the signer
2009 * @param[out] buffer set to a buffer with the blinded message to be signed
2010 * @return number of bytes stored in @a buffer
2013 GNUNET_CRYPTO_rsa_blind (const struct GNUNET_HashCode *hash,
2014 struct GNUNET_CRYPTO_rsa_BlindingKey *bkey,
2015 struct GNUNET_CRYPTO_rsa_PublicKey *pkey,
2020 * Sign the given message.
2022 * @param key private key to use for the signing
2023 * @param msg the (blinded) message to sign
2024 * @param msg_len number of bytes in @a msg to sign
2025 * @return NULL on error, signature on success
2027 struct GNUNET_CRYPTO_rsa_Signature *
2028 GNUNET_CRYPTO_rsa_sign (const struct GNUNET_CRYPTO_rsa_PrivateKey *key,
2034 * Free memory occupied by signature.
2036 * @param sig memory to free
2039 GNUNET_CRYPTO_rsa_signature_free (struct GNUNET_CRYPTO_rsa_Signature *sig);
2043 * Encode the given signature in a format suitable for storing it into a file.
2045 * @param sig the signature
2046 * @param[out] buffer set to a buffer with the encoded key
2047 * @return size of memory allocated in @a buffer
2050 GNUNET_CRYPTO_rsa_signature_encode (const struct GNUNET_CRYPTO_rsa_Signature *sig,
2055 * Decode the signature from the data-format back to the "normal", internal
2058 * @param buf the buffer where the public key data is stored
2059 * @param len the length of the data in @a buf
2060 * @return NULL on error
2062 struct GNUNET_CRYPTO_rsa_Signature *
2063 GNUNET_CRYPTO_rsa_signature_decode (const char *buf,
2068 * Duplicate the given rsa signature
2070 * @param sig the signature to duplicate
2071 * @return the duplicate key; NULL upon error
2073 struct GNUNET_CRYPTO_rsa_Signature *
2074 GNUNET_CRYPTO_rsa_signature_dup (const struct GNUNET_CRYPTO_rsa_Signature *sig);
2078 * Unblind a blind-signed signature. The signature should have been generated
2079 * with #GNUNET_CRYPTO_rsa_sign() using a hash that was blinded with
2080 * #GNUNET_CRYPTO_rsa_blind().
2082 * @param sig the signature made on the blinded signature purpose
2083 * @param bkey the blinding key used to blind the signature purpose
2084 * @param pkey the public key of the signer
2085 * @return unblinded signature on success, NULL on error
2087 struct GNUNET_CRYPTO_rsa_Signature *
2088 GNUNET_CRYPTO_rsa_unblind (struct GNUNET_CRYPTO_rsa_Signature *sig,
2089 struct GNUNET_CRYPTO_rsa_BlindingKey *bkey,
2090 struct GNUNET_CRYPTO_rsa_PublicKey *pkey);
2094 * Verify whether the given hash corresponds to the given signature and the
2095 * signature is valid with respect to the given public key.
2097 * @param hash the message to verify to match the @a sig
2098 * @param sig signature that is being validated
2099 * @param public_key public key of the signer
2100 * @returns #GNUNET_OK if ok, #GNUNET_SYSERR if invalid
2103 GNUNET_CRYPTO_rsa_verify (const struct GNUNET_HashCode *hash,
2104 const struct GNUNET_CRYPTO_rsa_Signature *sig,
2105 const struct GNUNET_CRYPTO_rsa_PublicKey *public_key);
2108 #if 0 /* keep Emacsens' auto-indent happy */
2116 /* ifndef GNUNET_CRYPTO_LIB_H */
2118 /* end of gnunet_crypto_lib.h */