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 * How many characters (without 0-terminator) are our ASCII-encoded
115 * public keys (ECDSA/EDDSA/ECDHE).
117 #define GNUNET_CRYPTO_PKEY_ASCII_LENGTH 52
120 * @brief 0-terminated ASCII encoding of a struct GNUNET_HashCode.
122 struct GNUNET_CRYPTO_HashAsciiEncoded
124 unsigned char encoding[104];
128 GNUNET_NETWORK_STRUCT_BEGIN
132 * @brief header of what an ECC signature signs
133 * this must be followed by "size - 8" bytes of
134 * the actual signed data
136 struct GNUNET_CRYPTO_EccSignaturePurpose
139 * How many bytes does this signature sign?
140 * (including this purpose header); in network
143 uint32_t size GNUNET_PACKED;
146 * What does this signature vouch for? This
147 * must contain a GNUNET_SIGNATURE_PURPOSE_XXX
148 * constant (from gnunet_signatures.h). In
149 * network byte order!
151 uint32_t purpose GNUNET_PACKED;
157 * @brief an ECC signature using EdDSA.
158 * See https://gnunet.org/ed25519
160 struct GNUNET_CRYPTO_EddsaSignature
166 unsigned char r[256 / 8];
171 unsigned char s[256 / 8];
178 * @brief an ECC signature using ECDSA
180 struct GNUNET_CRYPTO_EcdsaSignature
186 unsigned char r[256 / 8];
191 unsigned char s[256 / 8];
197 * Public ECC key (always for Curve25519) encoded in a format suitable
198 * for network transmission and EdDSA signatures.
200 struct GNUNET_CRYPTO_EddsaPublicKey
203 * Q consists of an x- and a y-value, each mod p (256 bits), given
204 * here in affine coordinates and Ed25519 standard compact format.
206 unsigned char q_y[256 / 8];
212 * Public ECC key (always for Curve25519) encoded in a format suitable
213 * for network transmission and ECDSA signatures.
215 struct GNUNET_CRYPTO_EcdsaPublicKey
218 * Q consists of an x- and a y-value, each mod p (256 bits), given
219 * here in affine coordinates and Ed25519 standard compact format.
221 unsigned char q_y[256 / 8];
227 * The identity of the host (wraps the signing key of the peer).
229 struct GNUNET_PeerIdentity
231 struct GNUNET_CRYPTO_EddsaPublicKey public_key;
236 * Public ECC key (always for Curve25519) encoded in a format suitable
237 * for network transmission and encryption (ECDH),
238 * See http://cr.yp.to/ecdh.html
240 struct GNUNET_CRYPTO_EcdhePublicKey
243 * Q consists of an x- and a y-value, each mod p (256 bits), given
244 * here in affine coordinates and Ed25519 standard compact format.
246 unsigned char q_y[256 / 8];
251 * Private ECC key encoded for transmission. To be used only for ECDH
252 * key exchange (ECDHE to be precise).
254 struct GNUNET_CRYPTO_EcdhePrivateKey
257 * d is a value mod n, where n has at most 256 bits.
259 unsigned char d[256 / 8];
264 * Private ECC key encoded for transmission. To be used only for ECDSA
267 struct GNUNET_CRYPTO_EcdsaPrivateKey
270 * d is a value mod n, where n has at most 256 bits.
272 unsigned char d[256 / 8];
277 * Private ECC key encoded for transmission. To be used only for EdDSA
280 struct GNUNET_CRYPTO_EddsaPrivateKey
283 * d is a value mod n, where n has at most 256 bits.
285 unsigned char d[256 / 8];
291 * @brief type for session keys
293 struct GNUNET_CRYPTO_SymmetricSessionKey
296 * Actual key for AES.
298 unsigned char aes_key[GNUNET_CRYPTO_AES_KEY_LENGTH];
301 * Actual key for TwoFish.
303 unsigned char twofish_key[GNUNET_CRYPTO_AES_KEY_LENGTH];
307 GNUNET_NETWORK_STRUCT_END
310 * @brief IV for sym cipher
312 * NOTE: must be smaller (!) in size than the
313 * `struct GNUNET_HashCode`.
315 struct GNUNET_CRYPTO_SymmetricInitializationVector
317 unsigned char aes_iv[GNUNET_CRYPTO_AES_KEY_LENGTH / 2];
319 unsigned char twofish_iv[GNUNET_CRYPTO_AES_KEY_LENGTH / 2];
324 * @brief type for (message) authentication keys
326 struct GNUNET_CRYPTO_AuthKey
328 unsigned char key[GNUNET_CRYPTO_HASH_LENGTH];
332 /* **************** Functions and Macros ************* */
336 * Seed a weak random generator. Only #GNUNET_CRYPTO_QUALITY_WEAK-mode generator
339 * @param seed the seed to use
342 GNUNET_CRYPTO_seed_weak_random (int32_t seed);
346 * Perform an incremental step in a CRC16 (for TCP/IP) calculation.
348 * @param sum current sum, initially 0
349 * @param buf buffer to calculate CRC over (must be 16-bit aligned)
350 * @param len number of bytes in @a buf, must be multiple of 2
351 * @return updated crc sum (must be subjected to #GNUNET_CRYPTO_crc16_finish to get actual crc16)
354 GNUNET_CRYPTO_crc16_step (uint32_t sum, const void *buf, size_t len);
358 * Convert results from GNUNET_CRYPTO_crc16_step to final crc16.
360 * @param sum cummulative sum
361 * @return crc16 value
364 GNUNET_CRYPTO_crc16_finish (uint32_t sum);
369 * Calculate the checksum of a buffer in one step.
371 * @param buf buffer to calculate CRC over (must be 16-bit aligned)
372 * @param len number of bytes in @a buf, must be multiple of 2
373 * @return crc16 value
376 GNUNET_CRYPTO_crc16_n (const void *buf, size_t len);
381 * Compute the CRC32 checksum for the first len
382 * bytes of the buffer.
384 * @param buf the data over which we're taking the CRC
385 * @param len the length of the buffer @a buf in bytes
386 * @return the resulting CRC32 checksum
389 GNUNET_CRYPTO_crc32_n (const void *buf, size_t len);
394 * Fill block with a random values.
396 * @param mode desired quality of the random number
397 * @param buffer the buffer to fill
398 * @param length buffer length
401 GNUNET_CRYPTO_random_block (enum GNUNET_CRYPTO_Quality mode, void *buffer, size_t length);
405 * Produce a random value.
407 * @param mode desired quality of the random number
408 * @param i the upper limit (exclusive) for the random number
409 * @return a random value in the interval [0,@a i) (exclusive).
412 GNUNET_CRYPTO_random_u32 (enum GNUNET_CRYPTO_Quality mode, uint32_t i);
417 * Random on unsigned 64-bit values.
419 * @param mode desired quality of the random number
420 * @param max value returned will be in range [0,@a max) (exclusive)
421 * @return random 64-bit number
424 GNUNET_CRYPTO_random_u64 (enum GNUNET_CRYPTO_Quality mode, uint64_t max);
429 * Get an array with a random permutation of the
431 * @param mode #GNUNET_CRYPTO_QUALITY_STRONG if the strong (but expensive) PRNG should be used,
432 * #GNUNET_CRYPTO_QUALITY_WEAK or #GNUNET_CRYPTO_QUALITY_NONCE otherwise
433 * @param n the size of the array
434 * @return the permutation array (allocated from heap)
437 GNUNET_CRYPTO_random_permute (enum GNUNET_CRYPTO_Quality mode, unsigned int n);
442 * Create a new random session key.
444 * @param key key to initialize
447 GNUNET_CRYPTO_symmetric_create_session_key (struct GNUNET_CRYPTO_SymmetricSessionKey *key);
452 * Encrypt a block using a symmetric sessionkey.
454 * @param block the block to encrypt
455 * @param size the size of the @a block
456 * @param sessionkey the key used to encrypt
457 * @param iv the initialization vector to use, use INITVALUE
459 * @return the size of the encrypted block, -1 for errors
462 GNUNET_CRYPTO_symmetric_encrypt (const void *block, size_t size,
463 const struct GNUNET_CRYPTO_SymmetricSessionKey *sessionkey,
464 const struct GNUNET_CRYPTO_SymmetricInitializationVector *iv,
470 * Decrypt a given block using a symmetric sessionkey.
472 * @param block the data to decrypt, encoded as returned by encrypt
473 * @param size how big is the block?
474 * @param sessionkey the key used to decrypt
475 * @param iv the initialization vector to use
476 * @param result address to store the result at
477 * @return -1 on failure, size of decrypted block on success
480 GNUNET_CRYPTO_symmetric_decrypt (const void *block, size_t size,
481 const struct GNUNET_CRYPTO_SymmetricSessionKey *sessionkey,
482 const struct GNUNET_CRYPTO_SymmetricInitializationVector *iv,
488 * @brief Derive an IV
489 * @param iv initialization vector
490 * @param skey session key
491 * @param salt salt for the derivation
492 * @param salt_len size of the @a salt
493 * @param ... pairs of void * & size_t for context chunks, terminated by NULL
496 GNUNET_CRYPTO_symmetric_derive_iv (struct GNUNET_CRYPTO_SymmetricInitializationVector *iv,
497 const struct GNUNET_CRYPTO_SymmetricSessionKey *skey,
499 size_t salt_len, ...);
503 * @brief Derive an IV
504 * @param iv initialization vector
505 * @param skey session key
506 * @param salt salt for the derivation
507 * @param salt_len size of the @a salt
508 * @param argp pairs of void * & size_t for context chunks, terminated by NULL
511 GNUNET_CRYPTO_symmetric_derive_iv_v (struct GNUNET_CRYPTO_SymmetricInitializationVector *iv,
512 const struct GNUNET_CRYPTO_SymmetricSessionKey *skey,
520 * Convert hash to ASCII encoding.
521 * @param block the hash code
522 * @param result where to store the encoding (struct GNUNET_CRYPTO_HashAsciiEncoded can be
523 * safely cast to char*, a '\\0' termination is set).
526 GNUNET_CRYPTO_hash_to_enc (const struct GNUNET_HashCode * block,
527 struct GNUNET_CRYPTO_HashAsciiEncoded *result);
532 * Convert ASCII encoding back to a 'struct GNUNET_HashCode'
534 * @param enc the encoding
535 * @param enclen number of characters in @a enc (without 0-terminator, which can be missing)
536 * @param result where to store the hash code
537 * @return #GNUNET_OK on success, #GNUNET_SYSERR if result has the wrong encoding
540 GNUNET_CRYPTO_hash_from_string2 (const char *enc, size_t enclen,
541 struct GNUNET_HashCode *result);
546 * Convert ASCII encoding back to `struct GNUNET_HashCode`
548 * @param enc the encoding
549 * @param result where to store the hash code
550 * @return #GNUNET_OK on success, #GNUNET_SYSERR if result has the wrong encoding
552 #define GNUNET_CRYPTO_hash_from_string(enc, result) \
553 GNUNET_CRYPTO_hash_from_string2 (enc, strlen(enc), result)
559 * Compute the distance between 2 hashcodes. The
560 * computation must be fast, not involve @a a[0] or @a a[4] (they're used
561 * elsewhere), and be somewhat consistent. And of course, the result
562 * should be a positive number.
564 * @param a some hash code
565 * @param b some hash code
566 * @return number between 0 and UINT32_MAX
569 GNUNET_CRYPTO_hash_distance_u32 (const struct GNUNET_HashCode *a,
570 const struct GNUNET_HashCode *b);
575 * Compute hash of a given block.
577 * @param block the data to hash
578 * @param size size of the @a block
579 * @param ret pointer to where to write the hashcode
582 GNUNET_CRYPTO_hash (const void *block, size_t size, struct GNUNET_HashCode * ret);
587 * Calculate HMAC of a message (RFC 2104)
589 * @param key secret key
590 * @param plaintext input plaintext
591 * @param plaintext_len length of @a plaintext
592 * @param hmac where to store the hmac
595 GNUNET_CRYPTO_hmac (const struct GNUNET_CRYPTO_AuthKey *key,
596 const void *plaintext, size_t plaintext_len,
597 struct GNUNET_HashCode * hmac);
601 * Function called once the hash computation over the
602 * specified file has completed.
605 * @param res resulting hash, NULL on error
607 typedef void (*GNUNET_CRYPTO_HashCompletedCallback) (void *cls,
608 const struct GNUNET_HashCode *res);
612 * Handle to file hashing operation.
614 struct GNUNET_CRYPTO_FileHashContext;
619 * Compute the hash of an entire file.
621 * @param priority scheduling priority to use
622 * @param filename name of file to hash
623 * @param blocksize number of bytes to process in one task
624 * @param callback function to call upon completion
625 * @param callback_cls closure for @a callback
626 * @return NULL on (immediate) errror
628 struct GNUNET_CRYPTO_FileHashContext *
629 GNUNET_CRYPTO_hash_file (enum GNUNET_SCHEDULER_Priority priority,
630 const char *filename, size_t blocksize,
631 GNUNET_CRYPTO_HashCompletedCallback callback,
636 * Cancel a file hashing operation.
638 * @param fhc operation to cancel (callback must not yet have been invoked)
641 GNUNET_CRYPTO_hash_file_cancel (struct GNUNET_CRYPTO_FileHashContext *fhc);
646 * Create a random hash code.
648 * @param mode desired quality level
649 * @param result hash code that is randomized
652 GNUNET_CRYPTO_hash_create_random (enum GNUNET_CRYPTO_Quality mode,
653 struct GNUNET_HashCode *result);
658 * compute @a result = @a b - @a a
660 * @param a some hash code
661 * @param b some hash code
662 * @param result set to @a b - @a a
665 GNUNET_CRYPTO_hash_difference (const struct GNUNET_HashCode *a,
666 const struct GNUNET_HashCode *b,
667 struct GNUNET_HashCode *result);
672 * compute @a result = @a a + @a delta
674 * @param a some hash code
675 * @param delta some hash code
676 * @param result set to @a a + @a delta
679 GNUNET_CRYPTO_hash_sum (const struct GNUNET_HashCode *a,
680 const struct GNUNET_HashCode *delta,
681 struct GNUNET_HashCode *result);
686 * compute result = a ^ b
688 * @param a some hash code
689 * @param b some hash code
690 * @param result set to @a a ^ @a b
693 GNUNET_CRYPTO_hash_xor (const struct GNUNET_HashCode * a, const struct GNUNET_HashCode * b,
694 struct GNUNET_HashCode * result);
699 * Convert a hashcode into a key.
701 * @param hc hash code that serves to generate the key
702 * @param skey set to a valid session key
703 * @param iv set to a valid initialization vector
706 GNUNET_CRYPTO_hash_to_aes_key (const struct GNUNET_HashCode * hc,
707 struct GNUNET_CRYPTO_SymmetricSessionKey *skey,
708 struct GNUNET_CRYPTO_SymmetricInitializationVector *iv);
713 * Obtain a bit from a hashcode.
715 * @param code the `struct GNUNET_HashCode` to index bit-wise
716 * @param bit index into the hashcode, [0...159]
717 * @return Bit \a bit from hashcode \a code, -1 for invalid index
720 GNUNET_CRYPTO_hash_get_bit (const struct GNUNET_HashCode *code,
726 * Determine how many low order bits match in two
727 * `struct GNUNET_HashCodes`. i.e. - 010011 and 011111 share
728 * the first two lowest order bits, and therefore the
729 * return value is two (NOT XOR distance, nor how many
730 * bits match absolutely!).
732 * @param first the first hashcode
733 * @param second the hashcode to compare first to
734 * @return the number of bits that match
737 GNUNET_CRYPTO_hash_matching_bits (const struct GNUNET_HashCode *first,
738 const struct GNUNET_HashCode *second);
743 * Compare function for HashCodes, producing a total ordering
746 * @param h1 some hash code
747 * @param h2 some hash code
748 * @return 1 if @a h1 > @a h2, -1 if @a h1 < @a h2 and 0 if @a h1 == @a h2.
751 GNUNET_CRYPTO_hash_cmp (const struct GNUNET_HashCode *h1,
752 const struct GNUNET_HashCode *h2);
757 * Find out which of the two GNUNET_CRYPTO_hash codes is closer to target
758 * in the XOR metric (Kademlia).
760 * @param h1 some hash code
761 * @param h2 some hash code
762 * @param target some hash code
763 * @return -1 if @a h1 is closer, 1 if @a h2 is closer and 0 if @a h1== @a h2.
766 GNUNET_CRYPTO_hash_xorcmp (const struct GNUNET_HashCode *h1,
767 const struct GNUNET_HashCode *h2,
768 const struct GNUNET_HashCode *target);
773 * @brief Derive an authentication key
774 * @param key authentication key
775 * @param rkey root key
777 * @param salt_len size of the salt
778 * @param argp pair of void * & size_t for context chunks, terminated by NULL
781 GNUNET_CRYPTO_hmac_derive_key_v (struct GNUNET_CRYPTO_AuthKey *key,
782 const struct GNUNET_CRYPTO_SymmetricSessionKey *rkey,
783 const void *salt, size_t salt_len,
789 * @brief Derive an authentication key
790 * @param key authentication key
791 * @param rkey root key
793 * @param salt_len size of the salt
794 * @param ... pair of void * & size_t for context chunks, terminated by NULL
797 GNUNET_CRYPTO_hmac_derive_key (struct GNUNET_CRYPTO_AuthKey *key,
798 const struct GNUNET_CRYPTO_SymmetricSessionKey *rkey,
799 const void *salt, size_t salt_len, ...);
805 * @param result buffer for the derived key, allocated by caller
806 * @param out_len desired length of the derived key
807 * @param xtr_algo hash algorithm for the extraction phase, GCRY_MD_...
808 * @param prf_algo hash algorithm for the expansion phase, GCRY_MD_...
810 * @param xts_len length of @a xts
811 * @param skm source key material
812 * @param skm_len length of @a skm
813 * @param ... pair of void * & size_t for context chunks, terminated by NULL
814 * @return #GNUNET_YES on success
817 GNUNET_CRYPTO_hkdf (void *result, size_t out_len, int xtr_algo, int prf_algo,
818 const void *xts, size_t xts_len, const void *skm,
819 size_t skm_len, ...);
825 * @param result buffer for the derived key, allocated by caller
826 * @param out_len desired length of the derived key
827 * @param xtr_algo hash algorithm for the extraction phase, GCRY_MD_...
828 * @param prf_algo hash algorithm for the expansion phase, GCRY_MD_...
830 * @param xts_len length of @a xts
831 * @param skm source key material
832 * @param skm_len length of @a skm
833 * @param argp va_list of void * & size_t pairs for context chunks
834 * @return #GNUNET_YES on success
837 GNUNET_CRYPTO_hkdf_v (void *result, size_t out_len, int xtr_algo, int prf_algo,
838 const void *xts, size_t xts_len, const void *skm,
839 size_t skm_len, va_list argp);
844 * @param result buffer for the derived key, allocated by caller
845 * @param out_len desired length of the derived key
847 * @param xts_len length of @a xts
848 * @param skm source key material
849 * @param skm_len length of @a skm
850 * @param argp va_list of void * & size_t pairs for context chunks
851 * @return #GNUNET_YES on success
854 GNUNET_CRYPTO_kdf_v (void *result, size_t out_len, const void *xts,
855 size_t xts_len, const void *skm, size_t skm_len,
862 * @param result buffer for the derived key, allocated by caller
863 * @param out_len desired length of the derived key
865 * @param xts_len length of @a xts
866 * @param skm source key material
867 * @param skm_len length of @a skm
868 * @param ... void * & size_t pairs for context chunks
869 * @return #GNUNET_YES on success
872 GNUNET_CRYPTO_kdf (void *result, size_t out_len, const void *xts,
873 size_t xts_len, const void *skm, size_t skm_len, ...);
878 * Extract the public key for the given private key.
880 * @param priv the private key
881 * @param pub where to write the public key
884 GNUNET_CRYPTO_ecdsa_key_get_public (const struct GNUNET_CRYPTO_EcdsaPrivateKey *priv,
885 struct GNUNET_CRYPTO_EcdsaPublicKey *pub);
889 * Extract the public key for the given private key.
891 * @param priv the private key
892 * @param pub where to write the public key
895 GNUNET_CRYPTO_eddsa_key_get_public (const struct GNUNET_CRYPTO_EddsaPrivateKey *priv,
896 struct GNUNET_CRYPTO_EddsaPublicKey *pub);
901 * Extract the public key for the given private key.
903 * @param priv the private key
904 * @param pub where to write the public key
907 GNUNET_CRYPTO_ecdhe_key_get_public (const struct GNUNET_CRYPTO_EcdhePrivateKey *priv,
908 struct GNUNET_CRYPTO_EcdhePublicKey *pub);
912 * Convert a public key to a string.
914 * @param pub key to convert
915 * @return string representing @a pub
918 GNUNET_CRYPTO_ecdsa_public_key_to_string (const struct GNUNET_CRYPTO_EcdsaPublicKey *pub);
922 * Convert a public key to a string.
924 * @param pub key to convert
925 * @return string representing @a pub
928 GNUNET_CRYPTO_eddsa_public_key_to_string (const struct GNUNET_CRYPTO_EddsaPublicKey *pub);
932 * Convert a string representing a public key to a public key.
934 * @param enc encoded public key
935 * @param enclen number of bytes in @a enc (without 0-terminator)
936 * @param pub where to store the public key
937 * @return #GNUNET_OK on success
940 GNUNET_CRYPTO_ecdsa_public_key_from_string (const char *enc,
942 struct GNUNET_CRYPTO_EcdsaPublicKey *pub);
946 * Convert a string representing a public key to a public key.
948 * @param enc encoded public key
949 * @param enclen number of bytes in @a enc (without 0-terminator)
950 * @param pub where to store the public key
951 * @return #GNUNET_OK on success
954 GNUNET_CRYPTO_eddsa_public_key_from_string (const char *enc,
956 struct GNUNET_CRYPTO_EddsaPublicKey *pub);
961 * Create a new private key by reading it from a file. If the
962 * files does not exist, create a new key and write it to the
963 * file. Caller must free return value. Note that this function
964 * can not guarantee that another process might not be trying
965 * the same operation on the same file at the same time.
966 * If the contents of the file
967 * are invalid the old file is deleted and a fresh key is
970 * @param filename name of file to use to store the key
971 * @return new private key, NULL on error (for example,
972 * permission denied); free using #GNUNET_free
974 struct GNUNET_CRYPTO_EcdsaPrivateKey *
975 GNUNET_CRYPTO_ecdsa_key_create_from_file (const char *filename);
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_EddsaPrivateKey *
994 GNUNET_CRYPTO_eddsa_key_create_from_file (const char *filename);
999 * Create a new private key by reading our peer's key from
1000 * the file specified in the configuration.
1002 * @param cfg the configuration to use
1003 * @return new private key, NULL on error (for example,
1004 * permission denied); free using #GNUNET_free
1006 struct GNUNET_CRYPTO_EddsaPrivateKey *
1007 GNUNET_CRYPTO_eddsa_key_create_from_configuration (const struct GNUNET_CONFIGURATION_Handle *cfg);
1012 * Create a new private key. Caller must free return value.
1014 * @return fresh private key; free using #GNUNET_free
1016 struct GNUNET_CRYPTO_EcdsaPrivateKey *
1017 GNUNET_CRYPTO_ecdsa_key_create (void);
1022 * Create a new private key. Caller must free return value.
1024 * @return fresh private key; free using #GNUNET_free
1026 struct GNUNET_CRYPTO_EddsaPrivateKey *
1027 GNUNET_CRYPTO_eddsa_key_create (void);
1032 * Create a new private key. Caller must free return value.
1034 * @return fresh private key; free using #GNUNET_free
1036 struct GNUNET_CRYPTO_EcdhePrivateKey *
1037 GNUNET_CRYPTO_ecdhe_key_create (void);
1042 * Clear memory that was used to store a private key.
1044 * @param pk location of the key
1047 GNUNET_CRYPTO_eddsa_key_clear (struct GNUNET_CRYPTO_EddsaPrivateKey *pk);
1052 * Clear memory that was used to store a private key.
1054 * @param pk location of the key
1057 GNUNET_CRYPTO_ecdsa_key_clear (struct GNUNET_CRYPTO_EcdsaPrivateKey *pk);
1061 * Clear memory that was used to store a private key.
1063 * @param pk location of the key
1066 GNUNET_CRYPTO_ecdhe_key_clear (struct GNUNET_CRYPTO_EcdhePrivateKey *pk);
1071 * Get the shared private key we use for anonymous users.
1073 * @return "anonymous" private key; do not free
1075 const struct GNUNET_CRYPTO_EcdsaPrivateKey *
1076 GNUNET_CRYPTO_ecdsa_key_get_anonymous (void);
1081 * Setup a hostkey file for a peer given the name of the
1082 * configuration file (!). This function is used so that
1083 * at a later point code can be certain that reading a
1084 * hostkey is fast (for example in time-dependent testcases).
1086 * @param cfg_name name of the configuration file to use
1089 GNUNET_CRYPTO_eddsa_setup_hostkey (const char *cfg_name);
1094 * Retrieve the identity of the host's peer.
1096 * @param cfg configuration to use
1097 * @param dst pointer to where to write the peer identity
1098 * @return #GNUNET_OK on success, #GNUNET_SYSERR if the identity
1099 * could not be retrieved
1102 GNUNET_CRYPTO_get_peer_identity (const struct GNUNET_CONFIGURATION_Handle *cfg,
1103 struct GNUNET_PeerIdentity *dst);
1106 * Compare two Peer Identities.
1108 * @param first first peer identity
1109 * @param second second peer identity
1110 * @return bigger than 0 if first > second,
1111 * 0 if they are the same
1112 * smaller than 0 if second > first
1115 GNUNET_CRYPTO_cmp_peer_identity (const struct GNUNET_PeerIdentity *first,
1116 const struct GNUNET_PeerIdentity *second);
1121 * Derive key material from a public and a private ECC key.
1123 * @param priv private key to use for the ECDH (x)
1124 * @param pub public key to use for the ECDH (yG)
1125 * @param key_material where to write the key material (xyG)
1126 * @return #GNUNET_SYSERR on error, #GNUNET_OK on success
1129 GNUNET_CRYPTO_ecc_ecdh (const struct GNUNET_CRYPTO_EcdhePrivateKey *priv,
1130 const struct GNUNET_CRYPTO_EcdhePublicKey *pub,
1131 struct GNUNET_HashCode *key_material);
1136 * EdDSA sign a given block.
1138 * @param priv private key to use for the signing
1139 * @param purpose what to sign (size, purpose)
1140 * @param sig where to write the signature
1141 * @return #GNUNET_SYSERR on error, #GNUNET_OK on success
1144 GNUNET_CRYPTO_eddsa_sign (const struct GNUNET_CRYPTO_EddsaPrivateKey *priv,
1145 const struct GNUNET_CRYPTO_EccSignaturePurpose *purpose,
1146 struct GNUNET_CRYPTO_EddsaSignature *sig);
1151 * ECDSA Sign a given block.
1153 * @param priv private key to use for the signing
1154 * @param purpose what to sign (size, purpose)
1155 * @param sig where to write the signature
1156 * @return #GNUNET_SYSERR on error, #GNUNET_OK on success
1159 GNUNET_CRYPTO_ecdsa_sign (const struct GNUNET_CRYPTO_EcdsaPrivateKey *priv,
1160 const struct GNUNET_CRYPTO_EccSignaturePurpose *purpose,
1161 struct GNUNET_CRYPTO_EcdsaSignature *sig);
1165 * Verify EdDSA signature.
1167 * @param purpose what is the purpose that the signature should have?
1168 * @param validate block to validate (size, purpose, data)
1169 * @param sig signature that is being validated
1170 * @param pub public key of the signer
1171 * @returns #GNUNET_OK if ok, #GNUNET_SYSERR if invalid
1174 GNUNET_CRYPTO_eddsa_verify (uint32_t purpose,
1175 const struct GNUNET_CRYPTO_EccSignaturePurpose *validate,
1176 const struct GNUNET_CRYPTO_EddsaSignature *sig,
1177 const struct GNUNET_CRYPTO_EddsaPublicKey *pub);
1183 * Verify ECDSA signature.
1185 * @param purpose what is the purpose that the signature should have?
1186 * @param validate block to validate (size, purpose, data)
1187 * @param sig signature that is being validated
1188 * @param pub public key of the signer
1189 * @returns #GNUNET_OK if ok, #GNUNET_SYSERR if invalid
1192 GNUNET_CRYPTO_ecdsa_verify (uint32_t purpose,
1193 const struct GNUNET_CRYPTO_EccSignaturePurpose *validate,
1194 const struct GNUNET_CRYPTO_EcdsaSignature *sig,
1195 const struct GNUNET_CRYPTO_EcdsaPublicKey *pub);
1200 * Derive a private key from a given private key and a label.
1201 * Essentially calculates a private key 'h = H(l,P) * d mod n'
1202 * where n is the size of the ECC group and P is the public
1203 * key associated with the private key 'd'.
1205 * @param priv original private key
1206 * @param label label to use for key deriviation
1207 * @param context additional context to use for HKDF of 'h';
1208 * typically the name of the subsystem/application
1209 * @return derived private key
1211 struct GNUNET_CRYPTO_EcdsaPrivateKey *
1212 GNUNET_CRYPTO_ecdsa_private_key_derive (const struct GNUNET_CRYPTO_EcdsaPrivateKey *priv,
1214 const char *context);
1219 * Derive a public key from a given public key and a label.
1220 * Essentially calculates a public key 'V = H(l,P) * P'.
1222 * @param pub original public key
1223 * @param label label to use for key deriviation
1224 * @param context additional context to use for HKDF of 'h'.
1225 * typically the name of the subsystem/application
1226 * @param result where to write the derived public key
1229 GNUNET_CRYPTO_ecdsa_public_key_derive (const struct GNUNET_CRYPTO_EcdsaPublicKey *pub,
1231 const char *context,
1232 struct GNUNET_CRYPTO_EcdsaPublicKey *result);
1235 #if 0 /* keep Emacsens' auto-indent happy */
1243 /* ifndef GNUNET_CRYPTO_LIB_H */
1245 /* end of gnunet_crypto_lib.h */