2 This file is part of GNUnet.
3 (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., 59 Temple Place - Suite 330,
18 Boston, MA 02111-1307, 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 Cryptographic operations
32 * @defgroup hash Hashing and operations on hashes
35 #ifndef GNUNET_CRYPTO_LIB_H
36 #define GNUNET_CRYPTO_LIB_H
41 #if 0 /* keep Emacsens' auto-indent happy */
47 * @brief A 512-bit hashcode
49 struct GNUNET_HashCode;
52 * The identity of the host (wraps the signing key of the peer).
54 struct GNUNET_PeerIdentity;
56 #include "gnunet_common.h"
57 #include "gnunet_scheduler_lib.h"
61 * @brief A 512-bit hashcode
63 struct GNUNET_HashCode
65 uint32_t bits[512 / 8 / sizeof (uint32_t)]; /* = 16 */
70 * Maximum length of an ECC signature.
71 * Note: round up to multiple of 8 minus 2 for alignment.
73 #define GNUNET_CRYPTO_ECC_SIGNATURE_DATA_ENCODING_LENGTH 126
77 * Desired quality level for random numbers.
80 enum GNUNET_CRYPTO_Quality
83 * No good quality of the operation is needed (i.e.,
84 * random numbers can be pseudo-random).
87 GNUNET_CRYPTO_QUALITY_WEAK,
90 * High-quality operations are desired.
93 GNUNET_CRYPTO_QUALITY_STRONG,
96 * Randomness for IVs etc. is required.
99 GNUNET_CRYPTO_QUALITY_NONCE
104 * @brief length of the sessionkey in bytes (256 BIT sessionkey)
106 #define GNUNET_CRYPTO_AES_KEY_LENGTH (256/8)
109 * Length of a hash value
111 #define GNUNET_CRYPTO_HASH_LENGTH (512/8)
114 * @brief 0-terminated ASCII encoding of a struct GNUNET_HashCode.
116 struct GNUNET_CRYPTO_HashAsciiEncoded
118 unsigned char encoding[104];
122 GNUNET_NETWORK_STRUCT_BEGIN
126 * @brief header of what an ECC signature signs
127 * this must be followed by "size - 8" bytes of
128 * the actual signed data
130 struct GNUNET_CRYPTO_EccSignaturePurpose
133 * How many bytes does this signature sign?
134 * (including this purpose header); in network
137 uint32_t size GNUNET_PACKED;
140 * What does this signature vouch for? This
141 * must contain a GNUNET_SIGNATURE_PURPOSE_XXX
142 * constant (from gnunet_signatures.h). In
143 * network byte order!
145 uint32_t purpose GNUNET_PACKED;
151 * @brief an ECC signature using EdDSA.
152 * See https://gnunet.org/ed25519
154 struct GNUNET_CRYPTO_EddsaSignature
160 unsigned char r[256 / 8];
165 unsigned char s[256 / 8];
172 * @brief an ECC signature using ECDSA
174 struct GNUNET_CRYPTO_EcdsaSignature
180 unsigned char r[256 / 8];
185 unsigned char s[256 / 8];
191 * Public ECC key (always for Curve25519) encoded in a format suitable
192 * for network transmission and EdDSA signatures.
194 struct GNUNET_CRYPTO_EddsaPublicKey
197 * Q consists of an x- and a y-value, each mod p (256 bits),
198 * given here in affine coordinates.
200 * FIXME: this coordinate will be removed in the future (compressed point!).
202 unsigned char q_x[256 / 8];
205 * Q consists of an x- and a y-value, each mod p (256 bits),
206 * given here in affine coordinates.
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),
221 * given here in affine coordinates.
223 * FIXME: this coordinate will be removed in the future (compressed point!).
225 unsigned char q_x[256 / 8];
228 * Q consists of an x- and a y-value, each mod p (256 bits),
229 * given here in affine coordinates.
231 unsigned char q_y[256 / 8];
237 * The identity of the host (wraps the signing key of the peer).
239 struct GNUNET_PeerIdentity
241 struct GNUNET_CRYPTO_EddsaPublicKey public_key;
246 * Public ECC key (always for Curve25519) encoded in a format suitable
247 * for network transmission and encryption (ECDH),
248 * See http://cr.yp.to/ecdh.html
250 struct GNUNET_CRYPTO_EcdhePublicKey
253 * Q consists of an x- and a y-value, each mod p (256 bits),
254 * given here in affine coordinates.
256 unsigned char q_x[256 / 8];
259 * Q consists of an x- and a y-value, each mod p (256 bits),
260 * given here in affine coordinates.
262 * FIXME: this coordinate will be removed in the future (compressed point!).
264 unsigned char q_y[256 / 8];
270 * Private ECC key encoded for transmission. To be used only for ECDH
271 * key exchange (ECDHE to be precise).
273 struct GNUNET_CRYPTO_EcdhePrivateKey
276 * d is a value mod n, where n has at most 256 bits.
278 unsigned char d[256 / 8];
283 * Private ECC key encoded for transmission. To be used only for ECDSA
286 struct GNUNET_CRYPTO_EcdsaPrivateKey
289 * d is a value mod n, where n has at most 256 bits.
291 unsigned char d[256 / 8];
296 * Private ECC key encoded for transmission. To be used only for EdDSA
299 struct GNUNET_CRYPTO_EddsaPrivateKey
302 * d is a value mod n, where n has at most 256 bits.
304 unsigned char d[256 / 8];
310 * @brief type for session keys
312 struct GNUNET_CRYPTO_SymmetricSessionKey
315 * Actual key for AES.
317 unsigned char aes_key[GNUNET_CRYPTO_AES_KEY_LENGTH];
320 * Actual key for TwoFish.
322 unsigned char twofish_key[GNUNET_CRYPTO_AES_KEY_LENGTH];
326 GNUNET_NETWORK_STRUCT_END
329 * @brief IV for sym cipher
331 * NOTE: must be smaller (!) in size than the
332 * `struct GNUNET_HashCode`.
334 struct GNUNET_CRYPTO_SymmetricInitializationVector
336 unsigned char aes_iv[GNUNET_CRYPTO_AES_KEY_LENGTH / 2];
338 unsigned char twofish_iv[GNUNET_CRYPTO_AES_KEY_LENGTH / 2];
343 * @brief type for (message) authentication keys
345 struct GNUNET_CRYPTO_AuthKey
347 unsigned char key[GNUNET_CRYPTO_HASH_LENGTH];
351 /* **************** Functions and Macros ************* */
355 * Seed a weak random generator. Only #GNUNET_CRYPTO_QUALITY_WEAK-mode generator
358 * @param seed the seed to use
361 GNUNET_CRYPTO_seed_weak_random (int32_t seed);
365 * Perform an incremental step in a CRC16 (for TCP/IP) calculation.
367 * @param sum current sum, initially 0
368 * @param buf buffer to calculate CRC over (must be 16-bit aligned)
369 * @param len number of bytes in @a buf, must be multiple of 2
370 * @return updated crc sum (must be subjected to #GNUNET_CRYPTO_crc16_finish to get actual crc16)
373 GNUNET_CRYPTO_crc16_step (uint32_t sum, const void *buf, size_t len);
377 * Convert results from GNUNET_CRYPTO_crc16_step to final crc16.
379 * @param sum cummulative sum
380 * @return crc16 value
383 GNUNET_CRYPTO_crc16_finish (uint32_t sum);
388 * Calculate the checksum of a buffer in one step.
390 * @param buf buffer to calculate CRC over (must be 16-bit aligned)
391 * @param len number of bytes in @a buf, must be multiple of 2
392 * @return crc16 value
395 GNUNET_CRYPTO_crc16_n (const void *buf, size_t len);
400 * Compute the CRC32 checksum for the first len
401 * bytes of the buffer.
403 * @param buf the data over which we're taking the CRC
404 * @param len the length of the buffer @a buf in bytes
405 * @return the resulting CRC32 checksum
408 GNUNET_CRYPTO_crc32_n (const void *buf, size_t len);
413 * Fill block with a random values.
415 * @param mode desired quality of the random number
416 * @param buffer the buffer to fill
417 * @param length buffer length
420 GNUNET_CRYPTO_random_block (enum GNUNET_CRYPTO_Quality mode, void *buffer, size_t length);
424 * Produce a random value.
426 * @param mode desired quality of the random number
427 * @param i the upper limit (exclusive) for the random number
428 * @return a random value in the interval [0,@a i) (exclusive).
431 GNUNET_CRYPTO_random_u32 (enum GNUNET_CRYPTO_Quality mode, uint32_t i);
436 * Random on unsigned 64-bit values.
438 * @param mode desired quality of the random number
439 * @param max value returned will be in range [0,@a max) (exclusive)
440 * @return random 64-bit number
443 GNUNET_CRYPTO_random_u64 (enum GNUNET_CRYPTO_Quality mode, uint64_t max);
448 * Get an array with a random permutation of the
450 * @param mode #GNUNET_CRYPTO_QUALITY_STRONG if the strong (but expensive) PRNG should be used,
451 * #GNUNET_CRYPTO_QUALITY_WEAK or #GNUNET_CRYPTO_QUALITY_NONCE otherwise
452 * @param n the size of the array
453 * @return the permutation array (allocated from heap)
456 GNUNET_CRYPTO_random_permute (enum GNUNET_CRYPTO_Quality mode, unsigned int n);
461 * Create a new random session key.
463 * @param key key to initialize
466 GNUNET_CRYPTO_symmetric_create_session_key (struct GNUNET_CRYPTO_SymmetricSessionKey *key);
471 * Encrypt a block using a symmetric sessionkey.
473 * @param block the block to encrypt
474 * @param len the size of the block
475 * @param sessionkey the key used to encrypt
476 * @param iv the initialization vector to use, use INITVALUE
478 * @return the size of the encrypted block, -1 for errors
481 GNUNET_CRYPTO_symmetric_encrypt (const void *block, size_t len,
482 const struct GNUNET_CRYPTO_SymmetricSessionKey *sessionkey,
483 const struct GNUNET_CRYPTO_SymmetricInitializationVector *iv,
489 * Decrypt a given block using a symmetric sessionkey.
491 * @param block the data to decrypt, encoded as returned by encrypt
492 * @param size how big is the block?
493 * @param sessionkey the key used to decrypt
494 * @param iv the initialization vector to use
495 * @param result address to store the result at
496 * @return -1 on failure, size of decrypted block on success
499 GNUNET_CRYPTO_symmetric_decrypt (const void *block, size_t size,
500 const struct GNUNET_CRYPTO_SymmetricSessionKey *sessionkey,
501 const struct GNUNET_CRYPTO_SymmetricInitializationVector *iv,
507 * @brief Derive an IV
508 * @param iv initialization vector
509 * @param skey session key
510 * @param salt salt for the derivation
511 * @param salt_len size of the @a salt
512 * @param ... pairs of void * & size_t for context chunks, terminated by NULL
515 GNUNET_CRYPTO_symmetric_derive_iv (struct GNUNET_CRYPTO_SymmetricInitializationVector *iv,
516 const struct GNUNET_CRYPTO_SymmetricSessionKey *skey,
518 size_t salt_len, ...);
522 * @brief Derive an IV
523 * @param iv initialization vector
524 * @param skey session key
525 * @param salt salt for the derivation
526 * @param salt_len size of the @a salt
527 * @param argp pairs of void * & size_t for context chunks, terminated by NULL
530 GNUNET_CRYPTO_symmetric_derive_iv_v (struct GNUNET_CRYPTO_SymmetricInitializationVector *iv,
531 const struct GNUNET_CRYPTO_SymmetricSessionKey *skey,
539 * Convert hash to ASCII encoding.
540 * @param block the hash code
541 * @param result where to store the encoding (struct GNUNET_CRYPTO_HashAsciiEncoded can be
542 * safely cast to char*, a '\\0' termination is set).
545 GNUNET_CRYPTO_hash_to_enc (const struct GNUNET_HashCode * block,
546 struct GNUNET_CRYPTO_HashAsciiEncoded *result);
551 * Convert ASCII encoding back to a 'struct GNUNET_HashCode'
553 * @param enc the encoding
554 * @param enclen number of characters in @a enc (without 0-terminator, which can be missing)
555 * @param result where to store the hash code
556 * @return #GNUNET_OK on success, #GNUNET_SYSERR if result has the wrong encoding
559 GNUNET_CRYPTO_hash_from_string2 (const char *enc, size_t enclen,
560 struct GNUNET_HashCode *result);
565 * Convert ASCII encoding back to `struct GNUNET_HashCode`
567 * @param enc the encoding
568 * @param result where to store the hash code
569 * @return #GNUNET_OK on success, #GNUNET_SYSERR if result has the wrong encoding
571 #define GNUNET_CRYPTO_hash_from_string(enc, result) \
572 GNUNET_CRYPTO_hash_from_string2 (enc, strlen(enc), result)
578 * Compute the distance between 2 hashcodes. The
579 * computation must be fast, not involve @a a[0] or @a a[4] (they're used
580 * elsewhere), and be somewhat consistent. And of course, the result
581 * should be a positive number.
583 * @param a some hash code
584 * @param b some hash code
585 * @return number between 0 and UINT32_MAX
588 GNUNET_CRYPTO_hash_distance_u32 (const struct GNUNET_HashCode *a,
589 const struct GNUNET_HashCode *b);
594 * Compute hash of a given block.
596 * @param block the data to hash
597 * @param size size of the @a block
598 * @param ret pointer to where to write the hashcode
601 GNUNET_CRYPTO_hash (const void *block, size_t size, struct GNUNET_HashCode * ret);
606 * Calculate HMAC of a message (RFC 2104)
608 * @param key secret key
609 * @param plaintext input plaintext
610 * @param plaintext_len length of @a plaintext
611 * @param hmac where to store the hmac
614 GNUNET_CRYPTO_hmac (const struct GNUNET_CRYPTO_AuthKey *key,
615 const void *plaintext, size_t plaintext_len,
616 struct GNUNET_HashCode * hmac);
620 * Function called once the hash computation over the
621 * specified file has completed.
624 * @param res resulting hash, NULL on error
626 typedef void (*GNUNET_CRYPTO_HashCompletedCallback) (void *cls,
627 const struct GNUNET_HashCode *res);
631 * Handle to file hashing operation.
633 struct GNUNET_CRYPTO_FileHashContext;
638 * Compute the hash of an entire file.
640 * @param priority scheduling priority to use
641 * @param filename name of file to hash
642 * @param blocksize number of bytes to process in one task
643 * @param callback function to call upon completion
644 * @param callback_cls closure for @a callback
645 * @return NULL on (immediate) errror
647 struct GNUNET_CRYPTO_FileHashContext *
648 GNUNET_CRYPTO_hash_file (enum GNUNET_SCHEDULER_Priority priority,
649 const char *filename, size_t blocksize,
650 GNUNET_CRYPTO_HashCompletedCallback callback,
655 * Cancel a file hashing operation.
657 * @param fhc operation to cancel (callback must not yet have been invoked)
660 GNUNET_CRYPTO_hash_file_cancel (struct GNUNET_CRYPTO_FileHashContext *fhc);
665 * Create a random hash code.
667 * @param mode desired quality level
668 * @param result hash code that is randomized
671 GNUNET_CRYPTO_hash_create_random (enum GNUNET_CRYPTO_Quality mode,
672 struct GNUNET_HashCode *result);
677 * compute @a result = @a b - @a a
679 * @param a some hash code
680 * @param b some hash code
681 * @param result set to @a b - @a a
684 GNUNET_CRYPTO_hash_difference (const struct GNUNET_HashCode *a,
685 const struct GNUNET_HashCode *b,
686 struct GNUNET_HashCode *result);
691 * compute @a result = @a a + @a delta
693 * @param a some hash code
694 * @param delta some hash code
695 * @param result set to @a a + @a delta
698 GNUNET_CRYPTO_hash_sum (const struct GNUNET_HashCode *a,
699 const struct GNUNET_HashCode *delta,
700 struct GNUNET_HashCode *result);
705 * compute result = a ^ b
707 * @param a some hash code
708 * @param b some hash code
709 * @param result set to @a a ^ @a b
712 GNUNET_CRYPTO_hash_xor (const struct GNUNET_HashCode * a, const struct GNUNET_HashCode * b,
713 struct GNUNET_HashCode * result);
718 * Convert a hashcode into a key.
720 * @param hc hash code that serves to generate the key
721 * @param skey set to a valid session key
722 * @param iv set to a valid initialization vector
725 GNUNET_CRYPTO_hash_to_aes_key (const struct GNUNET_HashCode * hc,
726 struct GNUNET_CRYPTO_SymmetricSessionKey *skey,
727 struct GNUNET_CRYPTO_SymmetricInitializationVector *iv);
732 * Obtain a bit from a hashcode.
734 * @param code the `struct GNUNET_HashCode` to index bit-wise
735 * @param bit index into the hashcode, [0...159]
736 * @return Bit \a bit from hashcode \a code, -1 for invalid index
739 GNUNET_CRYPTO_hash_get_bit (const struct GNUNET_HashCode *code,
745 * Determine how many low order bits match in two
746 * `struct GNUNET_HashCodes`. i.e. - 010011 and 011111 share
747 * the first two lowest order bits, and therefore the
748 * return value is two (NOT XOR distance, nor how many
749 * bits match absolutely!).
751 * @param first the first hashcode
752 * @param second the hashcode to compare first to
753 * @return the number of bits that match
756 GNUNET_CRYPTO_hash_matching_bits (const struct GNUNET_HashCode *first,
757 const struct GNUNET_HashCode *second);
762 * Compare function for HashCodes, producing a total ordering
765 * @param h1 some hash code
766 * @param h2 some hash code
767 * @return 1 if @a h1 > @a h2, -1 if @a h1 < @a h2 and 0 if @a h1 == @a h2.
770 GNUNET_CRYPTO_hash_cmp (const struct GNUNET_HashCode *h1,
771 const struct GNUNET_HashCode *h2);
776 * Find out which of the two GNUNET_CRYPTO_hash codes is closer to target
777 * in the XOR metric (Kademlia).
779 * @param h1 some hash code
780 * @param h2 some hash code
781 * @param target some hash code
782 * @return -1 if @a h1 is closer, 1 if @a h2 is closer and 0 if @a h1== @a h2.
785 GNUNET_CRYPTO_hash_xorcmp (const struct GNUNET_HashCode *h1,
786 const struct GNUNET_HashCode *h2,
787 const struct GNUNET_HashCode *target);
792 * @brief Derive an authentication key
793 * @param key authentication key
794 * @param rkey root key
796 * @param salt_len size of the salt
797 * @param argp pair of void * & size_t for context chunks, terminated by NULL
800 GNUNET_CRYPTO_hmac_derive_key_v (struct GNUNET_CRYPTO_AuthKey *key,
801 const struct GNUNET_CRYPTO_SymmetricSessionKey *rkey,
802 const void *salt, size_t salt_len,
808 * @brief Derive an authentication key
809 * @param key authentication key
810 * @param rkey root key
812 * @param salt_len size of the salt
813 * @param ... pair of void * & size_t for context chunks, terminated by NULL
816 GNUNET_CRYPTO_hmac_derive_key (struct GNUNET_CRYPTO_AuthKey *key,
817 const struct GNUNET_CRYPTO_SymmetricSessionKey *rkey,
818 const void *salt, size_t salt_len, ...);
824 * @param result buffer for the derived key, allocated by caller
825 * @param out_len desired length of the derived key
826 * @param xtr_algo hash algorithm for the extraction phase, GCRY_MD_...
827 * @param prf_algo hash algorithm for the expansion phase, GCRY_MD_...
829 * @param xts_len length of @a xts
830 * @param skm source key material
831 * @param skm_len length of @a skm
832 * @param ... pair of void * & size_t for context chunks, terminated by NULL
833 * @return #GNUNET_YES on success
836 GNUNET_CRYPTO_hkdf (void *result, size_t out_len, int xtr_algo, int prf_algo,
837 const void *xts, size_t xts_len, const void *skm,
838 size_t skm_len, ...);
844 * @param result buffer for the derived key, allocated by caller
845 * @param out_len desired length of the derived key
846 * @param xtr_algo hash algorithm for the extraction phase, GCRY_MD_...
847 * @param prf_algo hash algorithm for the expansion phase, GCRY_MD_...
849 * @param xts_len length of @a xts
850 * @param skm source key material
851 * @param skm_len length of @a skm
852 * @param argp va_list of void * & size_t pairs for context chunks
853 * @return #GNUNET_YES on success
856 GNUNET_CRYPTO_hkdf_v (void *result, size_t out_len, int xtr_algo, int prf_algo,
857 const void *xts, size_t xts_len, const void *skm,
858 size_t skm_len, va_list argp);
863 * @param result buffer for the derived key, allocated by caller
864 * @param out_len desired length of the derived key
866 * @param xts_len length of @a xts
867 * @param skm source key material
868 * @param skm_len length of @a skm
869 * @param argp va_list of void * & size_t pairs for context chunks
870 * @return #GNUNET_YES on success
873 GNUNET_CRYPTO_kdf_v (void *result, size_t out_len, const void *xts,
874 size_t xts_len, const void *skm, size_t skm_len,
881 * @param result buffer for the derived key, allocated by caller
882 * @param out_len desired length of the derived key
884 * @param xts_len length of @a xts
885 * @param skm source key material
886 * @param skm_len length of @a skm
887 * @param ... void * & size_t pairs for context chunks
888 * @return #GNUNET_YES on success
891 GNUNET_CRYPTO_kdf (void *result, size_t out_len, const void *xts,
892 size_t xts_len, const void *skm, size_t skm_len, ...);
897 * Extract the public key for the given private key.
899 * @param priv the private key
900 * @param pub where to write the public key
903 GNUNET_CRYPTO_ecdsa_key_get_public (const struct GNUNET_CRYPTO_EcdsaPrivateKey *priv,
904 struct GNUNET_CRYPTO_EcdsaPublicKey *pub);
908 * Extract the public key for the given private key.
910 * @param priv the private key
911 * @param pub where to write the public key
914 GNUNET_CRYPTO_eddsa_key_get_public (const struct GNUNET_CRYPTO_EddsaPrivateKey *priv,
915 struct GNUNET_CRYPTO_EddsaPublicKey *pub);
920 * Extract the public key for the given private key.
922 * @param priv the private key
923 * @param pub where to write the public key
926 GNUNET_CRYPTO_ecdhe_key_get_public (const struct GNUNET_CRYPTO_EcdhePrivateKey *priv,
927 struct GNUNET_CRYPTO_EcdhePublicKey *pub);
931 * Convert a public key to a string.
933 * @param pub key to convert
934 * @return string representing @a pub
937 GNUNET_CRYPTO_ecdsa_public_key_to_string (const struct GNUNET_CRYPTO_EcdsaPublicKey *pub);
941 * Convert a public key to a string.
943 * @param pub key to convert
944 * @return string representing @a pub
947 GNUNET_CRYPTO_eddsa_public_key_to_string (const struct GNUNET_CRYPTO_EddsaPublicKey *pub);
951 * Convert a string representing a public key to a public key.
953 * @param enc encoded public key
954 * @param enclen number of bytes in @a enc (without 0-terminator)
955 * @param pub where to store the public key
956 * @return #GNUNET_OK on success
959 GNUNET_CRYPTO_ecdsa_public_key_from_string (const char *enc,
961 struct GNUNET_CRYPTO_EcdsaPublicKey *pub);
965 * Convert a string representing a public key to a public key.
967 * @param enc encoded public key
968 * @param enclen number of bytes in @a enc (without 0-terminator)
969 * @param pub where to store the public key
970 * @return #GNUNET_OK on success
973 GNUNET_CRYPTO_eddsa_public_key_from_string (const char *enc,
975 struct GNUNET_CRYPTO_EddsaPublicKey *pub);
980 * Create a new private key by reading it from a file. If the
981 * files does not exist, create a new key and write it to the
982 * file. Caller must free return value. Note that this function
983 * can not guarantee that another process might not be trying
984 * the same operation on the same file at the same time.
985 * If the contents of the file
986 * are invalid the old file is deleted and a fresh key is
989 * @param filename name of file to use to store the key
990 * @return new private key, NULL on error (for example,
991 * permission denied); free using #GNUNET_free
993 struct GNUNET_CRYPTO_EcdsaPrivateKey *
994 GNUNET_CRYPTO_ecdsa_key_create_from_file (const char *filename);
999 * Create a new private key by reading it from a file. If the
1000 * files does not exist, create a new key and write it to the
1001 * file. Caller must free return value. Note that this function
1002 * can not guarantee that another process might not be trying
1003 * the same operation on the same file at the same time.
1004 * If the contents of the file
1005 * are invalid the old file is deleted and a fresh key is
1008 * @param filename name of file to use to store the key
1009 * @return new private key, NULL on error (for example,
1010 * permission denied); free using #GNUNET_free
1012 struct GNUNET_CRYPTO_EddsaPrivateKey *
1013 GNUNET_CRYPTO_eddsa_key_create_from_file (const char *filename);
1018 * Create a new private key by reading our peer's key from
1019 * the file specified in the configuration.
1021 * @param cfg the configuration to use
1022 * @return new private key, NULL on error (for example,
1023 * permission denied); free using #GNUNET_free
1025 struct GNUNET_CRYPTO_EddsaPrivateKey *
1026 GNUNET_CRYPTO_eddsa_key_create_from_configuration (const struct GNUNET_CONFIGURATION_Handle *cfg);
1031 * Create a new private key. Caller must free return value.
1033 * @return fresh private key; free using #GNUNET_free
1035 struct GNUNET_CRYPTO_EcdsaPrivateKey *
1036 GNUNET_CRYPTO_ecdsa_key_create (void);
1041 * Create a new private key. Caller must free return value.
1043 * @return fresh private key; free using #GNUNET_free
1045 struct GNUNET_CRYPTO_EddsaPrivateKey *
1046 GNUNET_CRYPTO_eddsa_key_create (void);
1051 * Create a new private key. Caller must free return value.
1053 * @return fresh private key; free using #GNUNET_free
1055 struct GNUNET_CRYPTO_EcdhePrivateKey *
1056 GNUNET_CRYPTO_ecdhe_key_create (void);
1061 * Clear memory that was used to store a private key.
1063 * @param pk location of the key
1066 GNUNET_CRYPTO_eddsa_key_clear (struct GNUNET_CRYPTO_EddsaPrivateKey *pk);
1071 * Clear memory that was used to store a private key.
1073 * @param pk location of the key
1076 GNUNET_CRYPTO_ecdsa_key_clear (struct GNUNET_CRYPTO_EcdsaPrivateKey *pk);
1080 * Clear memory that was used to store a private key.
1082 * @param pk location of the key
1085 GNUNET_CRYPTO_ecdhe_key_clear (struct GNUNET_CRYPTO_EcdhePrivateKey *pk);
1090 * Get the shared private key we use for anonymous users.
1092 * @return "anonymous" private key; do not free
1094 const struct GNUNET_CRYPTO_EcdsaPrivateKey *
1095 GNUNET_CRYPTO_ecdsa_key_get_anonymous (void);
1100 * Setup a hostkey file for a peer given the name of the
1101 * configuration file (!). This function is used so that
1102 * at a later point code can be certain that reading a
1103 * hostkey is fast (for example in time-dependent testcases).
1105 * @param cfg_name name of the configuration file to use
1108 GNUNET_CRYPTO_eddsa_setup_hostkey (const char *cfg_name);
1113 * Retrieve the identity of the host's peer.
1115 * @param cfg configuration to use
1116 * @param dst pointer to where to write the peer identity
1117 * @return #GNUNET_OK on success, #GNUNET_SYSERR if the identity
1118 * could not be retrieved
1121 GNUNET_CRYPTO_get_peer_identity (const struct GNUNET_CONFIGURATION_Handle *cfg,
1122 struct GNUNET_PeerIdentity *dst);
1127 * Derive key material from a public and a private ECC key.
1129 * @param priv private key to use for the ECDH (x)
1130 * @param pub public key to use for the ECDH (yG)
1131 * @param key_material where to write the key material (xyG)
1132 * @return #GNUNET_SYSERR on error, #GNUNET_OK on success
1135 GNUNET_CRYPTO_ecc_ecdh (const struct GNUNET_CRYPTO_EcdhePrivateKey *priv,
1136 const struct GNUNET_CRYPTO_EcdhePublicKey *pub,
1137 struct GNUNET_HashCode *key_material);
1142 * EdDSA sign a given block.
1144 * @param priv private key to use for the signing
1145 * @param purpose what to sign (size, purpose)
1146 * @param sig where to write the signature
1147 * @return #GNUNET_SYSERR on error, #GNUNET_OK on success
1150 GNUNET_CRYPTO_eddsa_sign (const struct GNUNET_CRYPTO_EddsaPrivateKey *priv,
1151 const struct GNUNET_CRYPTO_EccSignaturePurpose *purpose,
1152 struct GNUNET_CRYPTO_EddsaSignature *sig);
1157 * ECDSA Sign a given block.
1159 * @param priv private key to use for the signing
1160 * @param purpose what to sign (size, purpose)
1161 * @param sig where to write the signature
1162 * @return #GNUNET_SYSERR on error, #GNUNET_OK on success
1165 GNUNET_CRYPTO_ecdsa_sign (const struct GNUNET_CRYPTO_EcdsaPrivateKey *priv,
1166 const struct GNUNET_CRYPTO_EccSignaturePurpose *purpose,
1167 struct GNUNET_CRYPTO_EcdsaSignature *sig);
1171 * Verify EdDSA signature.
1173 * @param purpose what is the purpose that the signature should have?
1174 * @param validate block to validate (size, purpose, data)
1175 * @param sig signature that is being validated
1176 * @param pub public key of the signer
1177 * @returns #GNUNET_OK if ok, #GNUNET_SYSERR if invalid
1180 GNUNET_CRYPTO_eddsa_verify (uint32_t purpose,
1181 const struct GNUNET_CRYPTO_EccSignaturePurpose *validate,
1182 const struct GNUNET_CRYPTO_EddsaSignature *sig,
1183 const struct GNUNET_CRYPTO_EddsaPublicKey *pub);
1189 * Verify ECDSA signature.
1191 * @param purpose what is the purpose that the signature should have?
1192 * @param validate block to validate (size, purpose, data)
1193 * @param sig signature that is being validated
1194 * @param pub public key of the signer
1195 * @returns #GNUNET_OK if ok, #GNUNET_SYSERR if invalid
1198 GNUNET_CRYPTO_ecdsa_verify (uint32_t purpose,
1199 const struct GNUNET_CRYPTO_EccSignaturePurpose *validate,
1200 const struct GNUNET_CRYPTO_EcdsaSignature *sig,
1201 const struct GNUNET_CRYPTO_EcdsaPublicKey *pub);
1206 * Derive a private key from a given private key and a label.
1207 * Essentially calculates a private key 'h = H(l,P) * d mod n'
1208 * where n is the size of the ECC group and P is the public
1209 * key associated with the private key 'd'.
1211 * @param priv original private key
1212 * @param label label to use for key deriviation
1213 * @param context additional context to use for HKDF of 'h';
1214 * typically the name of the subsystem/application
1215 * @return derived private key
1217 struct GNUNET_CRYPTO_EcdsaPrivateKey *
1218 GNUNET_CRYPTO_ecdsa_private_key_derive (const struct GNUNET_CRYPTO_EcdsaPrivateKey *priv,
1220 const char *context);
1225 * Derive a public key from a given public key and a label.
1226 * Essentially calculates a public key 'V = H(l,P) * P'.
1228 * @param pub original public key
1229 * @param label label to use for key deriviation
1230 * @param context additional context to use for HKDF of 'h'.
1231 * typically the name of the subsystem/application
1232 * @param result where to write the derived public key
1235 GNUNET_CRYPTO_ecdsa_public_key_derive (const struct GNUNET_CRYPTO_EcdsaPublicKey *pub,
1237 const char *context,
1238 struct GNUNET_CRYPTO_EcdsaPublicKey *result);
1241 #if 0 /* keep Emacsens' auto-indent happy */
1249 /* ifndef GNUNET_CRYPTO_LIB_H */
1251 /* end of gnunet_crypto_lib.h */