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 * Produce a random value.
415 * @param mode desired quality of the random number
416 * @param i the upper limit (exclusive) for the random number
417 * @return a random value in the interval [0,@a i) (exclusive).
420 GNUNET_CRYPTO_random_u32 (enum GNUNET_CRYPTO_Quality mode, uint32_t i);
425 * Random on unsigned 64-bit values.
427 * @param mode desired quality of the random number
428 * @param max value returned will be in range [0,@a max) (exclusive)
429 * @return random 64-bit number
432 GNUNET_CRYPTO_random_u64 (enum GNUNET_CRYPTO_Quality mode, uint64_t max);
437 * Get an array with a random permutation of the
439 * @param mode #GNUNET_CRYPTO_QUALITY_STRONG if the strong (but expensive) PRNG should be used,
440 * #GNUNET_CRYPTO_QUALITY_WEAK or #GNUNET_CRYPTO_QUALITY_NONCE otherwise
441 * @param n the size of the array
442 * @return the permutation array (allocated from heap)
445 GNUNET_CRYPTO_random_permute (enum GNUNET_CRYPTO_Quality mode, unsigned int n);
450 * Create a new random session key.
452 * @param key key to initialize
455 GNUNET_CRYPTO_symmetric_create_session_key (struct GNUNET_CRYPTO_SymmetricSessionKey *key);
460 * Encrypt a block using a symmetric sessionkey.
462 * @param block the block to encrypt
463 * @param len the size of the block
464 * @param sessionkey the key used to encrypt
465 * @param iv the initialization vector to use, use INITVALUE
467 * @return the size of the encrypted block, -1 for errors
470 GNUNET_CRYPTO_symmetric_encrypt (const void *block, size_t len,
471 const struct GNUNET_CRYPTO_SymmetricSessionKey *sessionkey,
472 const struct GNUNET_CRYPTO_SymmetricInitializationVector *iv,
478 * Decrypt a given block using a symmetric sessionkey.
480 * @param block the data to decrypt, encoded as returned by encrypt
481 * @param size how big is the block?
482 * @param sessionkey the key used to decrypt
483 * @param iv the initialization vector to use
484 * @param result address to store the result at
485 * @return -1 on failure, size of decrypted block on success
488 GNUNET_CRYPTO_symmetric_decrypt (const void *block, size_t size,
489 const struct GNUNET_CRYPTO_SymmetricSessionKey *sessionkey,
490 const struct GNUNET_CRYPTO_SymmetricInitializationVector *iv,
496 * @brief Derive an IV
497 * @param iv initialization vector
498 * @param skey session key
499 * @param salt salt for the derivation
500 * @param salt_len size of the @a salt
501 * @param ... pairs of void * & size_t for context chunks, terminated by NULL
504 GNUNET_CRYPTO_symmetric_derive_iv (struct GNUNET_CRYPTO_SymmetricInitializationVector *iv,
505 const struct GNUNET_CRYPTO_SymmetricSessionKey *skey,
507 size_t salt_len, ...);
511 * @brief Derive an IV
512 * @param iv initialization vector
513 * @param skey session key
514 * @param salt salt for the derivation
515 * @param salt_len size of the @a salt
516 * @param argp pairs of void * & size_t for context chunks, terminated by NULL
519 GNUNET_CRYPTO_symmetric_derive_iv_v (struct GNUNET_CRYPTO_SymmetricInitializationVector *iv,
520 const struct GNUNET_CRYPTO_SymmetricSessionKey *skey,
528 * Convert hash to ASCII encoding.
529 * @param block the hash code
530 * @param result where to store the encoding (struct GNUNET_CRYPTO_HashAsciiEncoded can be
531 * safely cast to char*, a '\\0' termination is set).
534 GNUNET_CRYPTO_hash_to_enc (const struct GNUNET_HashCode * block,
535 struct GNUNET_CRYPTO_HashAsciiEncoded *result);
540 * Convert ASCII encoding back to a 'struct GNUNET_HashCode'
542 * @param enc the encoding
543 * @param enclen number of characters in @a enc (without 0-terminator, which can be missing)
544 * @param result where to store the hash code
545 * @return #GNUNET_OK on success, #GNUNET_SYSERR if result has the wrong encoding
548 GNUNET_CRYPTO_hash_from_string2 (const char *enc, size_t enclen,
549 struct GNUNET_HashCode *result);
554 * Convert ASCII encoding back to `struct GNUNET_HashCode`
556 * @param enc the encoding
557 * @param result where to store the hash code
558 * @return #GNUNET_OK on success, #GNUNET_SYSERR if result has the wrong encoding
560 #define GNUNET_CRYPTO_hash_from_string(enc, result) \
561 GNUNET_CRYPTO_hash_from_string2 (enc, strlen(enc), result)
567 * Compute the distance between 2 hashcodes. The
568 * computation must be fast, not involve @a a[0] or @a a[4] (they're used
569 * elsewhere), and be somewhat consistent. And of course, the result
570 * should be a positive number.
572 * @param a some hash code
573 * @param b some hash code
574 * @return number between 0 and UINT32_MAX
577 GNUNET_CRYPTO_hash_distance_u32 (const struct GNUNET_HashCode *a,
578 const struct GNUNET_HashCode *b);
583 * Compute hash of a given block.
585 * @param block the data to hash
586 * @param size size of the @a block
587 * @param ret pointer to where to write the hashcode
590 GNUNET_CRYPTO_hash (const void *block, size_t size, struct GNUNET_HashCode * ret);
595 * Calculate HMAC of a message (RFC 2104)
597 * @param key secret key
598 * @param plaintext input plaintext
599 * @param plaintext_len length of @a plaintext
600 * @param hmac where to store the hmac
603 GNUNET_CRYPTO_hmac (const struct GNUNET_CRYPTO_AuthKey *key,
604 const void *plaintext, size_t plaintext_len,
605 struct GNUNET_HashCode * hmac);
609 * Function called once the hash computation over the
610 * specified file has completed.
613 * @param res resulting hash, NULL on error
615 typedef void (*GNUNET_CRYPTO_HashCompletedCallback) (void *cls,
616 const struct GNUNET_HashCode *res);
620 * Handle to file hashing operation.
622 struct GNUNET_CRYPTO_FileHashContext;
627 * Compute the hash of an entire file.
629 * @param priority scheduling priority to use
630 * @param filename name of file to hash
631 * @param blocksize number of bytes to process in one task
632 * @param callback function to call upon completion
633 * @param callback_cls closure for @a callback
634 * @return NULL on (immediate) errror
636 struct GNUNET_CRYPTO_FileHashContext *
637 GNUNET_CRYPTO_hash_file (enum GNUNET_SCHEDULER_Priority priority,
638 const char *filename, size_t blocksize,
639 GNUNET_CRYPTO_HashCompletedCallback callback,
644 * Cancel a file hashing operation.
646 * @param fhc operation to cancel (callback must not yet have been invoked)
649 GNUNET_CRYPTO_hash_file_cancel (struct GNUNET_CRYPTO_FileHashContext *fhc);
654 * Create a random hash code.
656 * @param mode desired quality level
657 * @param result hash code that is randomized
660 GNUNET_CRYPTO_hash_create_random (enum GNUNET_CRYPTO_Quality mode,
661 struct GNUNET_HashCode *result);
666 * compute @a result = @a b - @a a
668 * @param a some hash code
669 * @param b some hash code
670 * @param result set to @a b - @a a
673 GNUNET_CRYPTO_hash_difference (const struct GNUNET_HashCode *a,
674 const struct GNUNET_HashCode *b,
675 struct GNUNET_HashCode *result);
680 * compute @a result = @a a + @a delta
682 * @param a some hash code
683 * @param delta some hash code
684 * @param result set to @a a + @a delta
687 GNUNET_CRYPTO_hash_sum (const struct GNUNET_HashCode *a,
688 const struct GNUNET_HashCode *delta,
689 struct GNUNET_HashCode *result);
694 * compute result = a ^ b
696 * @param a some hash code
697 * @param b some hash code
698 * @param result set to @a a ^ @a b
701 GNUNET_CRYPTO_hash_xor (const struct GNUNET_HashCode * a, const struct GNUNET_HashCode * b,
702 struct GNUNET_HashCode * result);
707 * Convert a hashcode into a key.
709 * @param hc hash code that serves to generate the key
710 * @param skey set to a valid session key
711 * @param iv set to a valid initialization vector
714 GNUNET_CRYPTO_hash_to_aes_key (const struct GNUNET_HashCode * hc,
715 struct GNUNET_CRYPTO_SymmetricSessionKey *skey,
716 struct GNUNET_CRYPTO_SymmetricInitializationVector *iv);
721 * Obtain a bit from a hashcode.
723 * @param code the `struct GNUNET_HashCode` to index bit-wise
724 * @param bit index into the hashcode, [0...159]
725 * @return Bit \a bit from hashcode \a code, -1 for invalid index
728 GNUNET_CRYPTO_hash_get_bit (const struct GNUNET_HashCode *code,
734 * Determine how many low order bits match in two
735 * `struct GNUNET_HashCodes`. i.e. - 010011 and 011111 share
736 * the first two lowest order bits, and therefore the
737 * return value is two (NOT XOR distance, nor how many
738 * bits match absolutely!).
740 * @param first the first hashcode
741 * @param second the hashcode to compare first to
742 * @return the number of bits that match
745 GNUNET_CRYPTO_hash_matching_bits (const struct GNUNET_HashCode *first,
746 const struct GNUNET_HashCode *second);
751 * Compare function for HashCodes, producing a total ordering
754 * @param h1 some hash code
755 * @param h2 some hash code
756 * @return 1 if @a h1 > @a h2, -1 if @a h1 < @a h2 and 0 if @a h1 == @a h2.
759 GNUNET_CRYPTO_hash_cmp (const struct GNUNET_HashCode *h1,
760 const struct GNUNET_HashCode *h2);
765 * Find out which of the two GNUNET_CRYPTO_hash codes is closer to target
766 * in the XOR metric (Kademlia).
768 * @param h1 some hash code
769 * @param h2 some hash code
770 * @param target some hash code
771 * @return -1 if @a h1 is closer, 1 if @a h2 is closer and 0 if @a h1== @a h2.
774 GNUNET_CRYPTO_hash_xorcmp (const struct GNUNET_HashCode *h1,
775 const struct GNUNET_HashCode *h2,
776 const struct GNUNET_HashCode *target);
781 * @brief Derive an authentication key
782 * @param key authentication key
783 * @param rkey root key
785 * @param salt_len size of the salt
786 * @param argp pair of void * & size_t for context chunks, terminated by NULL
789 GNUNET_CRYPTO_hmac_derive_key_v (struct GNUNET_CRYPTO_AuthKey *key,
790 const struct GNUNET_CRYPTO_SymmetricSessionKey *rkey,
791 const void *salt, size_t salt_len,
797 * @brief Derive an authentication key
798 * @param key authentication key
799 * @param rkey root key
801 * @param salt_len size of the salt
802 * @param ... pair of void * & size_t for context chunks, terminated by NULL
805 GNUNET_CRYPTO_hmac_derive_key (struct GNUNET_CRYPTO_AuthKey *key,
806 const struct GNUNET_CRYPTO_SymmetricSessionKey *rkey,
807 const void *salt, size_t salt_len, ...);
813 * @param result buffer for the derived key, allocated by caller
814 * @param out_len desired length of the derived key
815 * @param xtr_algo hash algorithm for the extraction phase, GCRY_MD_...
816 * @param prf_algo hash algorithm for the expansion phase, GCRY_MD_...
818 * @param xts_len length of @a xts
819 * @param skm source key material
820 * @param skm_len length of @a skm
821 * @param ... pair of void * & size_t for context chunks, terminated by NULL
822 * @return #GNUNET_YES on success
825 GNUNET_CRYPTO_hkdf (void *result, size_t out_len, int xtr_algo, int prf_algo,
826 const void *xts, size_t xts_len, const void *skm,
827 size_t skm_len, ...);
833 * @param result buffer for the derived key, allocated by caller
834 * @param out_len desired length of the derived key
835 * @param xtr_algo hash algorithm for the extraction phase, GCRY_MD_...
836 * @param prf_algo hash algorithm for the expansion phase, GCRY_MD_...
838 * @param xts_len length of @a xts
839 * @param skm source key material
840 * @param skm_len length of @a skm
841 * @param argp va_list of void * & size_t pairs for context chunks
842 * @return #GNUNET_YES on success
845 GNUNET_CRYPTO_hkdf_v (void *result, size_t out_len, int xtr_algo, int prf_algo,
846 const void *xts, size_t xts_len, const void *skm,
847 size_t skm_len, va_list argp);
852 * @param result buffer for the derived key, allocated by caller
853 * @param out_len desired length of the derived key
855 * @param xts_len length of @a xts
856 * @param skm source key material
857 * @param skm_len length of @a skm
858 * @param argp va_list of void * & size_t pairs for context chunks
859 * @return #GNUNET_YES on success
862 GNUNET_CRYPTO_kdf_v (void *result, size_t out_len, const void *xts,
863 size_t xts_len, const void *skm, size_t skm_len,
870 * @param result buffer for the derived key, allocated by caller
871 * @param out_len desired length of the derived key
873 * @param xts_len length of @a xts
874 * @param skm source key material
875 * @param skm_len length of @a skm
876 * @param ... void * & size_t pairs for context chunks
877 * @return #GNUNET_YES on success
880 GNUNET_CRYPTO_kdf (void *result, size_t out_len, const void *xts,
881 size_t xts_len, const void *skm, size_t skm_len, ...);
886 * Extract the public key for the given private key.
888 * @param priv the private key
889 * @param pub where to write the public key
892 GNUNET_CRYPTO_ecdsa_key_get_public (const struct GNUNET_CRYPTO_EcdsaPrivateKey *priv,
893 struct GNUNET_CRYPTO_EcdsaPublicKey *pub);
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_eddsa_key_get_public (const struct GNUNET_CRYPTO_EddsaPrivateKey *priv,
904 struct GNUNET_CRYPTO_EddsaPublicKey *pub);
909 * Extract the public key for the given private key.
911 * @param priv the private key
912 * @param pub where to write the public key
915 GNUNET_CRYPTO_ecdhe_key_get_public (const struct GNUNET_CRYPTO_EcdhePrivateKey *priv,
916 struct GNUNET_CRYPTO_EcdhePublicKey *pub);
920 * Convert a public key to a string.
922 * @param pub key to convert
923 * @return string representing @a pub
926 GNUNET_CRYPTO_ecdsa_public_key_to_string (const struct GNUNET_CRYPTO_EcdsaPublicKey *pub);
930 * Convert a public key to a string.
932 * @param pub key to convert
933 * @return string representing @a pub
936 GNUNET_CRYPTO_eddsa_public_key_to_string (const struct GNUNET_CRYPTO_EddsaPublicKey *pub);
940 * Convert a string representing a public key to a public key.
942 * @param enc encoded public key
943 * @param enclen number of bytes in @a enc (without 0-terminator)
944 * @param pub where to store the public key
945 * @return #GNUNET_OK on success
948 GNUNET_CRYPTO_ecdsa_public_key_from_string (const char *enc,
950 struct GNUNET_CRYPTO_EcdsaPublicKey *pub);
954 * Convert a string representing a public key to a public key.
956 * @param enc encoded public key
957 * @param enclen number of bytes in @a enc (without 0-terminator)
958 * @param pub where to store the public key
959 * @return #GNUNET_OK on success
962 GNUNET_CRYPTO_eddsa_public_key_from_string (const char *enc,
964 struct GNUNET_CRYPTO_EddsaPublicKey *pub);
969 * Create a new private key by reading it from a file. If the
970 * files does not exist, create a new key and write it to the
971 * file. Caller must free return value. Note that this function
972 * can not guarantee that another process might not be trying
973 * the same operation on the same file at the same time.
974 * If the contents of the file
975 * are invalid the old file is deleted and a fresh key is
978 * @param filename name of file to use to store the key
979 * @return new private key, NULL on error (for example,
980 * permission denied); free using #GNUNET_free
982 struct GNUNET_CRYPTO_EcdsaPrivateKey *
983 GNUNET_CRYPTO_ecdsa_key_create_from_file (const char *filename);
988 * Create a new private key by reading it from a file. If the
989 * files does not exist, create a new key and write it to the
990 * file. Caller must free return value. Note that this function
991 * can not guarantee that another process might not be trying
992 * the same operation on the same file at the same time.
993 * If the contents of the file
994 * are invalid the old file is deleted and a fresh key is
997 * @param filename name of file to use to store the key
998 * @return new private key, NULL on error (for example,
999 * permission denied); free using #GNUNET_free
1001 struct GNUNET_CRYPTO_EddsaPrivateKey *
1002 GNUNET_CRYPTO_eddsa_key_create_from_file (const char *filename);
1007 * Create a new private key by reading our peer's key from
1008 * the file specified in the configuration.
1010 * @param cfg the configuration to use
1011 * @return new private key, NULL on error (for example,
1012 * permission denied); free using #GNUNET_free
1014 struct GNUNET_CRYPTO_EddsaPrivateKey *
1015 GNUNET_CRYPTO_eddsa_key_create_from_configuration (const struct GNUNET_CONFIGURATION_Handle *cfg);
1020 * Create a new private key. Caller must free return value.
1022 * @return fresh private key; free using #GNUNET_free
1024 struct GNUNET_CRYPTO_EcdsaPrivateKey *
1025 GNUNET_CRYPTO_ecdsa_key_create (void);
1030 * Create a new private key. Caller must free return value.
1032 * @return fresh private key; free using #GNUNET_free
1034 struct GNUNET_CRYPTO_EddsaPrivateKey *
1035 GNUNET_CRYPTO_eddsa_key_create (void);
1040 * Create a new private key. Caller must free return value.
1042 * @return fresh private key; free using #GNUNET_free
1044 struct GNUNET_CRYPTO_EcdhePrivateKey *
1045 GNUNET_CRYPTO_ecdhe_key_create (void);
1050 * Clear memory that was used to store a private key.
1052 * @param pk location of the key
1055 GNUNET_CRYPTO_eddsa_key_clear (struct GNUNET_CRYPTO_EddsaPrivateKey *pk);
1060 * Clear memory that was used to store a private key.
1062 * @param pk location of the key
1065 GNUNET_CRYPTO_ecdsa_key_clear (struct GNUNET_CRYPTO_EcdsaPrivateKey *pk);
1069 * Clear memory that was used to store a private key.
1071 * @param pk location of the key
1074 GNUNET_CRYPTO_ecdhe_key_clear (struct GNUNET_CRYPTO_EcdhePrivateKey *pk);
1079 * Get the shared private key we use for anonymous users.
1081 * @return "anonymous" private key; do not free
1083 const struct GNUNET_CRYPTO_EcdsaPrivateKey *
1084 GNUNET_CRYPTO_ecdsa_key_get_anonymous (void);
1089 * Setup a hostkey file for a peer given the name of the
1090 * configuration file (!). This function is used so that
1091 * at a later point code can be certain that reading a
1092 * hostkey is fast (for example in time-dependent testcases).
1094 * @param cfg_name name of the configuration file to use
1097 GNUNET_CRYPTO_eddsa_setup_hostkey (const char *cfg_name);
1102 * Retrieve the identity of the host's peer.
1104 * @param cfg configuration to use
1105 * @param dst pointer to where to write the peer identity
1106 * @return #GNUNET_OK on success, #GNUNET_SYSERR if the identity
1107 * could not be retrieved
1110 GNUNET_CRYPTO_get_peer_identity (const struct GNUNET_CONFIGURATION_Handle *cfg,
1111 struct GNUNET_PeerIdentity *dst);
1116 * Derive key material from a public and a private ECC key.
1118 * @param priv private key to use for the ECDH (x)
1119 * @param pub public key to use for the ECDH (yG)
1120 * @param key_material where to write the key material (xyG)
1121 * @return #GNUNET_SYSERR on error, #GNUNET_OK on success
1124 GNUNET_CRYPTO_ecc_ecdh (const struct GNUNET_CRYPTO_EcdhePrivateKey *priv,
1125 const struct GNUNET_CRYPTO_EcdhePublicKey *pub,
1126 struct GNUNET_HashCode *key_material);
1131 * EdDSA sign a given block.
1133 * @param priv private key to use for the signing
1134 * @param purpose what to sign (size, purpose)
1135 * @param sig where to write the signature
1136 * @return #GNUNET_SYSERR on error, #GNUNET_OK on success
1139 GNUNET_CRYPTO_eddsa_sign (const struct GNUNET_CRYPTO_EddsaPrivateKey *priv,
1140 const struct GNUNET_CRYPTO_EccSignaturePurpose *purpose,
1141 struct GNUNET_CRYPTO_EddsaSignature *sig);
1146 * ECDSA Sign a given block.
1148 * @param priv private key to use for the signing
1149 * @param purpose what to sign (size, purpose)
1150 * @param sig where to write the signature
1151 * @return #GNUNET_SYSERR on error, #GNUNET_OK on success
1154 GNUNET_CRYPTO_ecdsa_sign (const struct GNUNET_CRYPTO_EcdsaPrivateKey *priv,
1155 const struct GNUNET_CRYPTO_EccSignaturePurpose *purpose,
1156 struct GNUNET_CRYPTO_EcdsaSignature *sig);
1160 * Verify EdDSA signature.
1162 * @param purpose what is the purpose that the signature should have?
1163 * @param validate block to validate (size, purpose, data)
1164 * @param sig signature that is being validated
1165 * @param pub public key of the signer
1166 * @returns #GNUNET_OK if ok, #GNUNET_SYSERR if invalid
1169 GNUNET_CRYPTO_eddsa_verify (uint32_t purpose,
1170 const struct GNUNET_CRYPTO_EccSignaturePurpose *validate,
1171 const struct GNUNET_CRYPTO_EddsaSignature *sig,
1172 const struct GNUNET_CRYPTO_EddsaPublicKey *pub);
1178 * Verify ECDSA signature.
1180 * @param purpose what is the purpose that the signature should have?
1181 * @param validate block to validate (size, purpose, data)
1182 * @param sig signature that is being validated
1183 * @param pub public key of the signer
1184 * @returns #GNUNET_OK if ok, #GNUNET_SYSERR if invalid
1187 GNUNET_CRYPTO_ecdsa_verify (uint32_t purpose,
1188 const struct GNUNET_CRYPTO_EccSignaturePurpose *validate,
1189 const struct GNUNET_CRYPTO_EcdsaSignature *sig,
1190 const struct GNUNET_CRYPTO_EcdsaPublicKey *pub);
1195 * Derive a private key from a given private key and a label.
1196 * Essentially calculates a private key 'h = H(l,P) * d mod n'
1197 * where n is the size of the ECC group and P is the public
1198 * key associated with the private key 'd'.
1200 * @param priv original private key
1201 * @param label label to use for key deriviation
1202 * @param context additional context to use for HKDF of 'h';
1203 * typically the name of the subsystem/application
1204 * @return derived private key
1206 struct GNUNET_CRYPTO_EcdsaPrivateKey *
1207 GNUNET_CRYPTO_ecdsa_private_key_derive (const struct GNUNET_CRYPTO_EcdsaPrivateKey *priv,
1209 const char *context);
1214 * Derive a public key from a given public key and a label.
1215 * Essentially calculates a public key 'V = H(l,P) * P'.
1217 * @param pub original public key
1218 * @param label label to use for key deriviation
1219 * @param context additional context to use for HKDF of 'h'.
1220 * typically the name of the subsystem/application
1221 * @param result where to write the derived public key
1224 GNUNET_CRYPTO_ecdsa_public_key_derive (const struct GNUNET_CRYPTO_EcdsaPublicKey *pub,
1226 const char *context,
1227 struct GNUNET_CRYPTO_EcdsaPublicKey *result);
1230 #if 0 /* keep Emacsens' auto-indent happy */
1238 /* ifndef GNUNET_CRYPTO_LIB_H */
1240 /* end of gnunet_crypto_lib.h */