-skeletons for transport-ng

[oweals/gnunet.git] / src / include / gnunet_crypto_lib.h

diff --git a/src/include/gnunet_crypto_lib.h b/src/include/gnunet_crypto_lib.h
index bd95ad3c3d0ecc3e2a96f0def0e74b476ce2a796..8002b771098b5cac3c960f1e6069d1a4798dd3ef 100644 (file)
--- a/src/include/gnunet_crypto_lib.h
+++ b/src/include/gnunet_crypto_lib.h
@@ -27,6 +27,7 @@
  * @author Gerd Knorr <kraxel@bytesex.org>
  * @author Ioana Patrascu
  * @author Tzvetan Horozov
+ * @author Jeffrey Burdges <burdges@gnunet.org>
  *
  * @defgroup crypto  Crypto library: cryptographic operations
  * Provides cryptographic primitives.
@@ -1014,6 +1015,26 @@ GNUNET_CRYPTO_kdf_v (void *result,
                      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
@@ -1327,7 +1348,7 @@ struct GNUNET_CRYPTO_EccPoint
  *
  * @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
+ * @return NULL on error
  */
 struct GNUNET_CRYPTO_EccDlogContext *
 GNUNET_CRYPTO_ecc_dlog_prepare (unsigned int max,
@@ -1340,7 +1361,7 @@ GNUNET_CRYPTO_ecc_dlog_prepare (unsigned int max,
  *
  * @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
+ * @return INT_MAX if dlog failed, otherwise the factor
  */
 int
 GNUNET_CRYPTO_ecc_dlog (struct GNUNET_CRYPTO_EccDlogContext *edc,
@@ -1974,16 +1995,17 @@ GNUNET_CRYPTO_rsa_public_key_cmp (struct GNUNET_CRYPTO_RsaPublicKey *p1,
  * Blinds the given message with the given blinding key
  *
  * @param hash hash of the message to sign
- * @param bks the blinding key secret
+ * @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,
                          const struct GNUNET_CRYPTO_RsaBlindingKeySecret *bks,
                          struct GNUNET_CRYPTO_RsaPublicKey *pkey,
-                         char **buffer);
+                         char **buf, size_t *buf_size);
 
 
 /**
@@ -1996,8 +2018,7 @@ GNUNET_CRYPTO_rsa_blind (const struct GNUNET_HashCode *hash,
  */
 struct GNUNET_CRYPTO_RsaSignature *
 GNUNET_CRYPTO_rsa_sign_blinded (const struct GNUNET_CRYPTO_RsaPrivateKey *key,
-                                const void *msg,
-                                size_t msg_len);
+                                const void *msg, size_t msg_len);
 
 
 /**
@@ -2005,7 +2026,7 @@ GNUNET_CRYPTO_rsa_sign_blinded (const struct GNUNET_CRYPTO_RsaPrivateKey *key,
  *
  * @param key private key to use for the signing
  * @param hash the hash of the message to sign
- * @return NULL on error, signature on success
+ * @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,
@@ -2064,7 +2085,7 @@ GNUNET_CRYPTO_rsa_signature_dup (const struct GNUNET_CRYPTO_RsaSignature *sig);
  * @param sig the signature made on the blinded 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_RsaSignature *
 GNUNET_CRYPTO_rsa_unblind (struct GNUNET_CRYPTO_RsaSignature *sig,
@@ -2079,7 +2100,7 @@ GNUNET_CRYPTO_rsa_unblind (struct GNUNET_CRYPTO_RsaSignature *sig,
  * @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,