From bff87d905d127d166a0f169268ac580c372b872a Mon Sep 17 00:00:00 2001 From: Rose Zadik Date: Thu, 25 Jan 2018 21:58:53 +0000 Subject: [PATCH] Improve ECDSA documentation - Rephrase file/function/parameter/enum/define/error descriptions into full and clear sentences. - Make sure to adhere to the Arm writing guidelines. - Fix missing/incorrect Doxygen tags. - Standardize terminology used within the file. GitHub PR: #1318 --- include/mbedtls/ecdsa.h | 275 ++++++++++++++++++++++++---------------- 1 file changed, 168 insertions(+), 107 deletions(-) diff --git a/include/mbedtls/ecdsa.h b/include/mbedtls/ecdsa.h index 6c6ae294f..aa23d67f9 100644 --- a/include/mbedtls/ecdsa.h +++ b/include/mbedtls/ecdsa.h @@ -1,10 +1,16 @@ /** * \file ecdsa.h * - * \brief Elliptic curve DSA + * \brief The Elliptic Curve Digital Signature Algorithm (ECDSA). + * + * ECDSA is defined in Standards for Efficient Cryptography Group (SECG): + * SEC1 Elliptic Curve Cryptography. + * The use of ECDSA for TLS is defined in RFC-4492: Elliptic Curve + * Cryptography (ECC) Cipher Suites for Transport Layer Security (TLS). + * */ /* - * Copyright (C) 2006-2015, ARM Limited, All Rights Reserved + * Copyright (C) 2006-2018, Arm Limited (or its affiliates), All Rights Reserved * SPDX-License-Identifier: Apache-2.0 * * Licensed under the Apache License, Version 2.0 (the "License"); you may @@ -19,8 +25,9 @@ * See the License for the specific language governing permissions and * limitations under the License. * - * This file is part of mbed TLS (https://tls.mbed.org) + * This file is part of Mbed TLS (https://tls.mbed.org) */ + #ifndef MBEDTLS_ECDSA_H #define MBEDTLS_ECDSA_H @@ -28,7 +35,7 @@ #include "md.h" /* - * RFC 4492 page 20: + * RFC-4492 page 20: * * Ecdsa-Sig-Value ::= SEQUENCE { * r INTEGER, @@ -44,11 +51,11 @@ #if MBEDTLS_ECP_MAX_BYTES > 124 #error "MBEDTLS_ECP_MAX_BYTES bigger than expected, please fix MBEDTLS_ECDSA_MAX_LEN" #endif -/** Maximum size of an ECDSA signature in bytes */ +/** The maximal size of an ECDSA signature in Bytes. */ #define MBEDTLS_ECDSA_MAX_LEN ( 3 + 2 * ( 3 + MBEDTLS_ECP_MAX_BYTES ) ) /** - * \brief ECDSA context structure + * \brief The ECDSA context structure. */ typedef mbedtls_ecp_keypair mbedtls_ecdsa_context; @@ -57,25 +64,30 @@ extern "C" { #endif /** - * \brief Compute ECDSA signature of a previously hashed message + * \brief This function computes the ECDSA signature of a + * previously-hashed message. * - * \note The deterministic version is usually prefered. + * \note The deterministic version is usually preferred. * - * \param grp ECP group - * \param r First output integer - * \param s Second output integer - * \param d Private signing key - * \param buf Message hash - * \param blen Length of buf - * \param f_rng RNG function - * \param p_rng RNG parameter + * \param grp The ECP group. + * \param r The first output integer. + * \param s The second output integer. + * \param d The private signing key. + * \param buf The message hash. + * \param blen The length of \p buf. + * \param f_rng The RNG function. + * \param p_rng The RNG parameter. * * \note If the bitlength of the message hash is larger than the - * bitlength of the group order, then the hash is truncated as - * prescribed by SEC1 4.1.3 step 5. + * bitlength of the group order, then the hash is truncated + * as defined in Standards for Efficient Cryptography Group + * (SECG): SEC1 Elliptic Curve Cryptography, section + * 4.1.3, step 5. * - * \return 0 if successful, - * or a MBEDTLS_ERR_ECP_XXX or MBEDTLS_MPI_XXX error code + * \return \c 0 on success, or 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, @@ -83,23 +95,31 @@ int mbedtls_ecdsa_sign( mbedtls_ecp_group *grp, mbedtls_mpi *r, mbedtls_mpi *s, #if defined(MBEDTLS_ECDSA_DETERMINISTIC) /** - * \brief Compute ECDSA signature of a previously hashed message, - * deterministic version (RFC 6979). + * \brief This function computes the ECDSA signature of a + * previously-hashed message, deterministic version. + * For more information, see RFC-6979: Deterministic + * Usage of the Digital Signature Algorithm (DSA) and Elliptic + * Curve Digital Signature Algorithm (ECDSA). * - * \param grp ECP group - * \param r First output integer - * \param s Second output integer - * \param d Private signing key - * \param buf Message hash - * \param blen Length of buf - * \param md_alg MD algorithm used to hash the message + * \param grp The ECP group. + * \param r The first output integer. + * \param s The second output integer. + * \param d The private signing key. + * \param buf The message hash. + * \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 - * prescribed by SEC1 4.1.3 step 5. + * defined in Standards for Efficient Cryptography Group + * (SECG): SEC1 Elliptic Curve Cryptography, section + * 4.1.3, step 5. * - * \return 0 if successful, - * or a MBEDTLS_ERR_ECP_XXX or MBEDTLS_MPI_XXX error code + * \return \c 0 on success, + * 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, @@ -107,55 +127,73 @@ int mbedtls_ecdsa_sign_det( mbedtls_ecp_group *grp, mbedtls_mpi *r, mbedtls_mpi #endif /* MBEDTLS_ECDSA_DETERMINISTIC */ /** - * \brief Verify ECDSA signature of a previously hashed message + * \brief This function verifies the ECDSA signature of a + * previously-hashed message. * - * \param grp ECP group - * \param buf Message hash - * \param blen Length of buf - * \param Q Public key to use for verification - * \param r First integer of the signature - * \param s Second integer of the signature + * \param grp The ECP group. + * \param buf The message hash. + * \param blen The length of \p buf. + * \param Q The public key to use for verification. + * \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 - * prescribed by SEC1 4.1.4 step 3. + * defined in Standards for Efficient Cryptography Group + * (SECG): SEC1 Elliptic Curve Cryptography, section + * 4.1.4, step 3. * - * \return 0 if successful, - * MBEDTLS_ERR_ECP_BAD_INPUT_DATA if signature is invalid - * or a MBEDTLS_ERR_ECP_XXX or MBEDTLS_MPI_XXX error code + * \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 + * 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, const mbedtls_ecp_point *Q, const mbedtls_mpi *r, const mbedtls_mpi *s); /** - * \brief Compute ECDSA signature and write it to buffer, - * serialized as defined in RFC 4492 page 20. - * (Not thread-safe to use same context in multiple threads) + * \brief This function computes the ECDSA signature and writes it + * to a buffer, serialized as defined in RFC-4492: + * Elliptic Curve Cryptography (ECC) Cipher Suites for + * Transport Layer Security (TLS). * - * \note The deterministic version (RFC 6979) is used if - * MBEDTLS_ECDSA_DETERMINISTIC is defined. + * \warning It is not thread-safe to use the same context in + * multiple threads. * - * \param ctx ECDSA context - * \param md_alg Algorithm that was used to hash the message - * \param hash Message hash - * \param hlen Length of hash - * \param sig Buffer that will hold the signature - * \param slen Length of the signature written - * \param f_rng RNG function - * \param p_rng RNG parameter + * \note The deterministic version is used if + * #MBEDTLS_ECDSA_DETERMINISTIC is defined. For more + * information, see RFC-6979: Deterministic Usage + * of the Digital Signature Algorithm (DSA) and Elliptic + * Curve Digital Signature Algorithm (ECDSA). * - * \note The "sig" buffer must be at least as large as twice the - * size of the curve used, plus 9 (eg. 73 bytes if a 256-bit - * curve is used). MBEDTLS_ECDSA_MAX_LEN is always safe. + * \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 + * #MBEDTLS_ECDSA_MAX_LEN is always safe. * * \note If the bitlength of the message hash is larger than the * bitlength of the group order, then the hash is truncated as - * prescribed by SEC1 4.1.3 step 5. + * defined in Standards for Efficient Cryptography Group + * (SECG): SEC1 Elliptic Curve Cryptography, section + * 4.1.3, step 5. * - * \return 0 if successful, - * or a MBEDTLS_ERR_ECP_XXX, MBEDTLS_ERR_MPI_XXX or - * MBEDTLS_ERR_ASN1_XXX error code + * \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 */ int mbedtls_ecdsa_write_signature( mbedtls_ecdsa_context *ctx, mbedtls_md_type_t md_alg, const unsigned char *hash, size_t hlen, @@ -171,31 +209,43 @@ int mbedtls_ecdsa_write_signature( mbedtls_ecdsa_context *ctx, mbedtls_md_type_t #define MBEDTLS_DEPRECATED #endif /** - * \brief Compute ECDSA signature and write it to buffer, - * serialized as defined in RFC 4492 page 20. - * Deterministic version, RFC 6979. - * (Not thread-safe to use same context in multiple threads) + * \brief This function computes an ECDSA signature and writes it to a buffer, + * serialized as defined in RFC-4492: Elliptic Curve Cryptography + * (ECC) Cipher Suites for Transport Layer Security (TLS). + * + * The deterministic version is defined in RFC-6979: + * Deterministic Usage of the Digital Signature Algorithm (DSA) and + * Elliptic Curve Digital Signature Algorithm (ECDSA). + * + * \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 ECDSA context - * \param hash Message hash - * \param hlen Length of hash - * \param sig Buffer that will hold the signature - * \param slen Length of the signature written - * \param md_alg MD algorithm used to hash the message + * \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 "sig" buffer must be at least as large as twice the - * size of the curve used, plus 9 (eg. 73 bytes if a 256-bit - * curve is used). MBEDTLS_ECDSA_MAX_LEN is always safe. + * \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 + * #MBEDTLS_ECDSA_MAX_LEN is always safe. * * \note If the bitlength of the message hash is larger than the * bitlength of the group order, then the hash is truncated as - * prescribed by SEC1 4.1.3 step 5. + * defined in Standards for Efficient Cryptography Group + * (SECG): SEC1 Elliptic Curve Cryptography, section + * 4.1.3, step 5. * - * \return 0 if successful, - * or a MBEDTLS_ERR_ECP_XXX, MBEDTLS_ERR_MPI_XXX or - * MBEDTLS_ERR_ASN1_XXX error code + * \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 */ int mbedtls_ecdsa_write_signature_det( mbedtls_ecdsa_context *ctx, const unsigned char *hash, size_t hlen, @@ -206,63 +256,74 @@ int mbedtls_ecdsa_write_signature_det( mbedtls_ecdsa_context *ctx, #endif /* MBEDTLS_ECDSA_DETERMINISTIC */ /** - * \brief Read and verify an ECDSA signature + * \brief This function reads and verifies an ECDSA signature. * - * \param ctx ECDSA context - * \param hash Message hash - * \param hlen Size of hash - * \param sig Signature to read and verify - * \param slen Size of sig + * \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 - * prescribed by SEC1 4.1.4 step 3. + * defined in Standards for Efficient Cryptography Group + * (SECG): SEC1 Elliptic Curve Cryptography, section + * 4.1.4, step 3. * - * \return 0 if successful, - * 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 siglen, - * or a MBEDTLS_ERR_ECP_XXX or MBEDTLS_ERR_MPI_XXX error code + * \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 */ int mbedtls_ecdsa_read_signature( mbedtls_ecdsa_context *ctx, const unsigned char *hash, size_t hlen, const unsigned char *sig, size_t slen ); /** - * \brief Generate an ECDSA keypair on the given curve + * \brief This function generates an ECDSA keypair on the given curve. * - * \param ctx ECDSA context in which the keypair should be stored - * \param gid Group (elliptic curve) to use. One of the various - * MBEDTLS_ECP_DP_XXX macros depending on configuration. - * \param f_rng RNG function - * \param p_rng RNG parameter + * \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. * - * \return 0 on success, or a MBEDTLS_ERR_ECP_XXX code. + * \return \c 0 on success, or an \c MBEDTLS_ERR_ECP_XXX code on + * failure. + * + * \see ecp.h */ int mbedtls_ecdsa_genkey( mbedtls_ecdsa_context *ctx, mbedtls_ecp_group_id gid, int (*f_rng)(void *, unsigned char *, size_t), void *p_rng ); /** - * \brief Set an ECDSA context from an EC key pair + * \brief This function sets an ECDSA context from an EC key pair. * - * \param ctx ECDSA context to set - * \param key EC key to use + * \param ctx The ECDSA context to set. + * \param key The EC key to use. * - * \return 0 on success, or a MBEDTLS_ERR_ECP_XXX code. + * \return \c 0 on success, or an \c MBEDTLS_ERR_ECP_XXX code on + * failure. + * + * \see ecp.h */ int mbedtls_ecdsa_from_keypair( mbedtls_ecdsa_context *ctx, const mbedtls_ecp_keypair *key ); /** - * \brief Initialize context + * \brief This function initializes an ECDSA context. * - * \param ctx Context to initialize + * \param ctx The ECDSA context to initialize. */ void mbedtls_ecdsa_init( mbedtls_ecdsa_context *ctx ); /** - * \brief Free context + * \brief This function frees an ECDSA context. * - * \param ctx Context to free + * \param ctx The ECDSA context to free. */ void mbedtls_ecdsa_free( mbedtls_ecdsa_context *ctx );