improve comments (#6164)

diff --git a/src/include/gnunet_crypto_lib.h b/src/include/gnunet_crypto_lib.h
index e0f453b399b086616707d948ab7f9b275d7b1449..c64fb4926296c583892dba579bb98e138d9d528b 100644 (file)
--- a/src/include/gnunet_crypto_lib.h
+++ b/src/include/gnunet_crypto_lib.h
@@ -1639,7 +1639,11 @@ GNUNET_CRYPTO_ecdh_ecdsa (const struct GNUNET_CRYPTO_EcdhePrivateKey *priv,
 
 /**
  * @ingroup crypto
- * EdDSA sign a given block.
+ * EdDSA sign a given block.  The @a purpose data is the
+ * beginning of the data of which the signature is to be
+ * created. The `size` field in @a purpose must correctly
+ * indicate the number of bytes of the data structure, including
+ * its header.
  *
  * @param priv private key to use for the signing
  * @param purpose what to sign (size, purpose)
@@ -1655,7 +1659,11 @@ GNUNET_CRYPTO_eddsa_sign (
 
 /**
  * @ingroup crypto
- * ECDSA Sign a given block.
+ * ECDSA Sign a given block.  The @a purpose data is the
+ * beginning of the data of which the signature is to be
+ * created. The `size` field in @a purpose must correctly
+ * indicate the number of bytes of the data structure, including
+ * its header.
  *
  * @param priv private key to use for the signing
  * @param purpose what to sign (size, purpose)
@@ -1670,7 +1678,13 @@ GNUNET_CRYPTO_ecdsa_sign (
 
 /**
  * @ingroup crypto
- * Verify EdDSA signature.
+ * Verify EdDSA signature.  The @a validate data is the
+ * beginning of the data of which the signature is to be
+ * verified. The `size` field in @a validate must correctly
+ * indicate the number of bytes of the data structure, including
+ * its header.  If @a purpose does not match the purpose given
+ * in @a validate (the latter must be in big endian), signature
+ * verification fails.
  *
  * @param purpose what is the purpose that the signature should have?
  * @param validate block to validate (size, purpose, data)
@@ -1688,7 +1702,13 @@ GNUNET_CRYPTO_eddsa_verify (
 
 /**
  * @ingroup crypto
- * Verify ECDSA signature.
+ * Verify ECDSA signature.  The @a validate data is the
+ * beginning of the data of which the signature is to be
+ * verified. The `size` field in @a validate must correctly
+ * indicate the number of bytes of the data structure, including
+ * its header.  If @a purpose does not match the purpose given
+ * in @a validate (the latter must be in big endian), signature
+ * verification fails.
  *
  * @param purpose what is the purpose that the signature should have?
  * @param validate block to validate (size, purpose, data)

diff --git a/src/util/crypto_ecc.c b/src/util/crypto_ecc.c
index fcc8efa2caeb50f83baef8cc68b7fb7d0c28c87c..d2cbe9450bf366417d2dbfab642fbe57d3ac4199 100644 (file)
--- a/src/util/crypto_ecc.c
+++ b/src/util/crypto_ecc.c
@@ -676,7 +676,11 @@ data_to_ecdsa_value (const struct GNUNET_CRYPTO_EccSignaturePurpose *purpose)
 
 
 /**
- * Sign a given block.
+ * Sign a given block.  The @a purpose data is the
+ * beginning of the data of which the signature is to be
+ * created. The `size` field in @a purpose must correctly
+ * indicate the number of bytes of the data structure, including
+ * its header.
  *
  * @param priv private key to use for the signing
  * @param purpose what to sign (size, purpose)
@@ -734,7 +738,11 @@ GNUNET_CRYPTO_ecdsa_sign (
 
 
 /**
- * Sign a given block.
+ * Sign a given block. The @a purpose data is the
+ * beginning of the data of which the signature is to be
+ * created. The `size` field in @a purpose must correctly
+ * indicate the number of bytes of the data structure, including
+ * its header.
  *
  * @param priv private key to use for the signing
  * @param purpose what to sign (size, purpose)
@@ -764,7 +772,12 @@ GNUNET_CRYPTO_eddsa_sign (
 
 
 /**
- * Verify signature.
+ * Verify signature.   The @a validate data is the
+ * beginning of the data of which the signature is to be
+ * verified. The `size` field in @a validate must correctly
+ * indicate the number of bytes of the data structure, including
+ * its header.  If @a purpose does not match the purpose given
+ * in @a validate (the latter
  *
  * @param purpose what is the purpose that the signature should have?
  * @param validate block to validate (size, purpose, data)
@@ -832,7 +845,13 @@ GNUNET_CRYPTO_ecdsa_verify (
 
 
 /**
- * Verify signature.
+ * Verify signature. The @a validate data is the
+ * beginning of the data of which the signature is to be
+ * verified. The `size` field in @a validate must correctly
+ * indicate the number of bytes of the data structure, including
+ * its header.  If @a purpose does not match the purpose given
+ * in @a validate (the latter must be in big endian), signature
+ * verification fails.
  *
  * @param purpose what is the purpose that the signature should have?
  * @param validate block to validate (size, purpose, data)