improve comments (#6164)

2 files changed, 47 insertions, 8 deletions

diff --git a/src/include/gnunet_crypto_lib.h b/src/include/gnunet_crypto_lib.h
index e0f453b39..c64fb4926 100644
--- 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 fcc8efa2c..d2cbe9450 100644
--- 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)