From 29bd17729dd74080e0070f09654690200c1e11ae Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Tue, 7 Apr 2020 17:51:59 +0200 Subject: improve comments (#6164) --- src/include/gnunet_crypto_lib.h | 28 ++++++++++++++++++++++++---- src/util/crypto_ecc.c | 27 +++++++++++++++++++++++---- 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) -- cgit v1.2.3