/*
This file is part of GNUnet.
- Copyright (C) 2001-2013 Christian Grothoff (and other contributing authors)
+ Copyright (C) 2001-2013 GNUnet e.V.
GNUnet is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published
You should have received a copy of the GNU General Public License
along with GNUnet; see the file COPYING. If not, write to the
- Free Software Foundation, Inc., 59 Temple Place - Suite 330,
- Boston, MA 02111-1307, USA.
+ Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
+ Boston, MA 02110-1301, USA.
*/
/**
* @author Gerd Knorr <kraxel@bytesex.org>
* @author Ioana Patrascu
* @author Tzvetan Horozov
+ * @author Jeffrey Burdges <burdges@gnunet.org>
*
- * @defgroup crypto Cryptographic operations
- * @defgroup hash Hashing and operations on hashes
+ * @defgroup crypto Crypto library: cryptographic operations
+ * Provides cryptographic primitives.
+ *
+ * @see [Documentation](https://gnunet.org/crypto-api)
+ *
+ * @defgroup hash Crypto library: hash operations
+ * Provides hashing and operations on hashes.
+ *
+ * @see [Documentation](https://gnunet.org/crypto-api)
*/
#ifndef GNUNET_CRYPTO_LIB_H
#include "gnunet_common.h"
#include <gcrypt.h>
-/**
- * We need this enum here, but not the entire scheduler API.
- * For the full definition, see gnunet_scheduler_lib.h.
- */
-enum GNUNET_SCHEDULER_Priority;
/**
* @brief A 512-bit hashcode
GNUNET_CRYPTO_seed_weak_random (int32_t seed);
+/**
+ * @ingroup hash
+ * Calculate the checksum of a buffer in one step.
+ *
+ * @param buf buffer to calculate CRC over
+ * @param len number of bytes in @a buf
+ * @return crc8 value
+ */
+uint8_t
+GNUNET_CRYPTO_crc8_n (const void *buf,
+ size_t len);
+
+
/**
* Perform an incremental step in a CRC16 (for TCP/IP) calculation.
*
size_t len);
+
+
/**
* @ingroup hash
* Compute the CRC32 checksum for the first len
va_list argp);
+/**
+ * Deterministically generate a pseudo-random number uniformly from the
+ * integers modulo a libgcrypt mpi.
+ *
+ * @param[out] r MPI value set to the FDH
+ * @param n MPI to work modulo
+ * @param xts salt
+ * @param xts_len length of @a xts
+ * @param skm source key material
+ * @param skm_len length of @a skm
+ * @param ctx context string
+ */
+void
+GNUNET_CRYPTO_kdf_mod_mpi (gcry_mpi_t *r,
+ gcry_mpi_t n,
+ const void *xts, size_t xts_len,
+ const void *skm, size_t skm_len,
+ const char *ctx);
+
+
/**
* @ingroup hash
* @brief Derive key
const struct GNUNET_PeerIdentity *second);
+/**
+ * Internal structure used to cache pre-calculated values for DLOG calculation.
+ */
+struct GNUNET_CRYPTO_EccDlogContext;
+
+
+/**
+ * Point on a curve (always for Curve25519) encoded in a format suitable
+ * for network transmission (ECDH), see http://cr.yp.to/ecdh.html.
+ */
+struct GNUNET_CRYPTO_EccPoint
+{
+ /**
+ * Q consists of an x- and a y-value, each mod p (256 bits), given
+ * here in affine coordinates and Ed25519 standard compact format.
+ */
+ unsigned char q_y[256 / 8];
+};
+
+
+/**
+ * Do pre-calculation for ECC discrete logarithm for small factors.
+ *
+ * @param max maximum value the factor can be
+ * @param mem memory to use (should be smaller than @a max), must not be zero.
+ * @return @a max if dlog failed, otherwise the factor
+ */
+struct GNUNET_CRYPTO_EccDlogContext *
+GNUNET_CRYPTO_ecc_dlog_prepare (unsigned int max,
+ unsigned int mem);
+
+
+/**
+ * Calculate ECC discrete logarithm for small factors.
+ * Opposite of #GNUNET_CRYPTO_ecc_dexp().
+ *
+ * @param dlc precalculated values, determine range of factors
+ * @param input point on the curve to factor
+ * @return `dlc->max` if dlog failed, otherwise the factor
+ */
+int
+GNUNET_CRYPTO_ecc_dlog (struct GNUNET_CRYPTO_EccDlogContext *edc,
+ gcry_mpi_point_t input);
+
+
+/**
+ * Multiply the generator g of the elliptic curve by @a val
+ * to obtain the point on the curve representing @a val.
+ * Afterwards, point addition will correspond to integer
+ * addition. #GNUNET_CRYPTO_ecc_dlog() can be used to
+ * convert a point back to an integer (as long as the
+ * integer is smaller than the MAX of the @a edc context).
+ *
+ * @param edc calculation context for ECC operations
+ * @param val value to encode into a point
+ * @return representation of the value as an ECC point,
+ * must be freed using #GNUNET_CRYPTO_ecc_free()
+ */
+gcry_mpi_point_t
+GNUNET_CRYPTO_ecc_dexp (struct GNUNET_CRYPTO_EccDlogContext *edc,
+ int val);
+
+
+/**
+ * Multiply the generator g of the elliptic curve by @a val
+ * to obtain the point on the curve representing @a val.
+ *
+ * @param edc calculation context for ECC operations
+ * @param val (positive) value to encode into a point
+ * @return representation of the value as an ECC point,
+ * must be freed using #GNUNET_CRYPTO_ecc_free()
+ */
+gcry_mpi_point_t
+GNUNET_CRYPTO_ecc_dexp_mpi (struct GNUNET_CRYPTO_EccDlogContext *edc,
+ gcry_mpi_t val);
+
+
+/**
+ * Multiply the point @a p on the elliptic curve by @a val.
+ *
+ * @param edc calculation context for ECC operations
+ * @param p point to multiply
+ * @param val (positive) value to encode into a point
+ * @return representation of the value as an ECC point,
+ * must be freed using #GNUNET_CRYPTO_ecc_free()
+ */
+gcry_mpi_point_t
+GNUNET_CRYPTO_ecc_pmul_mpi (struct GNUNET_CRYPTO_EccDlogContext *edc,
+ gcry_mpi_point_t p,
+ gcry_mpi_t val);
+
+
+/**
+ * Convert point value to binary representation.
+ *
+ * @param edc calculation context for ECC operations
+ * @param point computational point representation
+ * @param[out] bin binary point representation
+ */
+void
+GNUNET_CRYPTO_ecc_point_to_bin (struct GNUNET_CRYPTO_EccDlogContext *edc,
+ gcry_mpi_point_t point,
+ struct GNUNET_CRYPTO_EccPoint *bin);
+
+
+/**
+ * Convert binary representation of a point to computational representation.
+ *
+ * @param edc calculation context for ECC operations
+ * @param bin binary point representation
+ * @return computational representation
+ */
+gcry_mpi_point_t
+GNUNET_CRYPTO_ecc_bin_to_point (struct GNUNET_CRYPTO_EccDlogContext *edc,
+ const struct GNUNET_CRYPTO_EccPoint *bin);
+
+
+/**
+ * Add two points on the elliptic curve.
+ *
+ * @param edc calculation context for ECC operations
+ * @param a some value
+ * @param b some value
+ * @return @a a + @a b, must be freed using #GNUNET_CRYPTO_ecc_free()
+ */
+gcry_mpi_point_t
+GNUNET_CRYPTO_ecc_add (struct GNUNET_CRYPTO_EccDlogContext *edc,
+ gcry_mpi_point_t a,
+ gcry_mpi_point_t b);
+
+
+/**
+ * Obtain a random point on the curve and its
+ * additive inverse. Both returned values
+ * must be freed using #GNUNET_CRYPTO_ecc_free().
+ *
+ * @param edc calculation context for ECC operations
+ * @param[out] r set to a random point on the curve
+ * @param[out] r_inv set to the additive inverse of @a r
+ */
+void
+GNUNET_CRYPTO_ecc_rnd (struct GNUNET_CRYPTO_EccDlogContext *edc,
+ gcry_mpi_point_t *r,
+ gcry_mpi_point_t *r_inv);
+
+
+/**
+ * Obtain a random scalar for point multiplication on the curve and
+ * its multiplicative inverse.
+ *
+ * @param edc calculation context for ECC operations
+ * @param[out] r set to a random scalar on the curve
+ * @param[out] r_inv set to the multiplicative inverse of @a r
+ */
+void
+GNUNET_CRYPTO_ecc_rnd_mpi (struct GNUNET_CRYPTO_EccDlogContext *edc,
+ gcry_mpi_t *r,
+ gcry_mpi_t *r_inv);
+
+
+/**
+ * Generate a random value mod n.
+ *
+ * @param edc ECC context
+ * @return random value mod n.
+ */
+gcry_mpi_t
+GNUNET_CRYPTO_ecc_random_mod_n (struct GNUNET_CRYPTO_EccDlogContext *edc);
+
+
+/**
+ * Free a point value returned by the API.
+ *
+ * @param p point to free
+ */
+void
+GNUNET_CRYPTO_ecc_free (gcry_mpi_point_t p);
+
+
+/**
+ * Release precalculated values.
+ *
+ * @param dlc dlog context
+ */
+void
+GNUNET_CRYPTO_ecc_dlog_release (struct GNUNET_CRYPTO_EccDlogContext *dlc);
+
+
/**
* @ingroup crypto
* Derive key material from a public and a private ECC key.
const struct GNUNET_CRYPTO_EcdhePublicKey *pub,
struct GNUNET_HashCode *key_material);
+/**
+ * @ingroup crypto
+ * Derive key material from a ECDH public key and a private ECDSA key.
+ * Dual to #GNUNET_CRRYPTO_ecdh_ecdsa.
+ *
+ * @param priv private key from ECDSA to use for the ECDH (x)
+ * @param pub public key to use for the ECDH (yG)
+ * @param key_material where to write the key material H(h(x)yG)
+ * @return #GNUNET_SYSERR on error, #GNUNET_OK on success
+ */
+int
+GNUNET_CRYPTO_ecdsa_ecdh (const struct GNUNET_CRYPTO_EcdsaPrivateKey *priv,
+ const struct GNUNET_CRYPTO_EcdhePublicKey *pub,
+ struct GNUNET_HashCode *key_material);
+
/**
* @ingroup crypto
const struct GNUNET_CRYPTO_EddsaPublicKey *pub,
struct GNUNET_HashCode *key_material);
+/**
+ * @ingroup crypto
+ * Derive key material from a EcDSA public key and a private ECDH key.
+ * Dual to #GNUNET_CRRYPTO_ecdsa_ecdh.
+ *
+ * @param priv private key to use for the ECDH (y)
+ * @param pub public key from ECDSA to use for the ECDH (X=h(x)G)
+ * @param key_material where to write the key material H(yX)=H(h(x)yG)
+ * @return #GNUNET_SYSERR on error, #GNUNET_OK on success
+ */
+int
+GNUNET_CRYPTO_ecdh_ecdsa (const struct GNUNET_CRYPTO_EcdhePrivateKey *priv,
+ const struct GNUNET_CRYPTO_EcdsaPublicKey *pub,
+ struct GNUNET_HashCode *key_material);
+
/**
* @ingroup crypto
/**
* The private information of an RSA key pair.
*/
-struct GNUNET_CRYPTO_rsa_PrivateKey;
+struct GNUNET_CRYPTO_RsaPrivateKey;
/**
* The public information of an RSA key pair.
*/
-struct GNUNET_CRYPTO_rsa_PublicKey;
+struct GNUNET_CRYPTO_RsaPublicKey;
/**
- * Key used to blind a message
+ * Constant-size pre-secret for blinding key generation.
*/
-struct GNUNET_CRYPTO_rsa_BlindingKey;
+struct GNUNET_CRYPTO_RsaBlindingKeySecret
+{
+ /**
+ * Bits used to generate the blinding key. 256 bits
+ * of entropy is enough.
+ */
+ uint32_t pre_secret[8] GNUNET_PACKED;
+};
/**
* @brief an RSA signature
*/
-struct GNUNET_CRYPTO_rsa_Signature;
+struct GNUNET_CRYPTO_RsaSignature;
/**
* @param len length of the key in bits (i.e. 2048)
* @return fresh private key
*/
-struct GNUNET_CRYPTO_rsa_PrivateKey *
+struct GNUNET_CRYPTO_RsaPrivateKey *
GNUNET_CRYPTO_rsa_private_key_create (unsigned int len);
* @param key pointer to the memory to free
*/
void
-GNUNET_CRYPTO_rsa_private_key_free (struct GNUNET_CRYPTO_rsa_PrivateKey *key);
+GNUNET_CRYPTO_rsa_private_key_free (struct GNUNET_CRYPTO_RsaPrivateKey *key);
/**
* @return size of memory allocatedin @a buffer
*/
size_t
-GNUNET_CRYPTO_rsa_private_key_encode (const struct GNUNET_CRYPTO_rsa_PrivateKey *key,
+GNUNET_CRYPTO_rsa_private_key_encode (const struct GNUNET_CRYPTO_RsaPrivateKey *key,
char **buffer);
* @param len the length of the data in @a buf
* @return NULL on error
*/
-struct GNUNET_CRYPTO_rsa_PrivateKey *
+struct GNUNET_CRYPTO_RsaPrivateKey *
GNUNET_CRYPTO_rsa_private_key_decode (const char *buf,
size_t len);
+/**
+ * Duplicate the given private key
+ *
+ * @param key the private key to duplicate
+ * @return the duplicate key; NULL upon error
+ */
+struct GNUNET_CRYPTO_RsaPrivateKey *
+GNUNET_CRYPTO_rsa_private_key_dup (const struct GNUNET_CRYPTO_RsaPrivateKey *key);
+
+
/**
* Extract the public key of the given private key.
*
* @param priv the private key
* @retur NULL on error, otherwise the public key
*/
-struct GNUNET_CRYPTO_rsa_PublicKey *
-GNUNET_CRYPTO_rsa_private_key_get_public (const struct GNUNET_CRYPTO_rsa_PrivateKey *priv);
+struct GNUNET_CRYPTO_RsaPublicKey *
+GNUNET_CRYPTO_rsa_private_key_get_public (const struct GNUNET_CRYPTO_RsaPrivateKey *priv);
/**
* @param hc where to store the hash code
*/
void
-GNUNET_CRYPTO_rsa_public_key_hash (const struct GNUNET_CRYPTO_rsa_PublicKey *key,
+GNUNET_CRYPTO_rsa_public_key_hash (const struct GNUNET_CRYPTO_RsaPublicKey *key,
struct GNUNET_HashCode *hc);
+/**
+ * Obtain the length of the RSA key in bits.
+ *
+ * @param key the public key to introspect
+ * @return length of the key in bits
+ */
+unsigned int
+GNUNET_CRYPTO_rsa_public_key_len (const struct GNUNET_CRYPTO_RsaPublicKey *key);
+
+
/**
* Free memory occupied by the public key.
*
* @param key pointer to the memory to free
*/
void
-GNUNET_CRYPTO_rsa_public_key_free (struct GNUNET_CRYPTO_rsa_PublicKey *key);
+GNUNET_CRYPTO_rsa_public_key_free (struct GNUNET_CRYPTO_RsaPublicKey *key);
/**
* @return size of memory allocated in @a buffer
*/
size_t
-GNUNET_CRYPTO_rsa_public_key_encode (const struct GNUNET_CRYPTO_rsa_PublicKey *key,
+GNUNET_CRYPTO_rsa_public_key_encode (const struct GNUNET_CRYPTO_RsaPublicKey *key,
char **buffer);
* @param len the length of the data in @a buf
* @return NULL on error
*/
-struct GNUNET_CRYPTO_rsa_PublicKey *
+struct GNUNET_CRYPTO_RsaPublicKey *
GNUNET_CRYPTO_rsa_public_key_decode (const char *buf,
size_t len);
* @param key the public key to duplicate
* @return the duplicate key; NULL upon error
*/
-struct GNUNET_CRYPTO_rsa_PublicKey *
-GNUNET_CRYPTO_rsa_public_key_dup (const struct GNUNET_CRYPTO_rsa_PublicKey *key);
-
-
-/**
- * Create a blinding key
- *
- * @param len length of the key in bits (i.e. 2048)
- * @return the newly created blinding key
- */
-struct GNUNET_CRYPTO_rsa_BlindingKey *
-GNUNET_CRYPTO_rsa_blinding_key_create (unsigned int len);
+struct GNUNET_CRYPTO_RsaPublicKey *
+GNUNET_CRYPTO_rsa_public_key_dup (const struct GNUNET_CRYPTO_RsaPublicKey *key);
/**
- * Compare the values of two blinding keys.
+ * Compare the values of two signatures.
*
- * @param b1 one key
- * @param b2 the other key
+ * @param s1 one signature
+ * @param s2 the other signature
* @return 0 if the two are equal
*/
int
-GNUNET_CRYPTO_rsa_blinding_key_cmp (struct GNUNET_CRYPTO_rsa_BlindingKey *b1,
- struct GNUNET_CRYPTO_rsa_BlindingKey *b2);
-
+GNUNET_CRYPTO_rsa_signature_cmp (struct GNUNET_CRYPTO_RsaSignature *s1,
+ struct GNUNET_CRYPTO_RsaSignature *s2);
/**
- * Compare the values of two signatures.
+ * Compare the values of two private keys.
*
- * @param s1 one signature
- * @param s2 the other signature
+ * @param p1 one private key
+ * @param p2 the other private key
* @return 0 if the two are equal
*/
int
-GNUNET_CRYPTO_rsa_signature_cmp (struct GNUNET_CRYPTO_rsa_Signature *s1,
- struct GNUNET_CRYPTO_rsa_Signature *s2);
+GNUNET_CRYPTO_rsa_private_key_cmp (struct GNUNET_CRYPTO_RsaPrivateKey *p1,
+ struct GNUNET_CRYPTO_RsaPrivateKey *p2);
/**
* @return 0 if the two are equal
*/
int
-GNUNET_CRYPTO_rsa_public_key_cmp (struct GNUNET_CRYPTO_rsa_PublicKey *p1,
- struct GNUNET_CRYPTO_rsa_PublicKey *p2);
-
-
-/**
- * Destroy a blinding key
- *
- * @param bkey the blinding key to destroy
- */
-void
-GNUNET_CRYPTO_rsa_blinding_key_free (struct GNUNET_CRYPTO_rsa_BlindingKey *bkey);
-
-
-/**
- * Encode the blinding key in a format suitable for
- * storing it into a file.
- *
- * @param bkey the blinding key
- * @param[out] buffer set to a buffer with the encoded key
- * @return size of memory allocated in @a buffer
- */
-size_t
-GNUNET_CRYPTO_rsa_blinding_key_encode (const struct GNUNET_CRYPTO_rsa_BlindingKey *bkey,
- char **buffer);
-
-
-/**
- * Decode the blinding key from the data-format back
- * to the "normal", internal format.
- *
- * @param buf the buffer where the public key data is stored
- * @param len the length of the data in @a buf
- * @return NULL on error
- */
-struct GNUNET_CRYPTO_rsa_BlindingKey *
-GNUNET_CRYPTO_rsa_blinding_key_decode (const char *buf,
- size_t len);
+GNUNET_CRYPTO_rsa_public_key_cmp (struct GNUNET_CRYPTO_RsaPublicKey *p1,
+ struct GNUNET_CRYPTO_RsaPublicKey *p2);
/**
* @param hash hash of the message to sign
* @param bkey the blinding key
* @param pkey the public key of the signer
- * @param[out] buffer set to a buffer with the blinded message to be signed
- * @return number of bytes stored in @a buffer
+ * @param[out] buf set to a buffer with the blinded message to be signed
+ * @param[out] buf_size number of bytes stored in @a buf
+ * @return GNUNET_YES if successful, GNUNET_NO if RSA key is malicious
*/
-size_t
+int
GNUNET_CRYPTO_rsa_blind (const struct GNUNET_HashCode *hash,
- struct GNUNET_CRYPTO_rsa_BlindingKey *bkey,
- struct GNUNET_CRYPTO_rsa_PublicKey *pkey,
- char **buffer);
+ const struct GNUNET_CRYPTO_RsaBlindingKeySecret *bks,
+ struct GNUNET_CRYPTO_RsaPublicKey *pkey,
+ char **buf, size_t *buf_size);
/**
- * Sign the given message.
+ * Sign a blinded value, which must be a full domain hash of a message.
*
* @param key private key to use for the signing
* @param msg the (blinded) message to sign
* @param msg_len number of bytes in @a msg to sign
* @return NULL on error, signature on success
*/
-struct GNUNET_CRYPTO_rsa_Signature *
-GNUNET_CRYPTO_rsa_sign (const struct GNUNET_CRYPTO_rsa_PrivateKey *key,
- const void *msg,
- size_t msg_len);
+struct GNUNET_CRYPTO_RsaSignature *
+GNUNET_CRYPTO_rsa_sign_blinded (const struct GNUNET_CRYPTO_RsaPrivateKey *key,
+ const void *msg, size_t msg_len);
+
+
+/**
+ * Create and sign a full domain hash of a message.
+ *
+ * @param key private key to use for the signing
+ * @param hash the hash of the message to sign
+ * @return NULL on error, including a malicious RSA key, signature on success
+ */
+struct GNUNET_CRYPTO_RsaSignature *
+GNUNET_CRYPTO_rsa_sign_fdh (const struct GNUNET_CRYPTO_RsaPrivateKey *key,
+ const struct GNUNET_HashCode *hash);
/**
* @param sig memory to free
*/
void
-GNUNET_CRYPTO_rsa_signature_free (struct GNUNET_CRYPTO_rsa_Signature *sig);
+GNUNET_CRYPTO_rsa_signature_free (struct GNUNET_CRYPTO_RsaSignature *sig);
/**
* @return size of memory allocated in @a buffer
*/
size_t
-GNUNET_CRYPTO_rsa_signature_encode (const struct GNUNET_CRYPTO_rsa_Signature *sig,
+GNUNET_CRYPTO_rsa_signature_encode (const struct GNUNET_CRYPTO_RsaSignature *sig,
char **buffer);
* @param len the length of the data in @a buf
* @return NULL on error
*/
-struct GNUNET_CRYPTO_rsa_Signature *
+struct GNUNET_CRYPTO_RsaSignature *
GNUNET_CRYPTO_rsa_signature_decode (const char *buf,
size_t len);
+/**
+ * Duplicate the given rsa signature
+ *
+ * @param sig the signature to duplicate
+ * @return the duplicate key; NULL upon error
+ */
+struct GNUNET_CRYPTO_RsaSignature *
+GNUNET_CRYPTO_rsa_signature_dup (const struct GNUNET_CRYPTO_RsaSignature *sig);
+
+
/**
* Unblind a blind-signed signature. The signature should have been generated
* with #GNUNET_CRYPTO_rsa_sign() using a hash that was blinded with
* #GNUNET_CRYPTO_rsa_blind().
*
* @param sig the signature made on the blinded signature purpose
- * @param bkey the blinding key used to blind the signature purpose
+ * @param bks the blinding key secret used to blind the signature purpose
* @param pkey the public key of the signer
- * @return unblinded signature on success, NULL on error
+ * @return unblinded signature on success, NULL if RSA key is bad or malicious.
*/
-struct GNUNET_CRYPTO_rsa_Signature *
-GNUNET_CRYPTO_rsa_unblind (struct GNUNET_CRYPTO_rsa_Signature *sig,
- struct GNUNET_CRYPTO_rsa_BlindingKey *bkey,
- struct GNUNET_CRYPTO_rsa_PublicKey *pkey);
+struct GNUNET_CRYPTO_RsaSignature *
+GNUNET_CRYPTO_rsa_unblind (struct GNUNET_CRYPTO_RsaSignature *sig,
+ const struct GNUNET_CRYPTO_RsaBlindingKeySecret *bks,
+ struct GNUNET_CRYPTO_RsaPublicKey *pkey);
/**
* @param hash the message to verify to match the @a sig
* @param sig signature that is being validated
* @param public_key public key of the signer
- * @returns #GNUNET_OK if ok, #GNUNET_SYSERR if invalid
+ * @returns #GNUNET_YES if ok, #GNUNET_NO if RSA key is malicious, #GNUNET_SYSERR if signature
*/
int
GNUNET_CRYPTO_rsa_verify (const struct GNUNET_HashCode *hash,
- const struct GNUNET_CRYPTO_rsa_Signature *sig,
- const struct GNUNET_CRYPTO_rsa_PublicKey *public_key);
+ const struct GNUNET_CRYPTO_RsaSignature *sig,
+ const struct GNUNET_CRYPTO_RsaPublicKey *public_key);
#if 0 /* keep Emacsens' auto-indent happy */