Update ecdsa.h
Minor documentation improvements:
*Standardized file brief description.
*Separated return statements.
*Reordered tags within documentation blocks so that params and returns are last in block.
*p_rng descriptions changed from "parameter" to "context".
diff --git a/include/mbedtls/ecdsa.h b/include/mbedtls/ecdsa.h
index aa23d67..99c6d2e 100644
--- a/include/mbedtls/ecdsa.h
+++ b/include/mbedtls/ecdsa.h
@@ -1,9 +1,10 @@
/**
* \file ecdsa.h
*
- * \brief The Elliptic Curve Digital Signature Algorithm (ECDSA).
+ * \brief This file contains ECDSA definitions and functions.
*
- * ECDSA is defined in <em>Standards for Efficient Cryptography Group (SECG):
+ * The Elliptic Curve Digital Signature Algorithm (ECDSA) is defined in
+ * <em>Standards for Efficient Cryptography Group (SECG):
* SEC1 Elliptic Curve Cryptography</em>.
* The use of ECDSA for TLS is defined in <em>RFC-4492: Elliptic Curve
* Cryptography (ECC) Cipher Suites for Transport Layer Security (TLS)</em>.
@@ -69,6 +70,14 @@
*
* \note The deterministic version is usually preferred.
*
+ * \note If the bitlength of the message hash is larger than the
+ * bitlength of the group order, then the hash is truncated
+ * as defined in <em>Standards for Efficient Cryptography Group
+ * (SECG): SEC1 Elliptic Curve Cryptography</em>, section
+ * 4.1.3, step 5.
+ *
+ * \see ecp.h
+ *
* \param grp The ECP group.
* \param r The first output integer.
* \param s The second output integer.
@@ -76,18 +85,11 @@
* \param buf The message hash.
* \param blen The length of \p buf.
* \param f_rng The RNG function.
- * \param p_rng The RNG parameter.
+ * \param p_rng The RNG context.
*
- * \note If the bitlength of the message hash is larger than the
- * bitlength of the group order, then the hash is truncated
- * as defined in <em>Standards for Efficient Cryptography Group
- * (SECG): SEC1 Elliptic Curve Cryptography</em>, section
- * 4.1.3, step 5.
- *
- * \return \c 0 on success, or an \c MBEDTLS_ERR_ECP_XXX
+ * \return \c 0 on success.
+ * \return An \c MBEDTLS_ERR_ECP_XXX
* or \c MBEDTLS_MPI_XXX error code on failure.
- *
- * \see ecp.h
*/
int mbedtls_ecdsa_sign( mbedtls_ecp_group *grp, mbedtls_mpi *r, mbedtls_mpi *s,
const mbedtls_mpi *d, const unsigned char *buf, size_t blen,
@@ -97,10 +99,19 @@
/**
* \brief This function computes the ECDSA signature of a
* previously-hashed message, deterministic version.
+ *
* For more information, see <em>RFC-6979: Deterministic
* Usage of the Digital Signature Algorithm (DSA) and Elliptic
* Curve Digital Signature Algorithm (ECDSA)</em>.
*
+ * \note If the bitlength of the message hash is larger than the
+ * bitlength of the group order, then the hash is truncated as
+ * defined in <em>Standards for Efficient Cryptography Group
+ * (SECG): SEC1 Elliptic Curve Cryptography</em>, section
+ * 4.1.3, step 5.
+ *
+ * \see ecp.h
+ *
* \param grp The ECP group.
* \param r The first output integer.
* \param s The second output integer.
@@ -109,17 +120,9 @@
* \param blen The length of \p buf.
* \param md_alg The MD algorithm used to hash the message.
*
- * \note If the bitlength of the message hash is larger than the
- * bitlength of the group order, then the hash is truncated as
- * defined in <em>Standards for Efficient Cryptography Group
- * (SECG): SEC1 Elliptic Curve Cryptography</em>, section
- * 4.1.3, step 5.
- *
- * \return \c 0 on success,
- * or an \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_MPI_XXX
+ * \return \c 0 on success.
+ * \return or an \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_MPI_XXX
* error code on failure.
- *
- * \see ecp.h
*/
int mbedtls_ecdsa_sign_det( mbedtls_ecp_group *grp, mbedtls_mpi *r, mbedtls_mpi *s,
const mbedtls_mpi *d, const unsigned char *buf, size_t blen,
@@ -130,6 +133,14 @@
* \brief This function verifies the ECDSA signature of a
* previously-hashed message.
*
+ * \note If the bitlength of the message hash is larger than the
+ * bitlength of the group order, then the hash is truncated as
+ * defined in <em>Standards for Efficient Cryptography Group
+ * (SECG): SEC1 Elliptic Curve Cryptography</em>, section
+ * 4.1.4, step 3.
+ *
+ * \see ecp.h
+ *
* \param grp The ECP group.
* \param buf The message hash.
* \param blen The length of \p buf.
@@ -137,18 +148,10 @@
* \param r The first integer of the signature.
* \param s The second integer of the signature.
*
- * \note If the bitlength of the message hash is larger than the
- * bitlength of the group order, then the hash is truncated as
- * defined in <em>Standards for Efficient Cryptography Group
- * (SECG): SEC1 Elliptic Curve Cryptography</em>, section
- * 4.1.4, step 3.
- *
- * \return \c 0 on success,
- * #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if signature is invalid,
- * or an \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_MPI_XXX
+ * \return \c 0 on success.
+ * \return #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if signature is invalid.
+ * \return An \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_MPI_XXX
* error code on failure for any other reason.
- *
- * \see ecp.h
*/
int mbedtls_ecdsa_verify( mbedtls_ecp_group *grp,
const unsigned char *buf, size_t blen,
@@ -169,15 +172,6 @@
* of the Digital Signature Algorithm (DSA) and Elliptic
* Curve Digital Signature Algorithm (ECDSA)</em>.
*
- * \param ctx The ECDSA context.
- * \param md_alg The message digest that was used to hash the message.
- * \param hash The message hash.
- * \param hlen The length of the hash.
- * \param sig The buffer that holds the signature.
- * \param slen The length of the signature written.
- * \param f_rng The RNG function.
- * \param p_rng The RNG parameter.
- *
* \note The \p sig buffer must be at least twice as large as the
* size of the curve used, plus 9. For example, 73 Bytes if
* a 256-bit curve is used. A buffer length of
@@ -189,11 +183,20 @@
* (SECG): SEC1 Elliptic Curve Cryptography</em>, section
* 4.1.3, step 5.
*
- * \return \c 0 on success,
- * or an \c MBEDTLS_ERR_ECP_XXX, \c MBEDTLS_ERR_MPI_XXX or
- * \c MBEDTLS_ERR_ASN1_XXX error code on failure.
- *
* \see ecp.h
+ *
+ * \param ctx The ECDSA context.
+ * \param md_alg The message digest that was used to hash the message.
+ * \param hash The message hash.
+ * \param hlen The length of the hash.
+ * \param sig The buffer that holds the signature.
+ * \param slen The length of the signature written.
+ * \param f_rng The RNG function.
+ * \param p_rng The RNG context.
+ *
+ * \return \c 0 on success.
+ * \return An \c MBEDTLS_ERR_ECP_XXX, \c MBEDTLS_ERR_MPI_XXX or
+ * \c MBEDTLS_ERR_ASN1_XXX error code on failure.
*/
int mbedtls_ecdsa_write_signature( mbedtls_ecdsa_context *ctx, mbedtls_md_type_t md_alg,
const unsigned char *hash, size_t hlen,
@@ -209,26 +212,17 @@
#define MBEDTLS_DEPRECATED
#endif
/**
- * \brief This function computes an ECDSA signature and writes it to a buffer,
- * serialized as defined in <em>RFC-4492: Elliptic Curve Cryptography
- * (ECC) Cipher Suites for Transport Layer Security (TLS)</em>.
+ * \brief This function computes an ECDSA signature and writes
+ * it to a buffer, serialized as defined in <em>RFC-4492:
+ * Elliptic Curve Cryptography (ECC) Cipher Suites for
+ * Transport Layer Security (TLS)</em>.
*
- * The deterministic version is defined in <em>RFC-6979:
- * Deterministic Usage of the Digital Signature Algorithm (DSA) and
- * Elliptic Curve Digital Signature Algorithm (ECDSA)</em>.
+ * The deterministic version is defined in <em>RFC-6979:
+ * Deterministic Usage of the Digital Signature Algorithm (DSA)
+ * and Elliptic Curve Digital Signature Algorithm (ECDSA)</em>.
*
* \warning It is not thread-safe to use the same context in
* multiple threads.
-
- *
- * \deprecated Superseded by mbedtls_ecdsa_write_signature() in 2.0.0
- *
- * \param ctx The ECDSA context.
- * \param hash The Message hash.
- * \param hlen The length of the hash.
- * \param sig The buffer that holds the signature.
- * \param slen The length of the signature written.
- * \param md_alg The MD algorithm used to hash the message.
*
* \note The \p sig buffer must be at least twice as large as the
* size of the curve used, plus 9. For example, 73 Bytes if a
@@ -241,11 +235,20 @@
* (SECG): SEC1 Elliptic Curve Cryptography</em>, section
* 4.1.3, step 5.
*
- * \return \c 0 on success,
- * or an \c MBEDTLS_ERR_ECP_XXX, \c MBEDTLS_ERR_MPI_XXX or
- * \c MBEDTLS_ERR_ASN1_XXX error code on failure.
- *
* \see ecp.h
+ *
+ * \deprecated Superseded by mbedtls_ecdsa_write_signature() in 2.0.0
+ *
+ * \param ctx The ECDSA context.
+ * \param hash The Message hash.
+ * \param hlen The length of the hash.
+ * \param sig The buffer that holds the signature.
+ * \param slen The length of the signature written.
+ * \param md_alg The MD algorithm used to hash the message.
+ *
+ * \return \c 0 on success.
+ * \return An \c MBEDTLS_ERR_ECP_XXX, \c MBEDTLS_ERR_MPI_XXX or
+ * \c MBEDTLS_ERR_ASN1_XXX error code on failure.
*/
int mbedtls_ecdsa_write_signature_det( mbedtls_ecdsa_context *ctx,
const unsigned char *hash, size_t hlen,
@@ -258,26 +261,26 @@
/**
* \brief This function reads and verifies an ECDSA signature.
*
- * \param ctx The ECDSA context.
- * \param hash The message hash.
- * \param hlen The size of the hash.
- * \param sig The signature to read and verify.
- * \param slen The size of \p sig.
- *
* \note If the bitlength of the message hash is larger than the
* bitlength of the group order, then the hash is truncated as
* defined in <em>Standards for Efficient Cryptography Group
* (SECG): SEC1 Elliptic Curve Cryptography</em>, section
* 4.1.4, step 3.
*
- * \return \c 0 on success,
- * #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if signature is invalid,
- * #MBEDTLS_ERR_ECP_SIG_LEN_MISMATCH if the signature is
- * valid but its actual length is less than \p siglen,
- * or an \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_ERR_MPI_XXX
- * error code on failure for any other reason.
- *
* \see ecp.h
+ *
+ * \param ctx The ECDSA context.
+ * \param hash The message hash.
+ * \param hlen The size of the hash.
+ * \param sig The signature to read and verify.
+ * \param slen The size of \p sig.
+ *
+ * \return \c 0 on success.
+ * \return #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if signature is invalid.
+ * \return #MBEDTLS_ERR_ECP_SIG_LEN_MISMATCH if the signature is
+ * valid but its actual length is less than \p siglen.
+ * \return An \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_ERR_MPI_XXX
+ * error code on failure for any other reason.
*/
int mbedtls_ecdsa_read_signature( mbedtls_ecdsa_context *ctx,
const unsigned char *hash, size_t hlen,
@@ -286,16 +289,16 @@
/**
* \brief This function generates an ECDSA keypair on the given curve.
*
+ * \see ecp.h
+ *
* \param ctx The ECDSA context to store the keypair in.
* \param gid The elliptic curve to use. One of the various
* \c MBEDTLS_ECP_DP_XXX macros depending on configuration.
* \param f_rng The RNG function.
- * \param p_rng The RNG parameter.
+ * \param p_rng The RNG context.
*
- * \return \c 0 on success, or an \c MBEDTLS_ERR_ECP_XXX code on
- * failure.
- *
- * \see ecp.h
+ * \return \c 0 on success.
+ * \return An \c MBEDTLS_ERR_ECP_XXX code on failure.
*/
int mbedtls_ecdsa_genkey( mbedtls_ecdsa_context *ctx, mbedtls_ecp_group_id gid,
int (*f_rng)(void *, unsigned char *, size_t), void *p_rng );
@@ -303,13 +306,13 @@
/**
* \brief This function sets an ECDSA context from an EC key pair.
*
+ * \see ecp.h
+ *
* \param ctx The ECDSA context to set.
* \param key The EC key to use.
*
- * \return \c 0 on success, or an \c MBEDTLS_ERR_ECP_XXX code on
- * failure.
- *
- * \see ecp.h
+ * \return \c 0 on success.
+ * \return An \c MBEDTLS_ERR_ECP_XXX code on failure.
*/
int mbedtls_ecdsa_from_keypair( mbedtls_ecdsa_context *ctx, const mbedtls_ecp_keypair *key );