From 4ee9d24c904cab2c3540bf9f240efe768bd11703 Mon Sep 17 00:00:00 2001 From: Rose Zadik Date: Mon, 26 Mar 2018 17:18:44 +0100 Subject: [PATCH 01/30] Update ccm.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. --- include/mbedtls/ccm.h | 29 +++++++++++++++++------------ 1 file changed, 17 insertions(+), 12 deletions(-) diff --git a/include/mbedtls/ccm.h b/include/mbedtls/ccm.h index 630b7fdf6..93ec157d8 100644 --- a/include/mbedtls/ccm.h +++ b/include/mbedtls/ccm.h @@ -1,8 +1,10 @@ /** * \file ccm.h * - * \brief CCM combines Counter mode encryption with CBC-MAC authentication - * for 128-bit block ciphers. + * \brief This file contains CCM definitions and functions. + * + * CCM combines Counter mode encryption with CBC-MAC authentication + * for 128-bit block ciphers. * * Input to CCM includes the following elements: * * - * \return \c 0 on success, or a cipher specific error code. + * \return \c 0 on success. + * \return A cipher-specific error code on failure. */ int mbedtls_gcm_setkey( mbedtls_gcm_context *ctx, mbedtls_cipher_id_t cipher, @@ -101,15 +104,16 @@ int mbedtls_gcm_setkey( mbedtls_gcm_context *ctx, /** * \brief This function performs GCM encryption or decryption of a buffer. * - * \note For encryption, the output buffer can be the same as the input buffer. - * For decryption, the output buffer cannot be the same as input buffer. - * If the buffers overlap, the output buffer must trail at least 8 Bytes - * behind the input buffer. + * \note For encryption, the output buffer can be the same as the + * input buffer. For decryption, the output buffer cannot be + * the same as input buffer. If the buffers overlap, the output + * buffer must trail at least 8 Bytes behind the input buffer. * * \param ctx The GCM context to use for encryption or decryption. * \param mode The operation to perform: #MBEDTLS_GCM_ENCRYPT or * #MBEDTLS_GCM_DECRYPT. - * \param length The length of the input data. This must be a multiple of 16 except in the last call before mbedtls_gcm_finish(). + * \param length The length of the input data. This must be a multiple of + * 16 except in the last call before mbedtls_gcm_finish(). * \param iv The initialization vector. * \param iv_len The length of the IV. * \param add The buffer holding the additional data. @@ -137,12 +141,13 @@ int mbedtls_gcm_crypt_and_tag( mbedtls_gcm_context *ctx, * \brief This function performs a GCM authenticated decryption of a * buffer. * - * \note For decryption, the output buffer cannot be the same as input buffer. - * If the buffers overlap, the output buffer must trail at least 8 Bytes - * behind the input buffer. + * \note For decryption, the output buffer cannot be the same as + * input buffer. If the buffers overlap, the output buffer + * must trail at least 8 Bytes behind the input buffer. * * \param ctx The GCM context. - * \param length The length of the input data. This must be a multiple of 16 except in the last call before mbedtls_gcm_finish(). + * \param length The length of the input data. This must be a multiple + * of 16 except in the last call before mbedtls_gcm_finish(). * \param iv The initialization vector. * \param iv_len The length of the IV. * \param add The buffer holding the additional data. @@ -152,8 +157,8 @@ int mbedtls_gcm_crypt_and_tag( mbedtls_gcm_context *ctx, * \param input The buffer holding the input data. * \param output The buffer for holding the output data. * - * \return 0 if successful and authenticated, or - * #MBEDTLS_ERR_GCM_AUTH_FAILED if tag does not match. + * \return 0 if successful and authenticated. + * \return #MBEDTLS_ERR_GCM_AUTH_FAILED if tag does not match. */ int mbedtls_gcm_auth_decrypt( mbedtls_gcm_context *ctx, size_t length, @@ -175,10 +180,12 @@ int mbedtls_gcm_auth_decrypt( mbedtls_gcm_context *ctx, * #MBEDTLS_GCM_DECRYPT. * \param iv The initialization vector. * \param iv_len The length of the IV. - * \param add The buffer holding the additional data, or NULL if \p add_len is 0. - * \param add_len The length of the additional data. If 0, \p add is NULL. + * \param add The buffer holding the additional data, or NULL + * if \p add_len is 0. + * \param add_len The length of the additional data. If 0, + * \p add is NULL. * - * \return \c 0 on success. + * \return \c 0 on success. */ int mbedtls_gcm_starts( mbedtls_gcm_context *ctx, int mode, @@ -195,16 +202,18 @@ int mbedtls_gcm_starts( mbedtls_gcm_context *ctx, * Bytes. Only the last call before calling * mbedtls_gcm_finish() can be less than 16 Bytes. * - * \note For decryption, the output buffer cannot be the same as input buffer. - * If the buffers overlap, the output buffer must trail at least 8 Bytes - * behind the input buffer. + * \note For decryption, the output buffer cannot be the same as + * input buffer. If the buffers overlap, the output buffer + * must trail at least 8 Bytes behind the input buffer. * * \param ctx The GCM context. - * \param length The length of the input data. This must be a multiple of 16 except in the last call before mbedtls_gcm_finish(). + * \param length The length of the input data. This must be a multiple of + * 16 except in the last call before mbedtls_gcm_finish(). * \param input The buffer holding the input data. * \param output The buffer for holding the output data. * - * \return \c 0 on success, or #MBEDTLS_ERR_GCM_BAD_INPUT on failure. + * \return \c 0 on success. + * \return #MBEDTLS_ERR_GCM_BAD_INPUT on failure. */ int mbedtls_gcm_update( mbedtls_gcm_context *ctx, size_t length, @@ -222,7 +231,8 @@ int mbedtls_gcm_update( mbedtls_gcm_context *ctx, * \param tag The buffer for holding the tag. * \param tag_len The length of the tag to generate. Must be at least four. * - * \return \c 0 on success, or #MBEDTLS_ERR_GCM_BAD_INPUT on failure. + * \return \c 0 on success. + * \return #MBEDTLS_ERR_GCM_BAD_INPUT on failure. */ int mbedtls_gcm_finish( mbedtls_gcm_context *ctx, unsigned char *tag, @@ -251,7 +261,8 @@ extern "C" { /** * \brief The GCM checkup routine. * - * \return \c 0 on success, or \c 1 on failure. + * \return \c 0 on success. + * \return \c 1 on failure. */ int mbedtls_gcm_self_test( int verbose ); From bd9571a01eb29d2be7dab23925de213021f21d0a Mon Sep 17 00:00:00 2001 From: Rose Zadik Date: Mon, 16 Apr 2018 09:45:12 +0100 Subject: [PATCH 06/30] Update ccm.h minor changes based on comments --- include/mbedtls/ccm.h | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/include/mbedtls/ccm.h b/include/mbedtls/ccm.h index 93ec157d8..f354ef9fb 100644 --- a/include/mbedtls/ccm.h +++ b/include/mbedtls/ccm.h @@ -118,6 +118,7 @@ void mbedtls_ccm_free( mbedtls_ccm_context *ctx ); * 4, 6, 8, 10, 12, 14 or 16. * * \return \c 0 on success. + * \return A cipher-specific error code on failure. */ int mbedtls_ccm_encrypt_and_tag( mbedtls_ccm_context *ctx, size_t length, const unsigned char *iv, size_t iv_len, @@ -143,8 +144,8 @@ int mbedtls_ccm_encrypt_and_tag( mbedtls_ccm_context *ctx, size_t length, * \param tag_len The length of the tag in Bytes. * 4, 6, 8, 10, 12, 14 or 16. * - * \return 0 if successful and authenticated. - * \return #MBEDTLS_ERR_CCM_AUTH_FAILED if the tag does not match. + * \return \c 0 on success. + * \return A cipher-specific error code on failure. */ int mbedtls_ccm_auth_decrypt( mbedtls_ccm_context *ctx, size_t length, const unsigned char *iv, size_t iv_len, From b5607bf61d80d08520dd557e2041599940d2f077 Mon Sep 17 00:00:00 2001 From: Rose Zadik Date: Mon, 16 Apr 2018 10:34:51 +0100 Subject: [PATCH 07/30] Update cipher.h minor changes based on comments --- include/mbedtls/cipher.h | 59 ++++++++++++++++++++-------------------- 1 file changed, 29 insertions(+), 30 deletions(-) diff --git a/include/mbedtls/cipher.h b/include/mbedtls/cipher.h index 216771517..3ecae9b06 100644 --- a/include/mbedtls/cipher.h +++ b/include/mbedtls/cipher.h @@ -72,8 +72,8 @@ extern "C" { * \brief Supported cipher types. * * \warning ARC4 and DES are considered weak ciphers and their use - * constitutes a security risk. We recommend you consider using - * stronger ciphers instead. + * constitutes a security risk. Arm recommends considering stronger + * ciphers instead. */ typedef enum { MBEDTLS_CIPHER_ID_NONE = 0, /**< None. */ @@ -90,7 +90,7 @@ typedef enum { * \brief Supported {cipher type, cipher mode} pairs. * * \warning ARC4 and DES are considered weak ciphers and their use - * constitutes a security risk. We recommend considering stronger + * constitutes a security risk. Arm recommends considering stronger * ciphers instead. */ typedef enum { @@ -228,8 +228,10 @@ typedef struct { */ unsigned int iv_size; - /** Flags to set. For example, if the cipher - supports variable IV sizes or variable key sizes. */ + /** Bitflag comprised of MBEDTLS_CIPHER_VARIABLE_IV_LEN and + * MBEDTLS_CIPHER_VARIABLE_KEY_LEN indicating whether the + * cipher supports variable IV or variable key sizes, respectively. + */ int flags; /** The block size, in Bytes. */ @@ -312,7 +314,8 @@ const mbedtls_cipher_info_t *mbedtls_cipher_info_from_string( const char *cipher * \param cipher_type Type of the cipher to search for. * * \return The cipher information structure associated with the - * given \p cipher_type, or NULL if not found. + * given \p cipher_type. + * \return NULL if the associated cipher information is not found. */ const mbedtls_cipher_info_t *mbedtls_cipher_info_from_type( const mbedtls_cipher_type_t cipher_type ); @@ -405,9 +408,9 @@ static inline mbedtls_cipher_mode_t mbedtls_cipher_get_cipher_mode( const mbedtl * * \param ctx The context of the cipher. Must be initialized. * - * \return The recommended IV size, if no IV has been set. - * 0 for ciphers not using IV or nonce. - * \return The actual size, if an IV has been set. + * \return The recommended IV size if no IV has been set. + * \return 0 for ciphers not using IV or nonce. + * \return The actual size if an IV has been set. */ static inline int mbedtls_cipher_get_iv_size( const mbedtls_cipher_context_t *ctx ) { @@ -475,10 +478,8 @@ static inline int mbedtls_cipher_get_key_bitlen( const mbedtls_cipher_context_t * * \param ctx The context of the cipher. Must be initialized. * - * \return The type of operation: #MBEDTLS_ENCRYPT or - * #MBEDTLS_DECRYPT. - * \return #MBEDTLS_OPERATION_NONE if \p ctx - * has not been initialized. + * \return The type of operation: #MBEDTLS_ENCRYPT or #MBEDTLS_DECRYPT. + * \return #MBEDTLS_OPERATION_NONE if \p ctx has not been initialized. */ static inline mbedtls_operation_t mbedtls_cipher_get_operation( const mbedtls_cipher_context_t *ctx ) { @@ -499,10 +500,10 @@ static inline mbedtls_operation_t mbedtls_cipher_get_operation( const mbedtls_ci * \param operation The operation that the key will be used for: * #MBEDTLS_ENCRYPT or #MBEDTLS_DECRYPT. * - * \returns \c 0 on success. + * \return \c 0 on success. * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA if * parameter verification fails. - * \return A cipher-specific error code. + * \return A cipher-specific error code on failure. */ int mbedtls_cipher_setkey( mbedtls_cipher_context_t *ctx, const unsigned char *key, int key_bitlen, const mbedtls_operation_t operation ); @@ -517,7 +518,7 @@ int mbedtls_cipher_setkey( mbedtls_cipher_context_t *ctx, const unsigned char *k * \param ctx The generic cipher context. * \param mode The padding mode. * - * \returns \c 0 on success. + * \return \c 0 on success. * \return #MBEDTLS_ERR_CIPHER_FEATURE_UNAVAILABLE * if the selected padding mode is not supported. * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA if the cipher mode @@ -538,7 +539,7 @@ int mbedtls_cipher_set_padding_mode( mbedtls_cipher_context_t *ctx, mbedtls_ciph * \param iv_len The IV length for ciphers with variable-size IV. * This parameter is discarded by ciphers with fixed-size IV. * - * \returns \c 0 on success. + * \return \c 0 on success. * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA on failure. */ int mbedtls_cipher_set_iv( mbedtls_cipher_context_t *ctx, @@ -549,7 +550,7 @@ int mbedtls_cipher_set_iv( mbedtls_cipher_context_t *ctx, * * \param ctx The generic cipher context. * - * \returns \c 0 on success. + * \return \c 0 on success. * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA * if parameter verification fails. */ @@ -596,12 +597,12 @@ int mbedtls_cipher_update_ad( mbedtls_cipher_context_t *ctx, * \param olen The length of the output data, to be updated with the * actual number of Bytes written. * - * \returns \c 0 on success. + * \return \c 0 on success. * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA if * parameter verification fails. * \return #MBEDTLS_ERR_CIPHER_FEATURE_UNAVAILABLE on an * unsupported mode for a cipher. - * \return A cipher-specific error code. + * \return A cipher-specific error code on failure. */ int mbedtls_cipher_update( mbedtls_cipher_context_t *ctx, const unsigned char *input, size_t ilen, unsigned char *output, size_t *olen ); @@ -616,15 +617,14 @@ int mbedtls_cipher_update( mbedtls_cipher_context_t *ctx, const unsigned char *i * \param output The buffer to write data to. Needs block_size available. * \param olen The length of the data written to the \p output buffer. * - * \returns \c 0 on success. + * \return \c 0 on success. * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA if * parameter verification fails. * \return #MBEDTLS_ERR_CIPHER_FULL_BLOCK_EXPECTED if decryption * expected a full block but was not provided one. * \return #MBEDTLS_ERR_CIPHER_INVALID_PADDING on invalid padding * while decrypting. - * \return A cipher-specific error code on failure for any other - * reason. + * \return A cipher-specific error code on failure. */ int mbedtls_cipher_finish( mbedtls_cipher_context_t *ctx, unsigned char *output, size_t *olen ); @@ -681,14 +681,13 @@ int mbedtls_cipher_check_tag( mbedtls_cipher_context_t *ctx, * \note Some ciphers do not use IVs nor nonce. For these * ciphers, use \p iv = NULL and \p iv_len = 0. * - * \returns \c 0 on success. + * \return \c 0 on success. * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA, or * #MBEDTLS_ERR_CIPHER_FULL_BLOCK_EXPECTED if decryption * expected a full block but was not provided one. * \return #MBEDTLS_ERR_CIPHER_INVALID_PADDING on invalid padding * while decrypting. - * \return A cipher-specific error code on failure for any other - * reason. + * \return A cipher-specific error code on failure. */ int mbedtls_cipher_crypt( mbedtls_cipher_context_t *ctx, const unsigned char *iv, size_t iv_len, @@ -714,9 +713,9 @@ int mbedtls_cipher_crypt( mbedtls_cipher_context_t *ctx, * \param tag The buffer for the authentication tag. * \param tag_len The desired length of the authentication tag. * - * \returns \c 0 on success. + * \return \c 0 on success. * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA. - * \return A cipher-specific error code. + * \return A cipher-specific error code on failure. */ int mbedtls_cipher_auth_encrypt( mbedtls_cipher_context_t *ctx, const unsigned char *iv, size_t iv_len, @@ -747,10 +746,10 @@ int mbedtls_cipher_auth_encrypt( mbedtls_cipher_context_t *ctx, * \param tag The buffer holding the authentication tag. * \param tag_len The length of the authentication tag. * - * \returns \c 0 on success. + * \return \c 0 on success. * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA. * \return #MBEDTLS_ERR_CIPHER_AUTH_FAILED if data is not authentic. - * \return A cipher-specific error code on failure for any other reason. + * \return A cipher-specific error code on failure. */ int mbedtls_cipher_auth_decrypt( mbedtls_cipher_context_t *ctx, const unsigned char *iv, size_t iv_len, From 14d0d57c512c6286336c40aad2a15d4b32a7a736 Mon Sep 17 00:00:00 2001 From: Rose Zadik Date: Mon, 16 Apr 2018 16:09:30 +0100 Subject: [PATCH 08/30] Update ecdsa.h Minor changes based on review comments --- include/mbedtls/ecdsa.h | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/include/mbedtls/ecdsa.h b/include/mbedtls/ecdsa.h index 99c6d2e52..806c417ef 100644 --- a/include/mbedtls/ecdsa.h +++ b/include/mbedtls/ecdsa.h @@ -121,7 +121,7 @@ int mbedtls_ecdsa_sign( mbedtls_ecp_group *grp, mbedtls_mpi *r, mbedtls_mpi *s, * \param md_alg The MD algorithm used to hash the message. * * \return \c 0 on success. - * \return or an \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_MPI_XXX + * \return An \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_MPI_XXX * error code on failure. */ int mbedtls_ecdsa_sign_det( mbedtls_ecp_group *grp, mbedtls_mpi *r, mbedtls_mpi *s, @@ -149,7 +149,8 @@ int mbedtls_ecdsa_sign_det( mbedtls_ecp_group *grp, mbedtls_mpi *r, mbedtls_mpi * \param s The second integer of the signature. * * \return \c 0 on success. - * \return #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if signature is invalid. + * \return #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if the signature + * is invalid. * \return An \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_MPI_XXX * error code on failure for any other reason. */ @@ -240,7 +241,7 @@ int mbedtls_ecdsa_write_signature( mbedtls_ecdsa_context *ctx, mbedtls_md_type_t * \deprecated Superseded by mbedtls_ecdsa_write_signature() in 2.0.0 * * \param ctx The ECDSA context. - * \param hash The Message hash. + * \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. From 6a7ebc4c8663c19890f3d57ddaae68ac9c9872aa Mon Sep 17 00:00:00 2001 From: Rose Zadik Date: Mon, 16 Apr 2018 16:11:49 +0100 Subject: [PATCH 09/30] Update gcm.h minor fix based on review comments --- include/mbedtls/gcm.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/include/mbedtls/gcm.h b/include/mbedtls/gcm.h index 88408c2cf..119e2752e 100644 --- a/include/mbedtls/gcm.h +++ b/include/mbedtls/gcm.h @@ -158,7 +158,7 @@ int mbedtls_gcm_crypt_and_tag( mbedtls_gcm_context *ctx, * \param output The buffer for holding the output data. * * \return 0 if successful and authenticated. - * \return #MBEDTLS_ERR_GCM_AUTH_FAILED if tag does not match. + * \return #MBEDTLS_ERR_GCM_AUTH_FAILED if the tag does not match. */ int mbedtls_gcm_auth_decrypt( mbedtls_gcm_context *ctx, size_t length, From ef8717984218f9a7d62f121ebb69b6c0219585b7 Mon Sep 17 00:00:00 2001 From: Rose Zadik Date: Tue, 17 Apr 2018 10:41:48 +0100 Subject: [PATCH 10/30] Update ccm.h updated failure returns to "A CCM or cipher-specific error code on failure." --- include/mbedtls/ccm.h | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/include/mbedtls/ccm.h b/include/mbedtls/ccm.h index f354ef9fb..8f252c4bd 100644 --- a/include/mbedtls/ccm.h +++ b/include/mbedtls/ccm.h @@ -78,7 +78,7 @@ void mbedtls_ccm_init( mbedtls_ccm_context *ctx ); * \param keybits The key size in bits. This must be acceptable by the cipher. * * \return \c 0 on success. - * \return A cipher-specific error code on failure. + * \return A CCM or cipher-specific error code on failure. */ int mbedtls_ccm_setkey( mbedtls_ccm_context *ctx, mbedtls_cipher_id_t cipher, @@ -118,7 +118,7 @@ void mbedtls_ccm_free( mbedtls_ccm_context *ctx ); * 4, 6, 8, 10, 12, 14 or 16. * * \return \c 0 on success. - * \return A cipher-specific error code on failure. + * \return A CCM or cipher-specific error code on failure. */ int mbedtls_ccm_encrypt_and_tag( mbedtls_ccm_context *ctx, size_t length, const unsigned char *iv, size_t iv_len, @@ -145,7 +145,7 @@ int mbedtls_ccm_encrypt_and_tag( mbedtls_ccm_context *ctx, size_t length, * 4, 6, 8, 10, 12, 14 or 16. * * \return \c 0 on success. - * \return A cipher-specific error code on failure. + * \return A CCM or cipher-specific error code on failure. */ int mbedtls_ccm_auth_decrypt( mbedtls_ccm_context *ctx, size_t length, const unsigned char *iv, size_t iv_len, From d3c9bfcbeb02fdb89097d33326a6d1efd52c6a73 Mon Sep 17 00:00:00 2001 From: Rose Zadik Date: Tue, 17 Apr 2018 10:56:55 +0100 Subject: [PATCH 11/30] Update ecp.h Reviewed and standardized --- include/mbedtls/ecp.h | 645 +++++++++++++++++++++++------------------- 1 file changed, 351 insertions(+), 294 deletions(-) diff --git a/include/mbedtls/ecp.h b/include/mbedtls/ecp.h index e024da864..89c756b37 100644 --- a/include/mbedtls/ecp.h +++ b/include/mbedtls/ecp.h @@ -1,10 +1,20 @@ /** * \file ecp.h * - * \brief Elliptic curves over GF(p) + * \brief This file contains ECP definitions and functions. + * + * The Elliptic Curve over P (ECP) is defined in Standards for Efficient + * Cryptography Group (SECG): SEC1 Elliptic Curve Cryptography and + * RFC-4492: Elliptic Curve Cryptography (ECC) Cipher Suites + * for Transport Layer Security (TLS). + * + * RFC-2409: The Internet Key Exchange (IKE) defines ECP + * group types. + * */ -/* - * 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 +29,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_ECP_H #define MBEDTLS_ECP_H @@ -31,13 +42,13 @@ */ #define MBEDTLS_ERR_ECP_BAD_INPUT_DATA -0x4F80 /**< Bad input parameters to function. */ #define MBEDTLS_ERR_ECP_BUFFER_TOO_SMALL -0x4F00 /**< The buffer is too small to write to. */ -#define MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE -0x4E80 /**< Requested curve not available. */ +#define MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE -0x4E80 /**< The requested curve not available. */ #define MBEDTLS_ERR_ECP_VERIFY_FAILED -0x4E00 /**< The signature is not valid. */ #define MBEDTLS_ERR_ECP_ALLOC_FAILED -0x4D80 /**< Memory allocation failed. */ -#define MBEDTLS_ERR_ECP_RANDOM_FAILED -0x4D00 /**< Generation of random value, such as (ephemeral) key, failed. */ +#define MBEDTLS_ERR_ECP_RANDOM_FAILED -0x4D00 /**< Generation of random value, such as ephemeral key, failed. */ #define MBEDTLS_ERR_ECP_INVALID_KEY -0x4C80 /**< Invalid private or public key. */ #define MBEDTLS_ERR_ECP_SIG_LEN_MISMATCH -0x4C00 /**< The buffer contains a valid signature followed by more data. */ -#define MBEDTLS_ERR_ECP_HW_ACCEL_FAILED -0x4B80 /**< ECP hardware accelerator failed. */ +#define MBEDTLS_ERR_ECP_HW_ACCEL_FAILED -0x4B80 /**< The ECP hardware accelerator failed. */ #if !defined(MBEDTLS_ECP_ALT) /* @@ -53,9 +64,9 @@ extern "C" { #endif /** - * Domain parameters (curve, subgroup and generator) identifiers. + * Definition of domain parameter identifiers: curve, subgroup and generator. * - * Only curves over prime fields are supported. + * \note Only curves over prime fields are supported. * * \warning This library does not support validation of arbitrary domain * parameters. Therefore, only well-known domain parameters from trusted @@ -63,113 +74,119 @@ extern "C" { */ typedef enum { - MBEDTLS_ECP_DP_NONE = 0, - MBEDTLS_ECP_DP_SECP192R1, /*!< 192-bits NIST curve */ - MBEDTLS_ECP_DP_SECP224R1, /*!< 224-bits NIST curve */ - MBEDTLS_ECP_DP_SECP256R1, /*!< 256-bits NIST curve */ - MBEDTLS_ECP_DP_SECP384R1, /*!< 384-bits NIST curve */ - MBEDTLS_ECP_DP_SECP521R1, /*!< 521-bits NIST curve */ - MBEDTLS_ECP_DP_BP256R1, /*!< 256-bits Brainpool curve */ - MBEDTLS_ECP_DP_BP384R1, /*!< 384-bits Brainpool curve */ - MBEDTLS_ECP_DP_BP512R1, /*!< 512-bits Brainpool curve */ - MBEDTLS_ECP_DP_CURVE25519, /*!< Curve25519 */ - MBEDTLS_ECP_DP_CURVE448, /*!< Curve448 */ - MBEDTLS_ECP_DP_SECP192K1, /*!< 192-bits "Koblitz" curve */ - MBEDTLS_ECP_DP_SECP224K1, /*!< 224-bits "Koblitz" curve */ - MBEDTLS_ECP_DP_SECP256K1, /*!< 256-bits "Koblitz" curve */ + MBEDTLS_ECP_DP_NONE = 0, /*!< Curve not defined. */ + MBEDTLS_ECP_DP_SECP192R1, /*!< Domain parameters for 192-bit NIST curve. */ + MBEDTLS_ECP_DP_SECP224R1, /*!< Domain parameters for 224-bit NIST curve. */ + MBEDTLS_ECP_DP_SECP256R1, /*!< Domain parameters for 256-bit NIST curve. */ + MBEDTLS_ECP_DP_SECP384R1, /*!< Domain parameters for 384-bit NIST curve. */ + MBEDTLS_ECP_DP_SECP521R1, /*!< Domain parameters for 521-bit NIST curve. */ + MBEDTLS_ECP_DP_BP256R1, /*!< Domain parameters for 256-bit Brainpool curve. */ + MBEDTLS_ECP_DP_BP384R1, /*!< Domain parameters for 384-bit Brainpool curve. */ + MBEDTLS_ECP_DP_BP512R1, /*!< Domain parameters for 512-bit Brainpool curve. */ + MBEDTLS_ECP_DP_CURVE25519, /*!< Domain parameters for a Curve25519 curve. */ + MBEDTLS_ECP_DP_CURVE448, /*!< Domain parameters for a Curve448 curve. */ + MBEDTLS_ECP_DP_SECP192K1, /*!< Domain parameters for 192-bit "Koblitz" curve. */ + MBEDTLS_ECP_DP_SECP224K1, /*!< Domain parameters for 224-bit "Koblitz" curve. */ + MBEDTLS_ECP_DP_SECP256K1, /*!< Domain parameters for 256-bit "Koblitz" curve. */ } mbedtls_ecp_group_id; /** - * Number of supported curves (plus one for NONE). + * The number of supported curves, plus one for none. * - * (Montgomery curves excluded for now.) + * \note Montgomery curves are currently excluded. */ #define MBEDTLS_ECP_DP_MAX 12 /** - * Curve information for use by other modules + * Curve information, for use by other modules. */ typedef struct { - mbedtls_ecp_group_id grp_id; /*!< Internal identifier */ - uint16_t tls_id; /*!< TLS NamedCurve identifier */ - uint16_t bit_size; /*!< Curve size in bits */ - const char *name; /*!< Human-friendly name */ + mbedtls_ecp_group_id grp_id; /*!< An internal identifier. */ + uint16_t tls_id; /*!< The TLS NamedCurve identifier. */ + uint16_t bit_size; /*!< The size of the curve in bits. */ + const char *name; /*!< A human-friendly name. */ } mbedtls_ecp_curve_info; /** - * \brief ECP point structure (jacobian coordinates) + * \brief The ECP point structure, in jacobian coordinates. * * \note All functions expect and return points satisfying - * the following condition: Z == 0 or Z == 1. (Other - * values of Z are used by internal functions only.) + * the following condition: \p Z == 0 or \p Z == 1. Other + * values of \p Z are used only by internal functions. * The point is zero, or "at infinity", if Z == 0. * Otherwise, X and Y are its standard (affine) coordinates. */ typedef struct { - mbedtls_mpi X; /*!< the point's X coordinate */ - mbedtls_mpi Y; /*!< the point's Y coordinate */ - mbedtls_mpi Z; /*!< the point's Z coordinate */ + mbedtls_mpi X; /*!< The X coordinate of the ECP point. */ + mbedtls_mpi Y; /*!< The Y coordinate of the ECP point. */ + mbedtls_mpi Z; /*!< The Z coordinate of the ECP point. */ } mbedtls_ecp_point; /** - * \brief ECP group structure + * \brief The ECP group structure. * - * We consider two types of curves equations: - * 1. Short Weierstrass y^2 = x^3 + A x + B mod P (SEC1 + RFC 4492) - * 2. Montgomery, y^2 = x^3 + A x^2 + x mod P (Curve25519 + draft) - * In both cases, a generator G for a prime-order subgroup is fixed. In the - * short weierstrass, this subgroup is actually the whole curve, and its - * cardinal is denoted by N. + * We consider two types of curve equations: + *
  • Short Weierstrass: y^2 = x^3 + \p A x + \p B mod P + * (SEC1 + RFC-4492)
    • + *
  • Montgomery: y^2 = x^3 + A x^2 + x mod P (Curve25519 + draft)
+ * In both cases, the generator (G) for a prime-order subgroup is fixed. * - * In the case of Short Weierstrass curves, our code requires that N is an odd - * prime. (Use odd in mbedtls_ecp_mul() and prime in mbedtls_ecdsa_sign() for blinding.) + * For Short Weierstrass, this subgroup is the whole curve, and its + * cardinal is denoted by \p N. Our code requires that \p N is an odd prime. * - * In the case of Montgomery curves, we don't store A but (A + 2) / 4 which is - * the quantity actually used in the formulas. Also, nbits is not the size of N - * but the required size for private keys. + * \note For blinding, use odd in mbedtls_ecp_mul() and prime in + * mbedtls_ecdsa_sign(). * - * If modp is NULL, reduction modulo P is done using a generic algorithm. - * Otherwise, it must point to a function that takes an mbedtls_mpi in the range - * 0..2^(2*pbits)-1 and transforms it in-place in an integer of little more - * than pbits, so that the integer may be efficiently brought in the 0..P-1 - * range by a few additions or substractions. It must return 0 on success and - * non-zero on failure. + * For Montgomery curves, we do not store \p A, but (A + 2) / 4, which is + * the quantity used in the formulas. Additionally, \p nbits is not the + * size of \p N but the required size for private keys. + * + * If \p modp is NULL, reduction modulo \p P is done using a generic algorithm. + * Otherwise, it must point to a function that takes an \p mbedtls_mpi in the + * range of 0..2^(2*pbits)-1, and transforms it in-place in an integer of + * little more than \p pbits, so that the integer may be efficiently brought + * in the 0..P-1 range by a few additions or substractions. + * + * \return \c 0 on success + * \return Non-zero on failure. */ typedef struct { - mbedtls_ecp_group_id id; /*!< internal group identifier */ - mbedtls_mpi P; /*!< prime modulus of the base field */ - mbedtls_mpi A; /*!< 1. A in the equation, or 2. (A + 2) / 4 */ - mbedtls_mpi B; /*!< 1. B in the equation, or 2. unused */ - mbedtls_ecp_point G; /*!< generator of the (sub)group used */ - mbedtls_mpi N; /*!< the order of G */ - size_t pbits; /*!< number of bits in P */ - size_t nbits; /*!< number of bits in 1. P, or 2. private keys */ - unsigned int h; /*!< internal: 1 if the constants are static */ - int (*modp)(mbedtls_mpi *); /*!< function for fast reduction mod P */ - int (*t_pre)(mbedtls_ecp_point *, void *); /*!< unused */ - int (*t_post)(mbedtls_ecp_point *, void *); /*!< unused */ - void *t_data; /*!< unused */ - mbedtls_ecp_point *T; /*!< pre-computed points for ecp_mul_comb() */ - size_t T_size; /*!< number for pre-computed points */ + mbedtls_ecp_group_id id; /*!< An internal group identifier. */ + mbedtls_mpi P; /*!< A prime modulus of the base field. */ + mbedtls_mpi A; /*!< \p A in the equation or (A + 2) / 4. */ + mbedtls_mpi B; /*!< \p B in the equation or unused. */ + mbedtls_ecp_point G; /*!< The generator of the (sub)group used. */ + mbedtls_mpi N; /*!< The order of \p G. */ + size_t pbits; /*!< The number of bits in \p P.*/ + size_t nbits; /*!< The number of bits in \p P, or the private + keys. */ + unsigned int h; /*!< \internal 1 if the constants are static. */ + int (*modp)(mbedtls_mpi *); /*!< The function for fast reduction mod P.*/ + int (*t_pre)(mbedtls_ecp_point *, void *); /*!< Unused. */ + int (*t_post)(mbedtls_ecp_point *, void *); /*!< Unused. */ + void *t_data; /*!< Unused. */ + mbedtls_ecp_point *T; /*!< Pre-computed points for ecp_mul_comb(). */ + size_t T_size; /*!< The number for pre-computed points. */ } mbedtls_ecp_group; /** - * \brief ECP key pair structure + * \brief The ECP key-pair structure. * - * A generic key pair that could be used for ECDSA, fixed ECDH, etc. + * A generic key-pair that may be used for ECDSA and fixed ECDH, for example. * - * \note Members purposefully in the same order as struc mbedtls_ecdsa_context. + * \note Members are deliberately in the same order as in the + * #mbedtls_ecdsa_context structure. */ typedef struct { - mbedtls_ecp_group grp; /*!< Elliptic curve and base point */ - mbedtls_mpi d; /*!< our secret value */ - mbedtls_ecp_point Q; /*!< our public value */ + mbedtls_ecp_group grp; /*!< The elliptic curve and base point. */ + mbedtls_mpi d; /*!< Our secret value. */ + mbedtls_ecp_point Q; /*!< Our public value. */ } mbedtls_ecp_keypair; @@ -177,15 +194,15 @@ mbedtls_ecp_keypair; * \name SECTION: Module settings * * The configuration options you can set for this module are in this section. - * Either change them in config.h or define them on the compiler command line. + * Either change them in config.h, or define them using the compiler command line. * \{ */ #if !defined(MBEDTLS_ECP_MAX_BITS) /** - * Maximum size of the groups (that is, of N and P) + * The maximum size of the groups, that is, of N and P. */ -#define MBEDTLS_ECP_MAX_BITS 521 /**< Maximum bit size of groups */ +#define MBEDTLS_ECP_MAX_BITS 521 /**< The maximum size of groups, in bits. */ #endif #define MBEDTLS_ECP_MAX_BYTES ( ( MBEDTLS_ECP_MAX_BITS + 7 ) / 8 ) @@ -212,7 +229,7 @@ mbedtls_ecp_keypair; * 224 475 475 453 398 342 * 192 640 640 633 587 476 */ -#define MBEDTLS_ECP_WINDOW_SIZE 6 /**< Maximum window size used */ +#define MBEDTLS_ECP_WINDOW_SIZE 6 /**< The maximum window size used. */ #endif /* MBEDTLS_ECP_WINDOW_SIZE */ #if !defined(MBEDTLS_ECP_FIXED_POINT_OPTIM) @@ -227,7 +244,7 @@ mbedtls_ecp_keypair; * * Change this value to 0 to reduce peak memory usage. */ -#define MBEDTLS_ECP_FIXED_POINT_OPTIM 1 /**< Enable fixed-point speed-up */ +#define MBEDTLS_ECP_FIXED_POINT_OPTIM 1 /**< Enable fixed-point speed-up. */ #endif /* MBEDTLS_ECP_FIXED_POINT_OPTIM */ /* \} name SECTION: Module settings */ @@ -235,25 +252,26 @@ mbedtls_ecp_keypair; /* * Point formats, from RFC 4492's enum ECPointFormat */ -#define MBEDTLS_ECP_PF_UNCOMPRESSED 0 /**< Uncompressed point format */ -#define MBEDTLS_ECP_PF_COMPRESSED 1 /**< Compressed point format */ +#define MBEDTLS_ECP_PF_UNCOMPRESSED 0 /**< Uncompressed point format. */ +#define MBEDTLS_ECP_PF_COMPRESSED 1 /**< Compressed point format. */ /* * Some other constants from RFC 4492 */ -#define MBEDTLS_ECP_TLS_NAMED_CURVE 3 /**< ECCurveType's named_curve */ +#define MBEDTLS_ECP_TLS_NAMED_CURVE 3 /**< The named_curve of ECCurveType. */ /** - * \brief Get the list of supported curves in order of preferrence - * (full information) + * \brief This function retrieves the information defined in + * mbedtls_ecp_curve_info()for all supported curves in order + * of preference. * - * \return A statically allocated array, the last entry is 0. + * \return A statically allocated array. The last entry is 0. */ const mbedtls_ecp_curve_info *mbedtls_ecp_curve_list( void ); /** - * \brief Get the list of supported curves in order of preferrence - * (grp_id only) + * \brief This function retrieves the grp_id of all supported curves + * in order of preference. * * \return A statically allocated array, * terminated with MBEDTLS_ECP_DP_NONE. @@ -261,358 +279,390 @@ const mbedtls_ecp_curve_info *mbedtls_ecp_curve_list( void ); const mbedtls_ecp_group_id *mbedtls_ecp_grp_id_list( void ); /** - * \brief Get curve information from an internal group identifier + * \brief This function retrieves curve information from an internal + * group identifier. * - * \param grp_id A MBEDTLS_ECP_DP_XXX value + * \param grp_id An \c MBEDTLS_ECP_DP_XXX value. * - * \return The associated curve information or NULL + * \return The associated curve information, or NULL. */ const mbedtls_ecp_curve_info *mbedtls_ecp_curve_info_from_grp_id( mbedtls_ecp_group_id grp_id ); /** - * \brief Get curve information from a TLS NamedCurve value + * \brief This function retrieves curve information from a TLS + * NamedCurve value. * - * \param tls_id A MBEDTLS_ECP_DP_XXX value + * \param tls_id An \c MBEDTLS_ECP_DP_XXX value. * - * \return The associated curve information or NULL + * \return The associated curve information, or NULL. */ const mbedtls_ecp_curve_info *mbedtls_ecp_curve_info_from_tls_id( uint16_t tls_id ); /** - * \brief Get curve information from a human-readable name + * \brief This function retrieves curve information from a + * human-readable name. * - * \param name The name + * \param name The human-readable name. * - * \return The associated curve information or NULL + * \return The associated curve information, or NULL. */ const mbedtls_ecp_curve_info *mbedtls_ecp_curve_info_from_name( const char *name ); /** - * \brief Initialize a point (as zero) + * \brief This function initializes a point as zero. + * + * \param pt The point to initialize. */ void mbedtls_ecp_point_init( mbedtls_ecp_point *pt ); /** - * \brief Initialize a group (to something meaningless) + * \brief This function initializes a group to something meaningless. */ void mbedtls_ecp_group_init( mbedtls_ecp_group *grp ); /** - * \brief Initialize a key pair (as an invalid one) + * \brief This function initializes a key pair as an invalid one. + * + * \param key The key pair to initialize. */ void mbedtls_ecp_keypair_init( mbedtls_ecp_keypair *key ); /** - * \brief Free the components of a point + * \brief This function frees the components of a point. + * + * \param pt The point to free. */ void mbedtls_ecp_point_free( mbedtls_ecp_point *pt ); /** - * \brief Free the components of an ECP group + * \brief This function frees the components of an ECP group. + * \param grp The group to free. */ void mbedtls_ecp_group_free( mbedtls_ecp_group *grp ); /** - * \brief Free the components of a key pair + * \brief This function frees the components of a key pair. + * \param key The key pair to free. */ void mbedtls_ecp_keypair_free( mbedtls_ecp_keypair *key ); /** - * \brief Copy the contents of point Q into P + * \brief This function copies the contents of point \p Q into + * point \p P. * - * \param P Destination point - * \param Q Source point + * \param P The destination point. + * \param Q The source point. * - * \return 0 if successful, - * MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed + * \return \c 0 on success. + * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation fails. */ int mbedtls_ecp_copy( mbedtls_ecp_point *P, const mbedtls_ecp_point *Q ); /** - * \brief Copy the contents of a group object + * \brief This function copies the contents of group \p src into + * group \p dst. * - * \param dst Destination group - * \param src Source group + * \param dst The destination group. + * \param src The source group. * - * \return 0 if successful, - * MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed + * \return \c 0 on success. + * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation fails. */ int mbedtls_ecp_group_copy( mbedtls_ecp_group *dst, const mbedtls_ecp_group *src ); /** - * \brief Set a point to zero + * \brief This function sets a point to zero. * - * \param pt Destination point + * \param pt The point to set. * - * \return 0 if successful, - * MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed + * \return \c 0 on success. + * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation fails. */ int mbedtls_ecp_set_zero( mbedtls_ecp_point *pt ); /** - * \brief Tell if a point is zero + * \brief This function checks if a point is zero. * - * \param pt Point to test + * \param pt The point to test. * - * \return 1 if point is zero, 0 otherwise + * \return \c 1 if point is zero. + * \return \c 0 if point is non-zero. */ int mbedtls_ecp_is_zero( mbedtls_ecp_point *pt ); /** - * \brief Compare two points + * \brief This function compares two points. * - * \note This assumes the points are normalized. Otherwise, + * \note This assumes that the points are normalized. Otherwise, * they may compare as "not equal" even if they are. * - * \param P First point to compare - * \param Q Second point to compare + * \param P The first point to compare. + * \param Q The second point to compare. * - * \return 0 if the points are equal, - * MBEDTLS_ERR_ECP_BAD_INPUT_DATA otherwise + * \return \c 0 if the points are equal. + * \return #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if the points are not equal. */ int mbedtls_ecp_point_cmp( const mbedtls_ecp_point *P, const mbedtls_ecp_point *Q ); /** - * \brief Import a non-zero point from two ASCII strings + * \brief This function imports a non-zero point from two ASCII + * strings. * - * \param P Destination point - * \param radix Input numeric base - * \param x First affine coordinate as a null-terminated string - * \param y Second affine coordinate as a null-terminated string + * \param P The destination point. + * \param radix The numeric base of the input. + * \param x The first affine coordinate, as a null-terminated string. + * \param y The second affine coordinate, as a null-terminated string. * - * \return 0 if successful, or a MBEDTLS_ERR_MPI_XXX error code + * \return \c 0 on success. + * \return An \c MBEDTLS_ERR_MPI_XXX error code on failure. */ int mbedtls_ecp_point_read_string( mbedtls_ecp_point *P, int radix, const char *x, const char *y ); /** - * \brief Export a point into unsigned binary data + * \brief This function exports a point into unsigned binary data. * - * \param grp Group to which the point should belong - * \param P Point to export - * \param format Point format, should be a MBEDTLS_ECP_PF_XXX macro - * \param olen Length of the actual output - * \param buf Output buffer - * \param buflen Length of the output buffer + * \param grp The group to which the point should belong. + * \param P The point to export. + * \param format The point format. Should be an \c MBEDTLS_ECP_PF_XXX macro. + * \param olen The length of the output. + * \param buf The output buffer. + * \param buflen The length of the output buffer. * - * \return 0 if successful, - * or MBEDTLS_ERR_ECP_BAD_INPUT_DATA - * or MBEDTLS_ERR_ECP_BUFFER_TOO_SMALL + * \return \c 0 on success. + * \return #MBEDTLS_ERR_ECP_BAD_INPUT_DATA + * or #MBEDTLS_ERR_ECP_BUFFER_TOO_SMALL on failure. */ int mbedtls_ecp_point_write_binary( const mbedtls_ecp_group *grp, const mbedtls_ecp_point *P, int format, size_t *olen, unsigned char *buf, size_t buflen ); /** - * \brief Import a point from unsigned binary data + * \brief This function imports a point from unsigned binary data. * - * \param grp Group to which the point should belong - * \param P Point to import - * \param buf Input buffer - * \param ilen Actual length of input + * \note This function does not check that the point actually + * belongs to the given group, see mbedtls_ecp_check_pubkey() + * for that. * - * \return 0 if successful, - * MBEDTLS_ERR_ECP_BAD_INPUT_DATA if input is invalid, - * MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed, - * MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE if the point format + * \param grp The group to which the point should belong. + * \param P The point to import. + * \param buf The input buffer. + * \param ilen The length of the input. + * + * \return \c 0 on success. + * \return #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if input is invalid. + * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed. + * \return #MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE if the point format * is not implemented. * - * \note This function does NOT check that the point actually - * belongs to the given group, see mbedtls_ecp_check_pubkey() for - * that. */ int mbedtls_ecp_point_read_binary( const mbedtls_ecp_group *grp, mbedtls_ecp_point *P, const unsigned char *buf, size_t ilen ); /** - * \brief Import a point from a TLS ECPoint record + * \brief This function imports a point from a TLS ECPoint record. * - * \param grp ECP group used - * \param pt Destination point - * \param buf $(Start of input buffer) - * \param len Buffer length + * \note On function return, \p buf is updated to point to immediately + * after the ECPoint. * - * \note buf is updated to point right after the ECPoint on exit + * \param grp The ECP group used. + * \param pt The destination point. + * \param buf The address of the pointer to the start of input buffer. + * \param len The length of the buffer. * - * \return 0 if successful, - * MBEDTLS_ERR_MPI_XXX if initialization failed - * MBEDTLS_ERR_ECP_BAD_INPUT_DATA if input is invalid + * \return \c 0 on success. + * \return An \c MBEDTLS_ERR_MPI_XXX error code if initialization failed. + * \return #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if input is invalid. */ int mbedtls_ecp_tls_read_point( const mbedtls_ecp_group *grp, mbedtls_ecp_point *pt, const unsigned char **buf, size_t len ); /** - * \brief Export a point as a TLS ECPoint record + * \brief This function exports a point as a TLS ECPoint record. * - * \param grp ECP group used - * \param pt Point to export - * \param format Export format - * \param olen length of data written - * \param buf Buffer to write to - * \param blen Buffer length + * \param grp The ECP group used. + * \param pt The point to export. + * \param format The export format. + * \param olen The length of data written. + * \param buf The Buffer to write to. + * \param blen The length of the Buffer. * - * \return 0 if successful, - * or MBEDTLS_ERR_ECP_BAD_INPUT_DATA - * or MBEDTLS_ERR_ECP_BUFFER_TOO_SMALL + * \return \c 0 on success. + * \return #MBEDTLS_ERR_ECP_BAD_INPUT_DATA or + * #MBEDTLS_ERR_ECP_BUFFER_TOO_SMALL on failure. */ int mbedtls_ecp_tls_write_point( const mbedtls_ecp_group *grp, const mbedtls_ecp_point *pt, int format, size_t *olen, unsigned char *buf, size_t blen ); /** - * \brief Set a group using well-known domain parameters + * \brief This function sets a group using well-known domain parameters. * - * \param grp Destination group - * \param id Index in the list of well-known domain parameters + * \note The index should be a value of the NamedCurve enum, + * as defined in RFC-4492: Elliptic Curve Cryptography + * (ECC) Cipher Suites for Transport Layer Security (TLS), + * usually in the form of an \c MBEDTLS_ECP_DP_XXX macro. * - * \return 0 if successful, - * MBEDTLS_ERR_MPI_XXX if initialization failed - * MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE for unkownn groups + * \param grp The destination group. + * \param id The index in the list of well-known domain parameters. * - * \note Index should be a value of RFC 4492's enum NamedCurve, - * usually in the form of a MBEDTLS_ECP_DP_XXX macro. + * \return \c 0 on success, + * \return An \c MBEDTLS_ERR_MPI_XXX error code if initialization fails. + * \return #MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE for unkownn groups. + */ int mbedtls_ecp_group_load( mbedtls_ecp_group *grp, mbedtls_ecp_group_id id ); /** - * \brief Set a group from a TLS ECParameters record + * \brief This function sets a group from a TLS ECParameters record. * - * \param grp Destination group - * \param buf &(Start of input buffer) - * \param len Buffer length + * \note \p buf is updated to point right after ECParameters on exit. * - * \note buf is updated to point right after ECParameters on exit + * \param grp The destination group. + * \param buf The address of the pointer to the start of input buffer. + * \param len The length of the buffer. * - * \return 0 if successful, - * MBEDTLS_ERR_MPI_XXX if initialization failed - * MBEDTLS_ERR_ECP_BAD_INPUT_DATA if input is invalid + * \return \c 0 on success. + * \return An \c MBEDTLS_ERR_MPI_XXX error code if initialization fails. + * \return #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if input is invalid. */ int mbedtls_ecp_tls_read_group( mbedtls_ecp_group *grp, const unsigned char **buf, size_t len ); /** - * \brief Write the TLS ECParameters record for a group + * \brief This function writes the TLS ECParameters record for a group. * - * \param grp ECP group used - * \param olen Number of bytes actually written - * \param buf Buffer to write to - * \param blen Buffer length + * \param grp The ECP group used. + * \param olen The number of Bytes written. + * \param buf The buffer to write to. + * \param blen The length of the buffer. * - * \return 0 if successful, - * or MBEDTLS_ERR_ECP_BUFFER_TOO_SMALL + * \return \c 0 on success. + * \return #MBEDTLS_ERR_ECP_BUFFER_TOO_SMALL on failure. */ int mbedtls_ecp_tls_write_group( const mbedtls_ecp_group *grp, size_t *olen, unsigned char *buf, size_t blen ); /** - * \brief Multiplication by an integer: R = m * P - * (Not thread-safe to use same group in multiple threads) + * \brief This function performs multiplication of a point by + * an integer: \p R = \p m * \p P. * - * \note In order to prevent timing attacks, this function - * executes the exact same sequence of (base field) - * operations for any valid m. It avoids any if-branch or - * array index depending on the value of m. + * It is not thread-safe to use same group in multiple threads. * - * \note If f_rng is not NULL, it is used to randomize intermediate - * results in order to prevent potential timing attacks - * targeting these results. It is recommended to always - * provide a non-NULL f_rng (the overhead is negligible). + * \note To prevent timing attacks, this function + * executes the exact same sequence of base-field + * operations for any valid \p m. It avoids any if-branch or + * array index depending on the value of \p m. * - * \param grp ECP group - * \param R Destination point - * \param m Integer by which to multiply - * \param P Point to multiply - * \param f_rng RNG function (see notes) - * \param p_rng RNG parameter + * \note If \p f_rng is not NULL, it is used to randomize + * intermediate results to prevent potential timing attacks + * targeting these results. We recommend always providing + * a non-NULL \p f_rng. The overhead is negligible. * - * \return 0 if successful, - * MBEDTLS_ERR_ECP_INVALID_KEY if m is not a valid privkey - * or P is not a valid pubkey, - * MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed + * \param grp The ECP group. + * \param R The destination point. + * \param m The integer by which to multiply. + * \param P The point to multiply. + * \param f_rng The RNG function. + * \param p_rng The RNG context. + * + * \return \c 0 on success. + * \return #MBEDTLS_ERR_ECP_INVALID_KEY if \p m is not a valid privkey, + * or \p P is not a valid pubkey. + * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory allocation failure. */ int mbedtls_ecp_mul( mbedtls_ecp_group *grp, mbedtls_ecp_point *R, const mbedtls_mpi *m, const mbedtls_ecp_point *P, int (*f_rng)(void *, unsigned char *, size_t), void *p_rng ); /** - * \brief Multiplication and addition of two points by integers: - * R = m * P + n * Q - * (Not thread-safe to use same group in multiple threads) + * \brief This function performs multiplication and addition of two + * points by integers: \p R = \p m * \p P + \p n * \p Q + + * It is not thread-safe to use same group in multiple threads. * - * \note In contrast to mbedtls_ecp_mul(), this function does not guarantee - * a constant execution flow and timing. + * \note In contrast to mbedtls_ecp_mul(), this function does not + * guarantee a constant execution flow and timing. * - * \param grp ECP group - * \param R Destination point - * \param m Integer by which to multiply P - * \param P Point to multiply by m - * \param n Integer by which to multiply Q - * \param Q Point to be multiplied by n + * \param grp The ECP group. + * \param R The destination point. + * \param m The integer by which to multiply \p P. + * \param P The point to multiply by \p m. + * \param n The integer by which to multiply \p Q. + * \param Q The point to be multiplied by \p n. * - * \return 0 if successful, - * MBEDTLS_ERR_ECP_INVALID_KEY if m or n is not a valid privkey - * or P or Q is not a valid pubkey, - * MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed + * \return \c 0 on success. + * \return #MBEDTLS_ERR_ECP_INVALID_KEY if \p m or \p n are not + * valid private keys, or \p P or \p Q are not valid public + * keys. + * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory allocation failure. */ int mbedtls_ecp_muladd( mbedtls_ecp_group *grp, mbedtls_ecp_point *R, const mbedtls_mpi *m, const mbedtls_ecp_point *P, const mbedtls_mpi *n, const mbedtls_ecp_point *Q ); /** - * \brief Check that a point is a valid public key on this curve + * \brief This function checks that a point is a valid public key + * on this curve. * - * \param grp Curve/group the point should belong to - * \param pt Point to check + * It only checks that the point is non-zero, has + * valid coordinates and lies on the curve. It does not verify + * that it is indeed a multiple of \p G. This additional + * check is computationally more expensive, is not required + * by standards, and should not be necessary if the group + * used has a small cofactor. In particular, it is useless for + * the NIST groups which all have a cofactor of 1. * - * \return 0 if point is a valid public key, - * MBEDTLS_ERR_ECP_INVALID_KEY otherwise. + * \note This function uses bare components rather than an + * mbedtls_ecp_keypair() structure, to ease use with other + * structures. For example, mbedtls_ecdh_context() or + * mbedtls_ecdsa_context(). * - * \note This function only checks the point is non-zero, has valid - * coordinates and lies on the curve, but not that it is - * indeed a multiple of G. This is additional check is more - * expensive, isn't required by standards, and shouldn't be - * necessary if the group used has a small cofactor. In - * particular, it is useless for the NIST groups which all - * have a cofactor of 1. + * \param grp The curve or group the point should belong to. + * \param pt The point to check. * - * \note Uses bare components rather than an mbedtls_ecp_keypair structure - * in order to ease use with other structures such as - * mbedtls_ecdh_context of mbedtls_ecdsa_context. + * \return \c 0 if the point is a valid public key. + * \return #MBEDTLS_ERR_ECP_INVALID_KEY otherwise. */ int mbedtls_ecp_check_pubkey( const mbedtls_ecp_group *grp, const mbedtls_ecp_point *pt ); /** - * \brief Check that an mbedtls_mpi is a valid private key for this curve + * \brief This function checks that an \p mbedtls_mpi is a valid private + * key for this curve. * - * \param grp Group used - * \param d Integer to check + * \note This function uses bare components rather than an + * mbedtls_ecp_keypair() structure to ease use with other + * structures such as mbedtls_ecdh_context() or + * mbedtls_ecdsa_context(). * - * \return 0 if point is a valid private key, - * MBEDTLS_ERR_ECP_INVALID_KEY otherwise. + * \param grp The group used. + * \param d The integer to check. * - * \note Uses bare components rather than an mbedtls_ecp_keypair structure - * in order to ease use with other structures such as - * mbedtls_ecdh_context of mbedtls_ecdsa_context. + * \return \c 0 if the point is a valid private key. + * \return #MBEDTLS_ERR_ECP_INVALID_KEY otherwise. */ int mbedtls_ecp_check_privkey( const mbedtls_ecp_group *grp, const mbedtls_mpi *d ); /** - * \brief Generate a keypair with configurable base point + * \brief This function generates a keypair with a configurable base + * point. * - * \param grp ECP group - * \param G Chosen base point - * \param d Destination MPI (secret part) - * \param Q Destination point (public part) - * \param f_rng RNG function - * \param p_rng RNG parameter + * \note This function uses bare components rather than an + * mbedtls_ecp_keypair() structure to ease use with other + * structures such as mbedtls_ecdh_context() or + * mbedtls_ecdsa_context(). +* + * \param grp The ECP group. + * \param G The chosen base point. + * \param d The destination MPI (secret part). + * \param Q The destination point (public part). + * \param f_rng The RNG function. + * \param p_rng The RNG context. * - * \return 0 if successful, - * or a MBEDTLS_ERR_ECP_XXX or MBEDTLS_MPI_XXX error code - * - * \note Uses bare components rather than an mbedtls_ecp_keypair structure - * in order to ease use with other structures such as - * mbedtls_ecdh_context of mbedtls_ecdsa_context. - */ + * \return \c 0 on success. + * \return An \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_MPI_XXX error code + * on failure. + */ int mbedtls_ecp_gen_keypair_base( mbedtls_ecp_group *grp, const mbedtls_ecp_point *G, mbedtls_mpi *d, mbedtls_ecp_point *Q, @@ -620,57 +670,64 @@ int mbedtls_ecp_gen_keypair_base( mbedtls_ecp_group *grp, void *p_rng ); /** - * \brief Generate a keypair + * \brief This function generates a keypair. * - * \param grp ECP group - * \param d Destination MPI (secret part) - * \param Q Destination point (public part) - * \param f_rng RNG function - * \param p_rng RNG parameter + * \note This function uses bare components rather than an + * mbedtls_ecp_keypair() structure to ease use with other + * structures such as mbedtls_ecdh_context() or + * mbedtls_ecdsa_context(). * - * \return 0 if successful, - * or a MBEDTLS_ERR_ECP_XXX or MBEDTLS_MPI_XXX error code + * \param grp The ECP group. + * \param d The destination MPI (secret part). + * \param Q The destination point (public part). + * \param f_rng The RNG function. + * \param p_rng The RNG context. * - * \note Uses bare components rather than an mbedtls_ecp_keypair structure - * in order to ease use with other structures such as - * mbedtls_ecdh_context of mbedtls_ecdsa_context. + * \return \c 0 on success. + * \return An \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_MPI_XXX error code + * on failure. */ int mbedtls_ecp_gen_keypair( mbedtls_ecp_group *grp, mbedtls_mpi *d, mbedtls_ecp_point *Q, int (*f_rng)(void *, unsigned char *, size_t), void *p_rng ); /** - * \brief Generate a keypair + * \brief This function generates a key. * - * \param grp_id ECP group identifier - * \param key Destination keypair - * \param f_rng RNG function - * \param p_rng RNG parameter + * \param grp_id The ECP group identifier. + * \param key The destination key. + * \param f_rng The RNG function. + * \param p_rng The RNG context. * - * \return 0 if successful, - * or a MBEDTLS_ERR_ECP_XXX or MBEDTLS_MPI_XXX error code + * \return \c 0 on success. + * \return An \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_MPI_XXX error code + * on failure. */ int mbedtls_ecp_gen_key( mbedtls_ecp_group_id grp_id, mbedtls_ecp_keypair *key, int (*f_rng)(void *, unsigned char *, size_t), void *p_rng ); /** - * \brief Check a public-private key pair + * \brief This function checks a public-private key pair. * - * \param pub Keypair structure holding a public key - * \param prv Keypair structure holding a private (plus public) key + * \param pub The keypair structure holding the public key. + * \param prv The keypair structure holding the private key. * - * \return 0 if successful (keys are valid and match), or - * MBEDTLS_ERR_ECP_BAD_INPUT_DATA, or - * a MBEDTLS_ERR_ECP_XXX or MBEDTLS_ERR_MPI_XXX code. + * \note The both are keypairs, and may optionally hold the corresponding other key, but the public key passed in thee pub is checked against the private key passed in prv. + * + * \return \c 0 on success - the keys are valid and match. + * \return #MBEDTLS_ERR_ECP_BAD_INPUT_DATA, or an \c + * MBEDTLS_ERR_ECP_XXX or an \c MBEDTLS_ERR_MPI_XXX + * error code on failure. */ int mbedtls_ecp_check_pub_priv( const mbedtls_ecp_keypair *pub, const mbedtls_ecp_keypair *prv ); #if defined(MBEDTLS_SELF_TEST) /** - * \brief Checkup routine + * \brief The ECP checkup routine. * - * \return 0 if successful, or 1 if a test failed + * \return \c 0 on success. + * \return \c 1 on failure. */ int mbedtls_ecp_self_test( int verbose ); From f763f2bbc1c92416d12874fd5f14969279036cb0 Mon Sep 17 00:00:00 2001 From: Rose Zadik Date: Tue, 17 Apr 2018 11:00:40 +0100 Subject: [PATCH 12/30] Update dhm.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". *Suggest to specify issue for each return code, where multiple failure return codes are listed, or generalize. *Minor improvements to parameter documentation proposed by eng. --- include/mbedtls/dhm.h | 108 ++++++++++++++++++++++-------------------- 1 file changed, 57 insertions(+), 51 deletions(-) diff --git a/include/mbedtls/dhm.h b/include/mbedtls/dhm.h index 00fafd8d1..2829ffc07 100644 --- a/include/mbedtls/dhm.h +++ b/include/mbedtls/dhm.h @@ -1,7 +1,12 @@ /** * \file dhm.h * - * \brief Diffie-Hellman-Merkle key exchange. + * \brief This file contains DHM definitions and functions. + * + * Diffie-Hellman-Merkle (DHM) key exchange is defined in + * RFC-2631: Diffie-Hellman Key Agreement Method and + * Public-Key Cryptography Standards (PKCS) #3: Diffie + * Hellman Key Agreement Standard. * * RFC-3526: More Modular Exponential (MODP) Diffie-Hellman groups for * Internet Key Exchange (IKE) defines a number of standardized @@ -125,8 +130,8 @@ void mbedtls_dhm_init( mbedtls_dhm_context *ctx ); * failures. * \param end The end of the input buffer. * - * \return \c 0 on success, or an \c MBEDTLS_ERR_DHM_XXX error code - * on failure. + * \return \c 0 on success. + * \return An \c MBEDTLS_ERR_DHM_XXX error code on failure. */ int mbedtls_dhm_read_params( mbedtls_dhm_context *ctx, unsigned char **p, @@ -136,13 +141,6 @@ int mbedtls_dhm_read_params( mbedtls_dhm_context *ctx, * \brief This function sets up and writes the ServerKeyExchange * parameters. * - * \param ctx The DHM context. - * \param x_size The private value size in Bytes. - * \param olen The number of characters written. - * \param output The destination buffer. - * \param f_rng The RNG function. - * \param p_rng The RNG parameter. - * * \note The destination buffer must be large enough to hold * the reduced binary presentation of the modulus, the generator * and the public key, each wrapped with a 2-byte length field. @@ -155,8 +153,15 @@ int mbedtls_dhm_read_params( mbedtls_dhm_context *ctx, * mbedtls_dhm_set_group() below in conjunction with * mbedtls_mpi_read_binary() and mbedtls_mpi_read_string(). * - * \return \c 0 on success, or an \c MBEDTLS_ERR_DHM_XXX error code - * on failure. + * \param ctx The DHM context. + * \param x_size The private key size in Bytes. + * \param olen The number of characters written. + * \param output The destination buffer. + * \param f_rng The RNG function. + * \param p_rng The RNG context. + * + * \return \c 0 on success. + * \return An \c MBEDTLS_ERR_DHM_XXX error code on failure. */ int mbedtls_dhm_make_params( mbedtls_dhm_context *ctx, int x_size, unsigned char *output, size_t *olen, @@ -164,54 +169,54 @@ int mbedtls_dhm_make_params( mbedtls_dhm_context *ctx, int x_size, void *p_rng ); /** - * \brief Set prime modulus and generator + * \brief This function sets the prime modulus and generator. + * + * \note This function can be used to set \p P, \p G + * in preparation for mbedtls_dhm_make_params(). * * \param ctx The DHM context. - * \param P The MPI holding DHM prime modulus. - * \param G The MPI holding DHM generator. + * \param P The MPI holding the DHM prime modulus. + * \param G The MPI holding the DHM generator. * - * \note This function can be used to set P, G - * in preparation for \c mbedtls_dhm_make_params. - * - * \return \c 0 if successful, or an \c MBEDTLS_ERR_DHM_XXX error code - * on failure. + * \return \c 0 if successful. + * \return An \c MBEDTLS_ERR_DHM_XXX error code on failure. */ int mbedtls_dhm_set_group( mbedtls_dhm_context *ctx, const mbedtls_mpi *P, const mbedtls_mpi *G ); /** - * \brief This function imports the public value G^Y of the peer. + * \brief This function imports the G^Y public value of the peer. * * \param ctx The DHM context. - * \param input The input buffer. + * \param input The input buffer containing the G^Y value of the peer. * \param ilen The size of the input buffer. * - * \return \c 0 on success, or an \c MBEDTLS_ERR_DHM_XXX error code - * on failure. + * \return \c 0 on success. + * \return An \c MBEDTLS_ERR_DHM_XXX error code on failure. */ int mbedtls_dhm_read_public( mbedtls_dhm_context *ctx, const unsigned char *input, size_t ilen ); /** - * \brief This function creates its own private value \c X and + * \brief This function creates its own \c X private key and * exports \c G^X. * + * \note The destination buffer is always fully written + * so as to contain a big-endian representation of G^X mod P. + * If it is larger than ctx->len, it is padded accordingly + * with zero-bytes at the beginning. + * * \param ctx The DHM context. - * \param x_size The private value size in Bytes. + * \param x_size The private key size in Bytes. * \param output The destination buffer. * \param olen The length of the destination buffer. Must be at least - equal to ctx->len (the size of \c P). + * equal to ctx->len (the size of \c P). * \param f_rng The RNG function. - * \param p_rng The RNG parameter. + * \param p_rng The RNG context. * - * \note The destination buffer will always be fully written - * so as to contain a big-endian presentation of G^X mod P. - * If it is larger than ctx->len, it will accordingly be - * padded with zero-bytes in the beginning. - * - * \return \c 0 on success, or an \c MBEDTLS_ERR_DHM_XXX error code - * on failure. + * \return \c 0 on success. + * \return An \c MBEDTLS_ERR_DHM_XXX error code on failure. */ int mbedtls_dhm_make_public( mbedtls_dhm_context *ctx, int x_size, unsigned char *output, size_t olen, @@ -222,22 +227,22 @@ int mbedtls_dhm_make_public( mbedtls_dhm_context *ctx, int x_size, * \brief This function derives and exports the shared secret * \c (G^Y)^X mod \c P. * + * \note If \p f_rng is not NULL, it is used to blind the input as + * a countermeasure against timing attacks. Blinding is used + * only if our private key \c X is re-used, and not used + * otherwise. We recommend always passing a non-NULL + * \p f_rng argument. + * * \param ctx The DHM context. * \param output The destination buffer. * \param output_size The size of the destination buffer. Must be at least - * the size of ctx->len. + * the size of ctx->len (the size of \c P). * \param olen On exit, holds the actual number of Bytes written. * \param f_rng The RNG function, for blinding purposes. - * \param p_rng The RNG parameter. + * \param p_rng The RNG context. * - * \return \c 0 on success, or an \c MBEDTLS_ERR_DHM_XXX error code - * on failure. - * - * \note If non-NULL, \p f_rng is used to blind the input as - * a countermeasure against timing attacks. Blinding is used - * only if our secret value \p X is re-used and omitted - * otherwise. Therefore, we recommend always passing a - * non-NULL \p f_rng argument. + * \return \c 0 on success. + * \return An \c MBEDTLS_ERR_DHM_XXX error code on failure. */ int mbedtls_dhm_calc_secret( mbedtls_dhm_context *ctx, unsigned char *output, size_t output_size, size_t *olen, @@ -245,7 +250,7 @@ int mbedtls_dhm_calc_secret( mbedtls_dhm_context *ctx, void *p_rng ); /** - * \brief This function frees and clears the components of a DHM key. + * \brief This function frees and clears the components of a DHM context. * * \param ctx The DHM context to free and clear. */ @@ -261,8 +266,8 @@ void mbedtls_dhm_free( mbedtls_dhm_context *ctx ); * \param dhminlen The size of the buffer, including the terminating null * Byte for PEM data. * - * \return \c 0 on success, or a specific DHM or PEM error code - * on failure. + * \return \c 0 on success. + * \return A specific DHM or PEM error code on failure. */ int mbedtls_dhm_parse_dhm( mbedtls_dhm_context *dhm, const unsigned char *dhmin, size_t dhminlen ); @@ -275,8 +280,8 @@ int mbedtls_dhm_parse_dhm( mbedtls_dhm_context *dhm, const unsigned char *dhmin, * \param dhm The DHM context to load the parameters to. * \param path The filename to read the DHM parameters from. * - * \return \c 0 on success, or a specific DHM or PEM error code - * on failure. + * \return \c 0 on success. + * \return A specific DHM or PEM error code on failure. */ int mbedtls_dhm_parse_dhmfile( mbedtls_dhm_context *dhm, const char *path ); #endif /* MBEDTLS_FS_IO */ @@ -297,7 +302,8 @@ extern "C" { /** * \brief The DMH checkup routine. * - * \return \c 0 on success, or \c 1 on failure. + * \return \c 0 on success. + * \return \c 1 on failure. */ int mbedtls_dhm_self_test( int verbose ); From ec5d416cb2f09642a867d330e7c6b2934c30616e Mon Sep 17 00:00:00 2001 From: Rose Zadik Date: Tue, 17 Apr 2018 15:55:28 +0100 Subject: [PATCH 13/30] Update ecdsa.h minor fix based on review comments --- include/mbedtls/ecdsa.h | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/include/mbedtls/ecdsa.h b/include/mbedtls/ecdsa.h index 806c417ef..11df7e215 100644 --- a/include/mbedtls/ecdsa.h +++ b/include/mbedtls/ecdsa.h @@ -238,7 +238,8 @@ int mbedtls_ecdsa_write_signature( mbedtls_ecdsa_context *ctx, mbedtls_md_type_t * * \see ecp.h * - * \deprecated Superseded by mbedtls_ecdsa_write_signature() in 2.0.0 + * \deprecated Superseded by mbedtls_ecdsa_write_signature() in + * Mbed TLS version 2.0 and later. * * \param ctx The ECDSA context. * \param hash The message hash. From 477dce15bca9e4a20f9e06d4ad71a9a45fa6974f Mon Sep 17 00:00:00 2001 From: Rose Zadik Date: Tue, 17 Apr 2018 16:31:22 +0100 Subject: [PATCH 14/30] Update ccm.h updated brief desc. --- include/mbedtls/ccm.h | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/include/mbedtls/ccm.h b/include/mbedtls/ccm.h index 8f252c4bd..40ee1b3c8 100644 --- a/include/mbedtls/ccm.h +++ b/include/mbedtls/ccm.h @@ -1,7 +1,8 @@ /** * \file ccm.h * - * \brief This file contains CCM definitions and functions. + * \brief This file provides an API for the CCM authenticated encryption + * mode for block ciphers. * * CCM combines Counter mode encryption with CBC-MAC authentication * for 128-bit block ciphers. From 379b95ca9b5ca518dcff2b9f0a69702a49c01269 Mon Sep 17 00:00:00 2001 From: Rose Zadik Date: Tue, 17 Apr 2018 16:43:00 +0100 Subject: [PATCH 15/30] Update ccm.h Updated return values for mbedtls_ccm_auth_decrypt(). --- include/mbedtls/ccm.h | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/include/mbedtls/ccm.h b/include/mbedtls/ccm.h index 40ee1b3c8..5a34f3a0a 100644 --- a/include/mbedtls/ccm.h +++ b/include/mbedtls/ccm.h @@ -145,8 +145,9 @@ int mbedtls_ccm_encrypt_and_tag( mbedtls_ccm_context *ctx, size_t length, * \param tag_len The length of the tag in Bytes. * 4, 6, 8, 10, 12, 14 or 16. * - * \return \c 0 on success. - * \return A CCM or cipher-specific error code on failure. + * \return \c 0 on success. This indicates that the message is authentic. + * \return #MBEDTLS_ERR_CCM_AUTH_FAILED if the tag does not match. + * \return A cipher-specific error code on calculation failure. */ int mbedtls_ccm_auth_decrypt( mbedtls_ccm_context *ctx, size_t length, const unsigned char *iv, size_t iv_len, From ee96359d8916617c9f2766f2e7c8e6c7bf473274 Mon Sep 17 00:00:00 2001 From: Rose Zadik Date: Wed, 18 Apr 2018 09:46:12 +0100 Subject: [PATCH 16/30] Update dhm.h Changes based on review comments --- include/mbedtls/dhm.h | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/include/mbedtls/dhm.h b/include/mbedtls/dhm.h index 2829ffc07..348d8cfec 100644 --- a/include/mbedtls/dhm.h +++ b/include/mbedtls/dhm.h @@ -1,7 +1,8 @@ /** * \file dhm.h * - * \brief This file contains DHM definitions and functions. + * \brief This file contains Diffie-Hellman-Merkle (DHM) key exchange + * definitions and functions. * * Diffie-Hellman-Merkle (DHM) key exchange is defined in * RFC-2631: Diffie-Hellman Key Agreement Method and @@ -186,7 +187,7 @@ int mbedtls_dhm_set_group( mbedtls_dhm_context *ctx, const mbedtls_mpi *G ); /** - * \brief This function imports the G^Y public value of the peer. + * \brief This function imports the public value of the peer, G^Y. * * \param ctx The DHM context. * \param input The input buffer containing the G^Y value of the peer. @@ -199,7 +200,7 @@ int mbedtls_dhm_read_public( mbedtls_dhm_context *ctx, const unsigned char *input, size_t ilen ); /** - * \brief This function creates its own \c X private key and + * \brief This function creates its own private key, \c X, and * exports \c G^X. * * \note The destination buffer is always fully written @@ -267,7 +268,8 @@ void mbedtls_dhm_free( mbedtls_dhm_context *ctx ); * Byte for PEM data. * * \return \c 0 on success. - * \return A specific DHM or PEM error code on failure. + * \return An \c MBEDTLS_ERR_DHM_XXX or MBEDTLS_ERR_PEM_XXX error code + * error code on failure. */ int mbedtls_dhm_parse_dhm( mbedtls_dhm_context *dhm, const unsigned char *dhmin, size_t dhminlen ); @@ -281,7 +283,8 @@ int mbedtls_dhm_parse_dhm( mbedtls_dhm_context *dhm, const unsigned char *dhmin, * \param path The filename to read the DHM parameters from. * * \return \c 0 on success. - * \return A specific DHM or PEM error code on failure. + * \return An \c MBEDTLS_ERR_DHM_XXX or MBEDTLS_ERR_PEM_XXX error code + * error code on failure. */ int mbedtls_dhm_parse_dhmfile( mbedtls_dhm_context *dhm, const char *path ); #endif /* MBEDTLS_FS_IO */ From fa1fe36e08a45902f40d53c81e9d9532a777e2d9 Mon Sep 17 00:00:00 2001 From: Rose Zadik Date: Wed, 18 Apr 2018 10:09:31 +0100 Subject: [PATCH 17/30] Update dhm.h Minor fix based on review comments --- include/mbedtls/dhm.h | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/include/mbedtls/dhm.h b/include/mbedtls/dhm.h index 348d8cfec..b3b376172 100644 --- a/include/mbedtls/dhm.h +++ b/include/mbedtls/dhm.h @@ -268,7 +268,7 @@ void mbedtls_dhm_free( mbedtls_dhm_context *ctx ); * Byte for PEM data. * * \return \c 0 on success. - * \return An \c MBEDTLS_ERR_DHM_XXX or MBEDTLS_ERR_PEM_XXX error code + * \return An \c MBEDTLS_ERR_DHM_XXX or \c MBEDTLS_ERR_PEM_XXX error code * error code on failure. */ int mbedtls_dhm_parse_dhm( mbedtls_dhm_context *dhm, const unsigned char *dhmin, @@ -283,7 +283,7 @@ int mbedtls_dhm_parse_dhm( mbedtls_dhm_context *dhm, const unsigned char *dhmin, * \param path The filename to read the DHM parameters from. * * \return \c 0 on success. - * \return An \c MBEDTLS_ERR_DHM_XXX or MBEDTLS_ERR_PEM_XXX error code + * \return An \c MBEDTLS_ERR_DHM_XXX or \c MBEDTLS_ERR_PEM_XXX error code * error code on failure. */ int mbedtls_dhm_parse_dhmfile( mbedtls_dhm_context *dhm, const char *path ); From f56cb34d609b9c697238c3a8f2c2096ec0b42be6 Mon Sep 17 00:00:00 2001 From: Rose Zadik Date: Thu, 19 Apr 2018 12:49:10 +0100 Subject: [PATCH 18/30] Update ecp.h Updated based on review comment. One comment remains open (waiting for input) --- include/mbedtls/ecp.h | 151 +++++++++++++++++++++++------------------- 1 file changed, 84 insertions(+), 67 deletions(-) diff --git a/include/mbedtls/ecp.h b/include/mbedtls/ecp.h index 89c756b37..c58a4b6ab 100644 --- a/include/mbedtls/ecp.h +++ b/include/mbedtls/ecp.h @@ -3,8 +3,9 @@ * * \brief This file contains ECP definitions and functions. * - * The Elliptic Curve over P (ECP) is defined in Standards for Efficient - * Cryptography Group (SECG): SEC1 Elliptic Curve Cryptography and + * The use of Elliptic Curves over GF(P) (ECP) in cryptography and + * TLS is defined in Standards for Efficient Cryptography Group + * (SECG): SEC1 Elliptic Curve Cryptography and * RFC-4492: Elliptic Curve Cryptography (ECC) Cipher Suites * for Transport Layer Security (TLS). * @@ -69,7 +70,7 @@ extern "C" { * \note Only curves over prime fields are supported. * * \warning This library does not support validation of arbitrary domain - * parameters. Therefore, only well-known domain parameters from trusted + * parameters. Therefore, only standardized domain parameters from trusted * sources should be used. See mbedtls_ecp_group_load(). */ typedef enum @@ -84,14 +85,14 @@ typedef enum MBEDTLS_ECP_DP_BP384R1, /*!< Domain parameters for 384-bit Brainpool curve. */ MBEDTLS_ECP_DP_BP512R1, /*!< Domain parameters for 512-bit Brainpool curve. */ MBEDTLS_ECP_DP_CURVE25519, /*!< Domain parameters for a Curve25519 curve. */ - MBEDTLS_ECP_DP_CURVE448, /*!< Domain parameters for a Curve448 curve. */ + MBEDTLS_ECP_DP_CURVE448, /*!< Domain parameters for a Curve448 curve. */ MBEDTLS_ECP_DP_SECP192K1, /*!< Domain parameters for 192-bit "Koblitz" curve. */ MBEDTLS_ECP_DP_SECP224K1, /*!< Domain parameters for 224-bit "Koblitz" curve. */ MBEDTLS_ECP_DP_SECP256K1, /*!< Domain parameters for 256-bit "Koblitz" curve. */ } mbedtls_ecp_group_id; /** - * The number of supported curves, plus one for none. + * The number of supported curves, plus one for #MBEDTLS_ECP_DP_NONE. * * \note Montgomery curves are currently excluded. */ @@ -109,13 +110,15 @@ typedef struct } mbedtls_ecp_curve_info; /** - * \brief The ECP point structure, in jacobian coordinates. + * \brief The ECP point structure, in Jacobian coordinates. * * \note All functions expect and return points satisfying - * the following condition: \p Z == 0 or \p Z == 1. Other - * values of \p Z are used only by internal functions. - * The point is zero, or "at infinity", if Z == 0. - * Otherwise, X and Y are its standard (affine) coordinates. + * the following condition: Z == 0 or + * Z == 1. Other values of \p Z are + * used only by internal functions. + * The point is zero, or "at infinity", if Z == 0. + * Otherwise, \p X and \p Y are its standard (affine) + * coordinates. */ typedef struct { @@ -129,43 +132,46 @@ mbedtls_ecp_point; * \brief The ECP group structure. * * We consider two types of curve equations: - *
  • Short Weierstrass: y^2 = x^3 + \p A x + \p B mod P + *
    1. Short Weierstrass: y^2 = x^3 + A x + B mod P * (SEC1 + RFC-4492)
      2. - *
    2. Montgomery: y^2 = x^3 + A x^2 + x mod P (Curve25519 + draft)
- * In both cases, the generator (G) for a prime-order subgroup is fixed. + *
  • Montgomery: y^2 = x^3 + A x^2 + x mod P (Curve25519, + * Curve448)
    • + * In both cases, the generator (\p G) for a prime-order subgroup is fixed. * * For Short Weierstrass, this subgroup is the whole curve, and its - * cardinal is denoted by \p N. Our code requires that \p N is an odd prime. + * cardinality is denoted by \p N. Our code requires that \p N is an + * odd prime. * - * \note For blinding, use odd in mbedtls_ecp_mul() and prime in - * mbedtls_ecdsa_sign(). - * - * For Montgomery curves, we do not store \p A, but (A + 2) / 4, which is - * the quantity used in the formulas. Additionally, \p nbits is not the - * size of \p N but the required size for private keys. + * For Montgomery curves, we do not store \p A, but (A + 2) / 4, + * which is the quantity used in the formulas. Additionally, \p nbits is + * not the size of \p N but the required size for private keys. * * If \p modp is NULL, reduction modulo \p P is done using a generic algorithm. - * Otherwise, it must point to a function that takes an \p mbedtls_mpi in the - * range of 0..2^(2*pbits)-1, and transforms it in-place in an integer of - * little more than \p pbits, so that the integer may be efficiently brought - * in the 0..P-1 range by a few additions or substractions. + * Otherwise, \p modp must point to a function that takes an \p mbedtls_mpi in the + * range of 0..2^(2*pbits)-1, and transforms it in-place to an integer which is + * congruent mod \p P to the given MPI, and is close enough to \p pbits in size, + * so that it may be efficiently brought in the 0..P-1 range by a few additions + * or subtractions. Therefore, it is only an approximative modular reduction. * * \return \c 0 on success - * \return Non-zero on failure. + * \return Non-zero error code on failure. */ typedef struct { mbedtls_ecp_group_id id; /*!< An internal group identifier. */ - mbedtls_mpi P; /*!< A prime modulus of the base field. */ - mbedtls_mpi A; /*!< \p A in the equation or (A + 2) / 4. */ - mbedtls_mpi B; /*!< \p B in the equation or unused. */ - mbedtls_ecp_point G; /*!< The generator of the (sub)group used. */ + mbedtls_mpi P; /*!< The prime modulus of the base field. */ + mbedtls_mpi A; /*!< For (1) \p A in the equation or for + (2) (A + 2) / 4. */ + mbedtls_mpi B; /*!< For (1) \p B in the equation or + for (2) Unused. */ + mbedtls_ecp_point G; /*!< The generator of the subgroup used. */ mbedtls_mpi N; /*!< The order of \p G. */ size_t pbits; /*!< The number of bits in \p P.*/ - size_t nbits; /*!< The number of bits in \p P, or the private - keys. */ + size_t nbits; /*!< For (1) The number of bits in \p P, or + for (2) the private keys. */ unsigned int h; /*!< \internal 1 if the constants are static. */ - int (*modp)(mbedtls_mpi *); /*!< The function for fast reduction mod P.*/ + int (*modp)(mbedtls_mpi *); /*!< The function for fast pseudo-reduction + mod \p P (see above).*/ int (*t_pre)(mbedtls_ecp_point *, void *); /*!< Unused. */ int (*t_post)(mbedtls_ecp_point *, void *); /*!< Unused. */ void *t_data; /*!< Unused. */ @@ -200,7 +206,7 @@ mbedtls_ecp_keypair; #if !defined(MBEDTLS_ECP_MAX_BITS) /** - * The maximum size of the groups, that is, of N and P. + * The maximum size of the groups, that is, of \c N and \c P. */ #define MBEDTLS_ECP_MAX_BITS 521 /**< The maximum size of groups, in bits. */ #endif @@ -262,7 +268,7 @@ mbedtls_ecp_keypair; /** * \brief This function retrieves the information defined in - * mbedtls_ecp_curve_info()for all supported curves in order + * mbedtls_ecp_curve_info() for all supported curves in order * of preference. * * \return A statically allocated array. The last entry is 0. @@ -270,8 +276,9 @@ mbedtls_ecp_keypair; const mbedtls_ecp_curve_info *mbedtls_ecp_curve_list( void ); /** - * \brief This function retrieves the grp_id of all supported curves - * in order of preference. + * \brief This function retrieves the list of internal group + * identifiers of all supported curves in the order of + * preference. * * \return A statically allocated array, * terminated with MBEDTLS_ECP_DP_NONE. @@ -284,7 +291,8 @@ const mbedtls_ecp_group_id *mbedtls_ecp_grp_id_list( void ); * * \param grp_id An \c MBEDTLS_ECP_DP_XXX value. * - * \return The associated curve information, or NULL. + * \return The associated curve information on success. + * \return NULL on failure. */ const mbedtls_ecp_curve_info *mbedtls_ecp_curve_info_from_grp_id( mbedtls_ecp_group_id grp_id ); @@ -294,7 +302,8 @@ const mbedtls_ecp_curve_info *mbedtls_ecp_curve_info_from_grp_id( mbedtls_ecp_gr * * \param tls_id An \c MBEDTLS_ECP_DP_XXX value. * - * \return The associated curve information, or NULL. + * \return The associated curve information on success. + * \return NULL on failure. */ const mbedtls_ecp_curve_info *mbedtls_ecp_curve_info_from_tls_id( uint16_t tls_id ); @@ -304,7 +313,8 @@ const mbedtls_ecp_curve_info *mbedtls_ecp_curve_info_from_tls_id( uint16_t tls_i * * \param name The human-readable name. * - * \return The associated curve information, or NULL. + * \return The associated curve information on success. + * \return NULL on failure. */ const mbedtls_ecp_curve_info *mbedtls_ecp_curve_info_from_name( const char *name ); @@ -316,7 +326,13 @@ const mbedtls_ecp_curve_info *mbedtls_ecp_curve_info_from_name( const char *name void mbedtls_ecp_point_init( mbedtls_ecp_point *pt ); /** - * \brief This function initializes a group to something meaningless. + * \brief This function initializes an ECP group context + * without loading any domain parameters. + * + * \note After this function is called, domain parameters + * for various ECP groups can be loaded through the + * mbedtls_ecp_load() or mbedtls_ecp_tls_read_group() + * functions. */ void mbedtls_ecp_group_init( mbedtls_ecp_group *grp ); @@ -354,7 +370,7 @@ void mbedtls_ecp_keypair_free( mbedtls_ecp_keypair *key ); * \param Q The source point. * * \return \c 0 on success. - * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation fails. + * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory-allocation failure. */ int mbedtls_ecp_copy( mbedtls_ecp_point *P, const mbedtls_ecp_point *Q ); @@ -366,7 +382,7 @@ int mbedtls_ecp_copy( mbedtls_ecp_point *P, const mbedtls_ecp_point *Q ); * \param src The source group. * * \return \c 0 on success. - * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation fails. + * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory-allocation failure. */ int mbedtls_ecp_group_copy( mbedtls_ecp_group *dst, const mbedtls_ecp_group *src ); @@ -376,7 +392,7 @@ int mbedtls_ecp_group_copy( mbedtls_ecp_group *dst, const mbedtls_ecp_group *src * \param pt The point to set. * * \return \c 0 on success. - * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation fails. + * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory-allocation failure. */ int mbedtls_ecp_set_zero( mbedtls_ecp_point *pt ); @@ -385,8 +401,8 @@ int mbedtls_ecp_set_zero( mbedtls_ecp_point *pt ); * * \param pt The point to test. * - * \return \c 1 if point is zero. - * \return \c 0 if point is non-zero. + * \return \c 1 if the point is zero. + * \return \c 0 if the point is non-zero. */ int mbedtls_ecp_is_zero( mbedtls_ecp_point *pt ); @@ -452,7 +468,7 @@ int mbedtls_ecp_point_write_binary( const mbedtls_ecp_group *grp, const mbedtls_ * * \return \c 0 on success. * \return #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if input is invalid. - * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed. + * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory-allocation failure. * \return #MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE if the point format * is not implemented. * @@ -464,15 +480,15 @@ int mbedtls_ecp_point_read_binary( const mbedtls_ecp_group *grp, mbedtls_ecp_poi * \brief This function imports a point from a TLS ECPoint record. * * \note On function return, \p buf is updated to point to immediately - * after the ECPoint. + * after the ECPoint record. * * \param grp The ECP group used. * \param pt The destination point. - * \param buf The address of the pointer to the start of input buffer. + * \param buf The address of the pointer to the start of the input buffer. * \param len The length of the buffer. * * \return \c 0 on success. - * \return An \c MBEDTLS_ERR_MPI_XXX error code if initialization failed. + * \return An \c MBEDTLS_ERR_MPI_XXX error code on initialization failure. * \return #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if input is invalid. */ int mbedtls_ecp_tls_read_point( const mbedtls_ecp_group *grp, mbedtls_ecp_point *pt, @@ -484,9 +500,9 @@ int mbedtls_ecp_tls_read_point( const mbedtls_ecp_group *grp, mbedtls_ecp_point * \param grp The ECP group used. * \param pt The point to export. * \param format The export format. - * \param olen The length of data written. - * \param buf The Buffer to write to. - * \param blen The length of the Buffer. + * \param olen The length of the data written. + * \param buf The buffer to write to. + * \param blen The length of the buffer. * * \return \c 0 on success. * \return #MBEDTLS_ERR_ECP_BAD_INPUT_DATA or @@ -497,7 +513,7 @@ int mbedtls_ecp_tls_write_point( const mbedtls_ecp_group *grp, const mbedtls_ecp unsigned char *buf, size_t blen ); /** - * \brief This function sets a group using well-known domain parameters. + * \brief This function sets a group using standardized domain parameters. * * \note The index should be a value of the NamedCurve enum, * as defined in RFC-4492: Elliptic Curve Cryptography @@ -505,10 +521,10 @@ int mbedtls_ecp_tls_write_point( const mbedtls_ecp_group *grp, const mbedtls_ecp * usually in the form of an \c MBEDTLS_ECP_DP_XXX macro. * * \param grp The destination group. - * \param id The index in the list of well-known domain parameters. + * \param id The identifier of the domain parameter set to load. * * \return \c 0 on success, - * \return An \c MBEDTLS_ERR_MPI_XXX error code if initialization fails. + * \return An \c MBEDTLS_ERR_MPI_XXX error code on initialization failure. * \return #MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE for unkownn groups. */ @@ -517,14 +533,15 @@ int mbedtls_ecp_group_load( mbedtls_ecp_group *grp, mbedtls_ecp_group_id id ); /** * \brief This function sets a group from a TLS ECParameters record. * - * \note \p buf is updated to point right after ECParameters on exit. + * \note \p buf is updated to point right after the ECParameters record + * on exit. * * \param grp The destination group. - * \param buf The address of the pointer to the start of input buffer. + * \param buf The address of the pointer to the start of the input buffer. * \param len The length of the buffer. * * \return \c 0 on success. - * \return An \c MBEDTLS_ERR_MPI_XXX error code if initialization fails. + * \return An \c MBEDTLS_ERR_MPI_XXX error code on initialization failure. * \return #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if input is invalid. */ int mbedtls_ecp_tls_read_group( mbedtls_ecp_group *grp, const unsigned char **buf, size_t len ); @@ -567,9 +584,9 @@ int mbedtls_ecp_tls_write_group( const mbedtls_ecp_group *grp, size_t *olen, * \param p_rng The RNG context. * * \return \c 0 on success. - * \return #MBEDTLS_ERR_ECP_INVALID_KEY if \p m is not a valid privkey, - * or \p P is not a valid pubkey. - * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory allocation failure. + * \return #MBEDTLS_ERR_ECP_INVALID_KEY if \p m is not a valid private + * key, or \p P is not a valid public key. + * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory-allocation failure. */ int mbedtls_ecp_mul( mbedtls_ecp_group *grp, mbedtls_ecp_point *R, const mbedtls_mpi *m, const mbedtls_ecp_point *P, @@ -595,7 +612,7 @@ int mbedtls_ecp_mul( mbedtls_ecp_group *grp, mbedtls_ecp_point *R, * \return #MBEDTLS_ERR_ECP_INVALID_KEY if \p m or \p n are not * valid private keys, or \p P or \p Q are not valid public * keys. - * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory allocation failure. + * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory-allocation failure. */ int mbedtls_ecp_muladd( mbedtls_ecp_group *grp, mbedtls_ecp_point *R, const mbedtls_mpi *m, const mbedtls_ecp_point *P, @@ -618,11 +635,11 @@ int mbedtls_ecp_muladd( mbedtls_ecp_group *grp, mbedtls_ecp_point *R, * structures. For example, mbedtls_ecdh_context() or * mbedtls_ecdsa_context(). * - * \param grp The curve or group the point should belong to. + * \param grp The curve the point should lie on. * \param pt The point to check. * * \return \c 0 if the point is a valid public key. - * \return #MBEDTLS_ERR_ECP_INVALID_KEY otherwise. + * \return #MBEDTLS_ERR_ECP_INVALID_KEY on failure. */ int mbedtls_ecp_check_pubkey( const mbedtls_ecp_group *grp, const mbedtls_ecp_point *pt ); @@ -639,7 +656,7 @@ int mbedtls_ecp_check_pubkey( const mbedtls_ecp_group *grp, const mbedtls_ecp_po * \param d The integer to check. * * \return \c 0 if the point is a valid private key. - * \return #MBEDTLS_ERR_ECP_INVALID_KEY otherwise. + * \return #MBEDTLS_ERR_ECP_INVALID_KEY on failure. */ int mbedtls_ecp_check_privkey( const mbedtls_ecp_group *grp, const mbedtls_mpi *d ); @@ -670,7 +687,7 @@ int mbedtls_ecp_gen_keypair_base( mbedtls_ecp_group *grp, void *p_rng ); /** - * \brief This function generates a keypair. + * \brief This function generates an ECP keypair. * * \note This function uses bare components rather than an * mbedtls_ecp_keypair() structure to ease use with other @@ -692,7 +709,7 @@ int mbedtls_ecp_gen_keypair( mbedtls_ecp_group *grp, mbedtls_mpi *d, mbedtls_ecp void *p_rng ); /** - * \brief This function generates a key. + * \brief This function generates an ECP key. * * \param grp_id The ECP group identifier. * \param key The destination key. From 826f26492008095bfe919784d4c6ae867240f3c8 Mon Sep 17 00:00:00 2001 From: Rose Zadik Date: Thu, 19 Apr 2018 14:01:29 +0100 Subject: [PATCH 19/30] Update cipher.h Additional changes based on review comments --- include/mbedtls/cipher.h | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) diff --git a/include/mbedtls/cipher.h b/include/mbedtls/cipher.h index 3ecae9b06..416942846 100644 --- a/include/mbedtls/cipher.h +++ b/include/mbedtls/cipher.h @@ -1,7 +1,9 @@ /** * \file cipher.h * - * \brief This file contains the generic cipher wrapper. + * \brief This file contains an abstraction interface for use with the cipher + * primitives provided by the library. It provides a common interface to all of + * the available cipher operations. * * \author Adriaan de Jong */ @@ -71,7 +73,7 @@ extern "C" { /** * \brief Supported cipher types. * - * \warning ARC4 and DES are considered weak ciphers and their use + * \warning RC4 and DES are considered weak ciphers and their use * constitutes a security risk. Arm recommends considering stronger * ciphers instead. */ @@ -80,16 +82,16 @@ typedef enum { MBEDTLS_CIPHER_ID_NULL, /**< NULL.*/ MBEDTLS_CIPHER_ID_AES, /**< The AES cipher. */ MBEDTLS_CIPHER_ID_DES, /**< The DES cipher. */ - MBEDTLS_CIPHER_ID_3DES, /**< The 3DES cipher. */ + MBEDTLS_CIPHER_ID_3DES, /**< The Trile DES cipher. */ MBEDTLS_CIPHER_ID_CAMELLIA, /**< The Camellia cipher. */ MBEDTLS_CIPHER_ID_BLOWFISH, /**< The Blowfish cipher. */ - MBEDTLS_CIPHER_ID_ARC4, /**< The ARC4 cipher. */ + MBEDTLS_CIPHER_ID_ARC4, /**< The RC4 cipher. */ } mbedtls_cipher_id_t; /** * \brief Supported {cipher type, cipher mode} pairs. * - * \warning ARC4 and DES are considered weak ciphers and their use + * \warning RC4 and DES are considered weak ciphers and their use * constitutes a security risk. Arm recommends considering stronger * ciphers instead. */ @@ -136,7 +138,7 @@ typedef enum { MBEDTLS_CIPHER_BLOWFISH_CBC, /**< Blowfish cipher with CBC mode. */ MBEDTLS_CIPHER_BLOWFISH_CFB64, /**< Blowfish cipher with CFB64 mode. */ MBEDTLS_CIPHER_BLOWFISH_CTR, /**< Blowfish cipher with CTR mode. */ - MBEDTLS_CIPHER_ARC4_128, /**< ARC4 cipher with 128-bit mode. */ + MBEDTLS_CIPHER_ARC4_128, /**< RC4 cipher with 128-bit mode. */ MBEDTLS_CIPHER_AES_128_CCM, /**< AES cipher with 128-bit CCM mode. */ MBEDTLS_CIPHER_AES_192_CCM, /**< AES cipher with 192-bit CCM mode. */ MBEDTLS_CIPHER_AES_256_CCM, /**< AES cipher with 256-bit CCM mode. */ @@ -151,7 +153,7 @@ typedef enum { MBEDTLS_MODE_ECB, /**< The ECB cipher mode. */ MBEDTLS_MODE_CBC, /**< The CBC cipher mode. */ MBEDTLS_MODE_CFB, /**< The CFB cipher mode. */ - MBEDTLS_MODE_OFB, /**< Unused. */ + MBEDTLS_MODE_OFB, /**< The OFB cipher mode - unsupported. */ MBEDTLS_MODE_CTR, /**< The CTR cipher mode. */ MBEDTLS_MODE_GCM, /**< The GCM cipher mode. */ MBEDTLS_MODE_STREAM, /**< The stream cipher mode. */ @@ -409,7 +411,7 @@ static inline mbedtls_cipher_mode_t mbedtls_cipher_get_cipher_mode( const mbedtl * \param ctx The context of the cipher. Must be initialized. * * \return The recommended IV size if no IV has been set. - * \return 0 for ciphers not using IV or nonce. + * \return \c 0 for ciphers not using IV or nonce. * \return The actual size if an IV has been set. */ static inline int mbedtls_cipher_get_iv_size( const mbedtls_cipher_context_t *ctx ) From 4c368e82cc5456303d4f0d0b7e5fd25c6a240b1a Mon Sep 17 00:00:00 2001 From: Rose Zadik Date: Thu, 19 Apr 2018 14:24:11 +0100 Subject: [PATCH 20/30] Update cipher.h Additional changes based on review comments --- include/mbedtls/cipher.h | 59 ++++++++++++++++++++++------------------ 1 file changed, 32 insertions(+), 27 deletions(-) diff --git a/include/mbedtls/cipher.h b/include/mbedtls/cipher.h index 416942846..473181762 100644 --- a/include/mbedtls/cipher.h +++ b/include/mbedtls/cipher.h @@ -78,8 +78,8 @@ extern "C" { * ciphers instead. */ typedef enum { - MBEDTLS_CIPHER_ID_NONE = 0, /**< None. */ - MBEDTLS_CIPHER_ID_NULL, /**< NULL.*/ + MBEDTLS_CIPHER_ID_NONE = 0, /**< Placeholder to mark the end of cipher ID lists. */ + MBEDTLS_CIPHER_ID_NULL, /**< The identity cipher, treated as a stream cipher. */ MBEDTLS_CIPHER_ID_AES, /**< The AES cipher. */ MBEDTLS_CIPHER_ID_DES, /**< The DES cipher. */ MBEDTLS_CIPHER_ID_3DES, /**< The Trile DES cipher. */ @@ -96,8 +96,8 @@ typedef enum { * ciphers instead. */ typedef enum { - MBEDTLS_CIPHER_NONE = 0, /**< None. */ - MBEDTLS_CIPHER_NULL, /**< NULL. */ + MBEDTLS_CIPHER_NONE = 0, /**< Placeholder to mark the end of cipher-pair lists. */ + MBEDTLS_CIPHER_NULL, /**< The cipher-pair, treated as a stream cipher. */ MBEDTLS_CIPHER_AES_128_ECB, /**< AES cipher with 128-bit ECB mode. */ MBEDTLS_CIPHER_AES_192_ECB, /**< AES cipher with 192-bit ECB mode. */ MBEDTLS_CIPHER_AES_256_ECB, /**< AES cipher with 256-bit ECB mode. */ @@ -361,9 +361,10 @@ void mbedtls_cipher_free( mbedtls_cipher_context_t *ctx ); * \param cipher_info The cipher to use. * * \return \c 0 on success. - * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA on parameter failure. + * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA on + * parameter-verification failure. * \return #MBEDTLS_ERR_CIPHER_ALLOC_FAILED if allocation of the - * cipher-specific context failed. + * cipher-specific context fails. * * \internal Currently, the function also clears the structure. * In future versions, the caller will be required to call @@ -411,7 +412,7 @@ static inline mbedtls_cipher_mode_t mbedtls_cipher_get_cipher_mode( const mbedtl * \param ctx The context of the cipher. Must be initialized. * * \return The recommended IV size if no IV has been set. - * \return \c 0 for ciphers not using IV or nonce. + * \return \c 0 for ciphers not using an IV or a nonce. * \return The actual size if an IV has been set. */ static inline int mbedtls_cipher_get_iv_size( const mbedtls_cipher_context_t *ctx ) @@ -503,8 +504,8 @@ static inline mbedtls_operation_t mbedtls_cipher_get_operation( const mbedtls_ci * #MBEDTLS_ENCRYPT or #MBEDTLS_DECRYPT. * * \return \c 0 on success. - * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA if - * parameter verification fails. + * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA on + * parameter-verification failure. * \return A cipher-specific error code on failure. */ int mbedtls_cipher_setkey( mbedtls_cipher_context_t *ctx, const unsigned char *key, @@ -542,7 +543,8 @@ int mbedtls_cipher_set_padding_mode( mbedtls_cipher_context_t *ctx, mbedtls_ciph * This parameter is discarded by ciphers with fixed-size IV. * * \return \c 0 on success. - * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA on failure. + * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA on + * parameter-verification failure. */ int mbedtls_cipher_set_iv( mbedtls_cipher_context_t *ctx, const unsigned char *iv, size_t iv_len ); @@ -553,8 +555,8 @@ int mbedtls_cipher_set_iv( mbedtls_cipher_context_t *ctx, * \param ctx The generic cipher context. * * \return \c 0 on success. - * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA - * if parameter verification fails. + * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA on + * parameter-verification failure. */ int mbedtls_cipher_reset( mbedtls_cipher_context_t *ctx ); @@ -585,10 +587,10 @@ int mbedtls_cipher_update_ad( mbedtls_cipher_context_t *ctx, * Exception: For MBEDTLS_MODE_ECB, expects a single block * in size. For example, 16 Bytes for AES. * - * \note If the underlying cipher is GCM, all calls to this - * function, except the last one before - * mbedtls_cipher_finish(). Must have \p ilen as a - * multiple of the block_size. + * \note If the underlying cipher is used in GCM mode, all calls + * to this function, except for the last one before + * mbedtls_cipher_finish(), must have \p ilen as a + * multiple of the block size of the cipher. * * \param ctx The generic cipher context. * \param input The buffer holding the input data. @@ -600,8 +602,8 @@ int mbedtls_cipher_update_ad( mbedtls_cipher_context_t *ctx, * actual number of Bytes written. * * \return \c 0 on success. - * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA if - * parameter verification fails. + * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA on + * parameter-verification failure. * \return #MBEDTLS_ERR_CIPHER_FEATURE_UNAVAILABLE on an * unsupported mode for a cipher. * \return A cipher-specific error code on failure. @@ -620,10 +622,10 @@ int mbedtls_cipher_update( mbedtls_cipher_context_t *ctx, const unsigned char *i * \param olen The length of the data written to the \p output buffer. * * \return \c 0 on success. - * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA if - * parameter verification fails. - * \return #MBEDTLS_ERR_CIPHER_FULL_BLOCK_EXPECTED if decryption - * expected a full block but was not provided one. + * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA on + * parameter-verification failure. + * \return #MBEDTLS_ERR_CIPHER_FULL_BLOCK_EXPECTED on decryption + * expecting a full block but not receiving one. * \return #MBEDTLS_ERR_CIPHER_INVALID_PADDING on invalid padding * while decrypting. * \return A cipher-specific error code on failure. @@ -684,9 +686,10 @@ int mbedtls_cipher_check_tag( mbedtls_cipher_context_t *ctx, * ciphers, use \p iv = NULL and \p iv_len = 0. * * \return \c 0 on success. - * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA, or - * #MBEDTLS_ERR_CIPHER_FULL_BLOCK_EXPECTED if decryption - * expected a full block but was not provided one. + * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA on + * parameter-verification failure. + * \return #MBEDTLS_ERR_CIPHER_FULL_BLOCK_EXPECTED on decryption + * expecting a full block but not receiving one. * \return #MBEDTLS_ERR_CIPHER_INVALID_PADDING on invalid padding * while decrypting. * \return A cipher-specific error code on failure. @@ -716,7 +719,8 @@ int mbedtls_cipher_crypt( mbedtls_cipher_context_t *ctx, * \param tag_len The desired length of the authentication tag. * * \return \c 0 on success. - * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA. + * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA on + * parameter-verification failure. * \return A cipher-specific error code on failure. */ int mbedtls_cipher_auth_encrypt( mbedtls_cipher_context_t *ctx, @@ -749,7 +753,8 @@ int mbedtls_cipher_auth_encrypt( mbedtls_cipher_context_t *ctx, * \param tag_len The length of the authentication tag. * * \return \c 0 on success. - * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA. + * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA on + * parameter-verification failure. * \return #MBEDTLS_ERR_CIPHER_AUTH_FAILED if data is not authentic. * \return A cipher-specific error code on failure. */ From c441f7490005800065b206dbfaabbabfe54b9fe7 Mon Sep 17 00:00:00 2001 From: Rose Zadik Date: Thu, 19 Apr 2018 14:38:20 +0100 Subject: [PATCH 21/30] Update cipher.h minor fix --- include/mbedtls/cipher.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/include/mbedtls/cipher.h b/include/mbedtls/cipher.h index 473181762..a13145208 100644 --- a/include/mbedtls/cipher.h +++ b/include/mbedtls/cipher.h @@ -97,7 +97,7 @@ typedef enum { */ typedef enum { MBEDTLS_CIPHER_NONE = 0, /**< Placeholder to mark the end of cipher-pair lists. */ - MBEDTLS_CIPHER_NULL, /**< The cipher-pair, treated as a stream cipher. */ + MBEDTLS_CIPHER_NULL, /**< The identity stream cipher. */ MBEDTLS_CIPHER_AES_128_ECB, /**< AES cipher with 128-bit ECB mode. */ MBEDTLS_CIPHER_AES_192_ECB, /**< AES cipher with 192-bit ECB mode. */ MBEDTLS_CIPHER_AES_256_ECB, /**< AES cipher with 256-bit ECB mode. */ From 93f9919c26d8a42bc3ead452964b8e5b189b0522 Mon Sep 17 00:00:00 2001 From: Rose Zadik Date: Thu, 19 Apr 2018 14:41:33 +0100 Subject: [PATCH 22/30] Update cipher.h Fixed typo. --- include/mbedtls/cipher.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/include/mbedtls/cipher.h b/include/mbedtls/cipher.h index a13145208..3ee2ab7db 100644 --- a/include/mbedtls/cipher.h +++ b/include/mbedtls/cipher.h @@ -82,7 +82,7 @@ typedef enum { MBEDTLS_CIPHER_ID_NULL, /**< The identity cipher, treated as a stream cipher. */ MBEDTLS_CIPHER_ID_AES, /**< The AES cipher. */ MBEDTLS_CIPHER_ID_DES, /**< The DES cipher. */ - MBEDTLS_CIPHER_ID_3DES, /**< The Trile DES cipher. */ + MBEDTLS_CIPHER_ID_3DES, /**< The Triple DES cipher. */ MBEDTLS_CIPHER_ID_CAMELLIA, /**< The Camellia cipher. */ MBEDTLS_CIPHER_ID_BLOWFISH, /**< The Blowfish cipher. */ MBEDTLS_CIPHER_ID_ARC4, /**< The RC4 cipher. */ From b2e111a288811b7edd4616dda55afd680c6d4195 Mon Sep 17 00:00:00 2001 From: Rose Zadik Date: Fri, 20 Apr 2018 10:13:48 +0100 Subject: [PATCH 23/30] Update ecp.h Changes based on review comments. 2 comments still open pending decisions --- include/mbedtls/ecp.h | 95 ++++++++++++++++++++++--------------------- 1 file changed, 49 insertions(+), 46 deletions(-) diff --git a/include/mbedtls/ecp.h b/include/mbedtls/ecp.h index c58a4b6ab..050283c4a 100644 --- a/include/mbedtls/ecp.h +++ b/include/mbedtls/ecp.h @@ -1,11 +1,11 @@ /** * \file ecp.h * - * \brief This file contains ECP definitions and functions. + * \brief This file provides an API for Elliptic Curves over GF(P) (ECP). * - * The use of Elliptic Curves over GF(P) (ECP) in cryptography and - * TLS is defined in Standards for Efficient Cryptography Group - * (SECG): SEC1 Elliptic Curve Cryptography and + * The use of ECP in cryptography and TLS is defined in + * Standards for Efficient Cryptography Group (SECG): SEC1 + * Elliptic Curve Cryptography and * RFC-4492: Elliptic Curve Cryptography (ECC) Cipher Suites * for Transport Layer Security (TLS). * @@ -43,7 +43,7 @@ */ #define MBEDTLS_ERR_ECP_BAD_INPUT_DATA -0x4F80 /**< Bad input parameters to function. */ #define MBEDTLS_ERR_ECP_BUFFER_TOO_SMALL -0x4F00 /**< The buffer is too small to write to. */ -#define MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE -0x4E80 /**< The requested curve not available. */ +#define MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE -0x4E80 /**< The requested curve is not available. */ #define MBEDTLS_ERR_ECP_VERIFY_FAILED -0x4E00 /**< The signature is not valid. */ #define MBEDTLS_ERR_ECP_ALLOC_FAILED -0x4D80 /**< Memory allocation failed. */ #define MBEDTLS_ERR_ECP_RANDOM_FAILED -0x4D00 /**< Generation of random value, such as ephemeral key, failed. */ @@ -65,7 +65,7 @@ extern "C" { #endif /** - * Definition of domain parameter identifiers: curve, subgroup and generator. + * Domain parameters: curve, subgroup, and generator. * * \note Only curves over prime fields are supported. * @@ -76,16 +76,16 @@ extern "C" { typedef enum { MBEDTLS_ECP_DP_NONE = 0, /*!< Curve not defined. */ - MBEDTLS_ECP_DP_SECP192R1, /*!< Domain parameters for 192-bit NIST curve. */ - MBEDTLS_ECP_DP_SECP224R1, /*!< Domain parameters for 224-bit NIST curve. */ - MBEDTLS_ECP_DP_SECP256R1, /*!< Domain parameters for 256-bit NIST curve. */ - MBEDTLS_ECP_DP_SECP384R1, /*!< Domain parameters for 384-bit NIST curve. */ - MBEDTLS_ECP_DP_SECP521R1, /*!< Domain parameters for 521-bit NIST curve. */ + MBEDTLS_ECP_DP_SECP192R1, /*!< Domain parameters for the 192-bit curve defined by FIPS 186-4 and SEC1. */ + MBEDTLS_ECP_DP_SECP224R1, /*!< Domain parameters for the 224-bit curve defined by FIPS 186-4 and SEC1. */ + MBEDTLS_ECP_DP_SECP256R1, /*!< Domain parameters for the 256-bit curve defined by FIPS 186-4 and SEC1. */ + MBEDTLS_ECP_DP_SECP384R1, /*!< Domain parameters for the 384-bit curve defined by FIPS 186-4 and SEC1. */ + MBEDTLS_ECP_DP_SECP521R1, /*!< Domain parameters for the 521-bit curve defined by FIPS 186-4 and SEC1. */ MBEDTLS_ECP_DP_BP256R1, /*!< Domain parameters for 256-bit Brainpool curve. */ MBEDTLS_ECP_DP_BP384R1, /*!< Domain parameters for 384-bit Brainpool curve. */ MBEDTLS_ECP_DP_BP512R1, /*!< Domain parameters for 512-bit Brainpool curve. */ - MBEDTLS_ECP_DP_CURVE25519, /*!< Domain parameters for a Curve25519 curve. */ - MBEDTLS_ECP_DP_CURVE448, /*!< Domain parameters for a Curve448 curve. */ + MBEDTLS_ECP_DP_CURVE25519, /*!< Domain parameters for Curve25519. */ + MBEDTLS_ECP_DP_CURVE448, /*!< Domain parameters for Curve448. */ MBEDTLS_ECP_DP_SECP192K1, /*!< Domain parameters for 192-bit "Koblitz" curve. */ MBEDTLS_ECP_DP_SECP224K1, /*!< Domain parameters for 224-bit "Koblitz" curve. */ MBEDTLS_ECP_DP_SECP256K1, /*!< Domain parameters for 256-bit "Koblitz" curve. */ @@ -105,7 +105,7 @@ typedef struct { mbedtls_ecp_group_id grp_id; /*!< An internal identifier. */ uint16_t tls_id; /*!< The TLS NamedCurve identifier. */ - uint16_t bit_size; /*!< The size of the curve in bits. */ + uint16_t bit_size; /*!< The curve size in bits. */ const char *name; /*!< A human-friendly name. */ } mbedtls_ecp_curve_info; @@ -132,15 +132,16 @@ mbedtls_ecp_point; * \brief The ECP group structure. * * We consider two types of curve equations: - *
    1. Short Weierstrass: y^2 = x^3 + A x + B mod P + *
      • Short Weierstrass: y^2 = x^3 + A x + B mod P * (SEC1 + RFC-4492)
        • *
      • Montgomery: y^2 = x^3 + A x^2 + x mod P (Curve25519, - * Curve448)
    + * Curve448) * In both cases, the generator (\p G) for a prime-order subgroup is fixed. * * For Short Weierstrass, this subgroup is the whole curve, and its * cardinality is denoted by \p N. Our code requires that \p N is an - * odd prime. + * odd prime as mbedtls_ecp_mul() requires an odd number, and + * mbedtls_ecdsa_sign() requires that it is prime for blinding purposes. * * For Montgomery curves, we do not store \p A, but (A + 2) / 4, * which is the quantity used in the formulas. Additionally, \p nbits is @@ -160,15 +161,15 @@ typedef struct { mbedtls_ecp_group_id id; /*!< An internal group identifier. */ mbedtls_mpi P; /*!< The prime modulus of the base field. */ - mbedtls_mpi A; /*!< For (1) \p A in the equation or for - (2) (A + 2) / 4. */ - mbedtls_mpi B; /*!< For (1) \p B in the equation or - for (2) Unused. */ + mbedtls_mpi A; /*!< For Short Weierstrass: \p A in the equation. For + Montgomery curves: (A + 2) / 4. */ + mbedtls_mpi B; /*!< For Short Weierstrass: \p B in the equation. + For Montgomery curves: unused. */ mbedtls_ecp_point G; /*!< The generator of the subgroup used. */ mbedtls_mpi N; /*!< The order of \p G. */ size_t pbits; /*!< The number of bits in \p P.*/ - size_t nbits; /*!< For (1) The number of bits in \p P, or - for (2) the private keys. */ + size_t nbits; /*!< For Short Weierstrass: The number of bits in \p P. + For Montgomery curves: the private keys. */ unsigned int h; /*!< \internal 1 if the constants are static. */ int (*modp)(mbedtls_mpi *); /*!< The function for fast pseudo-reduction mod \p P (see above).*/ @@ -176,7 +177,7 @@ typedef struct int (*t_post)(mbedtls_ecp_point *, void *); /*!< Unused. */ void *t_data; /*!< Unused. */ mbedtls_ecp_point *T; /*!< Pre-computed points for ecp_mul_comb(). */ - size_t T_size; /*!< The number for pre-computed points. */ + size_t T_size; /*!< The number of pre-computed points. */ } mbedtls_ecp_group; @@ -498,7 +499,7 @@ int mbedtls_ecp_tls_read_point( const mbedtls_ecp_group *grp, mbedtls_ecp_point * \brief This function exports a point as a TLS ECPoint record. * * \param grp The ECP group used. - * \param pt The point to export. + * \param pt he point format to export to an \c MBEDTLS_ECP_PF_XXX constant. * \param format The export format. * \param olen The length of the data written. * \param buf The buffer to write to. @@ -631,9 +632,9 @@ int mbedtls_ecp_muladd( mbedtls_ecp_group *grp, mbedtls_ecp_point *R, * the NIST groups which all have a cofactor of 1. * * \note This function uses bare components rather than an - * mbedtls_ecp_keypair() structure, to ease use with other - * structures. For example, mbedtls_ecdh_context() or - * mbedtls_ecdsa_context(). + * ::mbedtls_ecp_keypair structure, to ease use with other + * structures, such as ::mbedtls_ecdh_context or + * ::mbedtls_ecdsa_context. * * \param grp The curve the point should lie on. * \param pt The point to check. @@ -648,9 +649,9 @@ int mbedtls_ecp_check_pubkey( const mbedtls_ecp_group *grp, const mbedtls_ecp_po * key for this curve. * * \note This function uses bare components rather than an - * mbedtls_ecp_keypair() structure to ease use with other - * structures such as mbedtls_ecdh_context() or - * mbedtls_ecdsa_context(). + * ::mbedtls_ecp_keypair structure to ease use with other + * structures, such as ::mbedtls_ecdh_context() or + * ::mbedtls_ecdsa_context. * * \param grp The group used. * \param d The integer to check. @@ -665,10 +666,10 @@ int mbedtls_ecp_check_privkey( const mbedtls_ecp_group *grp, const mbedtls_mpi * * point. * * \note This function uses bare components rather than an - * mbedtls_ecp_keypair() structure to ease use with other - * structures such as mbedtls_ecdh_context() or - * mbedtls_ecdsa_context(). -* + * ::mbedtls_ecp_keypair structure to ease use with other + * structures, such as ::mbedtls_ecdh_context or + * ::mbedtls_ecdsa_context. + * * \param grp The ECP group. * \param G The chosen base point. * \param d The destination MPI (secret part). @@ -690,9 +691,9 @@ int mbedtls_ecp_gen_keypair_base( mbedtls_ecp_group *grp, * \brief This function generates an ECP keypair. * * \note This function uses bare components rather than an - * mbedtls_ecp_keypair() structure to ease use with other - * structures such as mbedtls_ecdh_context() or - * mbedtls_ecdsa_context(). + * ::mbedtls_ecp_keypair structure to ease use with other + * structures, such as ::mbedtls_ecdh_context or + * ::mbedtls_ecdsa_context. * * \param grp The ECP group. * \param d The destination MPI (secret part). @@ -724,17 +725,19 @@ int mbedtls_ecp_gen_key( mbedtls_ecp_group_id grp_id, mbedtls_ecp_keypair *key, int (*f_rng)(void *, unsigned char *, size_t), void *p_rng ); /** - * \brief This function checks a public-private key pair. + * \brief This function checks that the keypair objects + * \p pub and \p prv have the same group and the + * same public point, and that the private key in + * \p prv is consistent with the public key. * * \param pub The keypair structure holding the public key. - * \param prv The keypair structure holding the private key. + * If it contains a private key, that part is ignored. + * \param prv The keypair structure holding the full keypair. * - * \note The both are keypairs, and may optionally hold the corresponding other key, but the public key passed in thee pub is checked against the private key passed in prv. - * - * \return \c 0 on success - the keys are valid and match. - * \return #MBEDTLS_ERR_ECP_BAD_INPUT_DATA, or an \c - * MBEDTLS_ERR_ECP_XXX or an \c MBEDTLS_ERR_MPI_XXX - * error code on failure. + * \return \c 0 on success, meaning that the keys are valid and match. + * \return #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if the keys are invalid or do not match. + * \return An \c MBEDTLS_ERR_ECP_XXX or an \c MBEDTLS_ERR_MPI_XXX + * error code on calculation failure. */ int mbedtls_ecp_check_pub_priv( const mbedtls_ecp_keypair *pub, const mbedtls_ecp_keypair *prv ); From f089fa334181d89bdd37a50b933c9568d1426e4d Mon Sep 17 00:00:00 2001 From: Rose Zadik Date: Fri, 20 Apr 2018 10:41:16 +0100 Subject: [PATCH 24/30] Update ecp.h minor spacing/comment format fixes --- include/mbedtls/ecp.h | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/include/mbedtls/ecp.h b/include/mbedtls/ecp.h index 050283c4a..1a5d7d798 100644 --- a/include/mbedtls/ecp.h +++ b/include/mbedtls/ecp.h @@ -232,7 +232,6 @@ mbedtls_ecp_keypair; * 521 145 141 135 120 97 * 384 214 209 198 177 146 * 256 320 320 303 262 226 - * 224 475 475 453 398 342 * 192 640 640 633 587 476 */ @@ -596,7 +595,7 @@ int mbedtls_ecp_mul( mbedtls_ecp_group *grp, mbedtls_ecp_point *R, /** * \brief This function performs multiplication and addition of two * points by integers: \p R = \p m * \p P + \p n * \p Q - + * * It is not thread-safe to use same group in multiple threads. * * \note In contrast to mbedtls_ecp_mul(), this function does not @@ -680,7 +679,7 @@ int mbedtls_ecp_check_privkey( const mbedtls_ecp_group *grp, const mbedtls_mpi * * \return \c 0 on success. * \return An \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_MPI_XXX error code * on failure. - */ + */ int mbedtls_ecp_gen_keypair_base( mbedtls_ecp_group *grp, const mbedtls_ecp_point *G, mbedtls_mpi *d, mbedtls_ecp_point *Q, From abc9ec73b04c9e7f0e3fb3123471c33a973eed36 Mon Sep 17 00:00:00 2001 From: Rose Zadik Date: Mon, 23 Apr 2018 06:16:40 +0100 Subject: [PATCH 25/30] Update ecdsa.h Merged change to MBEDTLS_ERR_ECP_SIG_LEN_MISMATCH from other commit for merging, as requested (lines 282+283). --- include/mbedtls/ecdsa.h | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/include/mbedtls/ecdsa.h b/include/mbedtls/ecdsa.h index 11df7e215..ce1a03d79 100644 --- a/include/mbedtls/ecdsa.h +++ b/include/mbedtls/ecdsa.h @@ -279,8 +279,8 @@ int mbedtls_ecdsa_write_signature_det( mbedtls_ecdsa_context *ctx, * * \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 #MBEDTLS_ERR_ECP_SIG_LEN_MISMATCH if there is a valid + * signature in \p sig, but its 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. */ From d76ac587d3b4eb37548b032d6fd6765575ee9959 Mon Sep 17 00:00:00 2001 From: Rose Zadik Date: Mon, 23 Apr 2018 06:29:34 +0100 Subject: [PATCH 26/30] Update ecp.h Changes based on review comments. Waiting for responses on 2 remaining comments --- include/mbedtls/ecp.h | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/include/mbedtls/ecp.h b/include/mbedtls/ecp.h index 1a5d7d798..f7f57c073 100644 --- a/include/mbedtls/ecp.h +++ b/include/mbedtls/ecp.h @@ -43,7 +43,7 @@ */ #define MBEDTLS_ERR_ECP_BAD_INPUT_DATA -0x4F80 /**< Bad input parameters to function. */ #define MBEDTLS_ERR_ECP_BUFFER_TOO_SMALL -0x4F00 /**< The buffer is too small to write to. */ -#define MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE -0x4E80 /**< The requested curve is not available. */ +#define MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE -0x4E80 /**< The requested feature is not available, for example, . */ #define MBEDTLS_ERR_ECP_VERIFY_FAILED -0x4E00 /**< The signature is not valid. */ #define MBEDTLS_ERR_ECP_ALLOC_FAILED -0x4D80 /**< Memory allocation failed. */ #define MBEDTLS_ERR_ECP_RANDOM_FAILED -0x4D00 /**< Generation of random value, such as ephemeral key, failed. */ @@ -65,7 +65,7 @@ extern "C" { #endif /** - * Domain parameters: curve, subgroup, and generator. + * Domain-parameter identifiers: curve, subgroup, and generator. * * \note Only curves over prime fields are supported. * @@ -169,7 +169,8 @@ typedef struct mbedtls_mpi N; /*!< The order of \p G. */ size_t pbits; /*!< The number of bits in \p P.*/ size_t nbits; /*!< For Short Weierstrass: The number of bits in \p P. - For Montgomery curves: the private keys. */ + For Montgomery curves: the number of bits in the + private keys. */ unsigned int h; /*!< \internal 1 if the constants are static. */ int (*modp)(mbedtls_mpi *); /*!< The function for fast pseudo-reduction mod \p P (see above).*/ @@ -187,7 +188,7 @@ mbedtls_ecp_group; * A generic key-pair that may be used for ECDSA and fixed ECDH, for example. * * \note Members are deliberately in the same order as in the - * #mbedtls_ecdsa_context structure. + * ::mbedtls_ecdsa_context structure. */ typedef struct { @@ -498,7 +499,7 @@ int mbedtls_ecp_tls_read_point( const mbedtls_ecp_group *grp, mbedtls_ecp_point * \brief This function exports a point as a TLS ECPoint record. * * \param grp The ECP group used. - * \param pt he point format to export to an \c MBEDTLS_ECP_PF_XXX constant. + * \param pt The point format to export to an \c MBEDTLS_ECP_PF_XXX constant. * \param format The export format. * \param olen The length of the data written. * \param buf The buffer to write to. @@ -649,7 +650,7 @@ int mbedtls_ecp_check_pubkey( const mbedtls_ecp_group *grp, const mbedtls_ecp_po * * \note This function uses bare components rather than an * ::mbedtls_ecp_keypair structure to ease use with other - * structures, such as ::mbedtls_ecdh_context() or + * structures, such as ::mbedtls_ecdh_context or * ::mbedtls_ecdsa_context. * * \param grp The group used. From c32efb3f641313279a5d75ff7e102ed84e32c899 Mon Sep 17 00:00:00 2001 From: Rose Zadik Date: Mon, 23 Apr 2018 09:38:29 +0100 Subject: [PATCH 27/30] Update ecp.h Resolved last review comment --- include/mbedtls/ecp.h | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/include/mbedtls/ecp.h b/include/mbedtls/ecp.h index f7f57c073..e11cdf2d8 100644 --- a/include/mbedtls/ecp.h +++ b/include/mbedtls/ecp.h @@ -499,7 +499,8 @@ int mbedtls_ecp_tls_read_point( const mbedtls_ecp_group *grp, mbedtls_ecp_point * \brief This function exports a point as a TLS ECPoint record. * * \param grp The ECP group used. - * \param pt The point format to export to an \c MBEDTLS_ECP_PF_XXX constant. + * \param pt The point format to export to. The point format is an + * \c MBEDTLS_ECP_PF_XXX constant. * \param format The export format. * \param olen The length of the data written. * \param buf The buffer to write to. From d35340550dea413e5a7ce872561eb84c96179be3 Mon Sep 17 00:00:00 2001 From: Rose Zadik Date: Mon, 23 Apr 2018 16:12:42 +0100 Subject: [PATCH 28/30] Update ecp.h fixed omittion --- include/mbedtls/ecp.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/include/mbedtls/ecp.h b/include/mbedtls/ecp.h index e11cdf2d8..6924d4036 100644 --- a/include/mbedtls/ecp.h +++ b/include/mbedtls/ecp.h @@ -43,7 +43,7 @@ */ #define MBEDTLS_ERR_ECP_BAD_INPUT_DATA -0x4F80 /**< Bad input parameters to function. */ #define MBEDTLS_ERR_ECP_BUFFER_TOO_SMALL -0x4F00 /**< The buffer is too small to write to. */ -#define MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE -0x4E80 /**< The requested feature is not available, for example, . */ +#define MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE -0x4E80 /**< The requested feature is not available, for example, the requested curve is not supported. */ #define MBEDTLS_ERR_ECP_VERIFY_FAILED -0x4E00 /**< The signature is not valid. */ #define MBEDTLS_ERR_ECP_ALLOC_FAILED -0x4D80 /**< Memory allocation failed. */ #define MBEDTLS_ERR_ECP_RANDOM_FAILED -0x4D00 /**< Generation of random value, such as ephemeral key, failed. */ From a7a6155272baaae2a99a0021ac0694842eeac392 Mon Sep 17 00:00:00 2001 From: Rose Zadik Date: Tue, 24 Apr 2018 13:14:01 +0100 Subject: [PATCH 29/30] Update ecp.h One fix. Removed trailing whitespaces --- include/mbedtls/ecp.h | 107 +++++++++++++++++++++--------------------- 1 file changed, 53 insertions(+), 54 deletions(-) diff --git a/include/mbedtls/ecp.h b/include/mbedtls/ecp.h index 6924d4036..9fc650ee3 100644 --- a/include/mbedtls/ecp.h +++ b/include/mbedtls/ecp.h @@ -8,13 +8,13 @@ * Elliptic Curve Cryptography     and * RFC-4492: Elliptic Curve Cryptography (ECC) Cipher Suites * for Transport Layer Security (TLS). - * + * * RFC-2409: The Internet Key Exchange (IKE) defines ECP * group types. - * + * */ -/* +/* * Copyright (C) 2006-2018, Arm Limited (or its affiliates), All Rights Reserved * SPDX-License-Identifier: Apache-2.0 * @@ -32,7 +32,7 @@ * * This file is part of Mbed TLS (https://tls.mbed.org) */ - + #ifndef MBEDTLS_ECP_H #define MBEDTLS_ECP_H @@ -114,10 +114,10 @@ typedef struct * * \note All functions expect and return points satisfying * the following condition: Z == 0 or - * Z == 1. Other values of \p Z are + * Z == 1. Other values of \p Z are * used only by internal functions. * The point is zero, or "at infinity", if Z == 0. - * Otherwise, \p X and \p Y are its standard (affine) + * Otherwise, \p X and \p Y are its standard (affine) * coordinates. */ typedef struct @@ -144,18 +144,17 @@ mbedtls_ecp_point; * mbedtls_ecdsa_sign() requires that it is prime for blinding purposes. * * For Montgomery curves, we do not store \p A, but (A + 2) / 4, - * which is the quantity used in the formulas. Additionally, \p nbits is + * which is the quantity used in the formulas. Additionally, \p nbits is * not the size of \p N but the required size for private keys. * - * If \p modp is NULL, reduction modulo \p P is done using a generic algorithm. - * Otherwise, \p modp must point to a function that takes an \p mbedtls_mpi in the - * range of 0..2^(2*pbits)-1, and transforms it in-place to an integer which is - * congruent mod \p P to the given MPI, and is close enough to \p pbits in size, - * so that it may be efficiently brought in the 0..P-1 range by a few additions - * or subtractions. Therefore, it is only an approximative modular reduction. + * If \p modp is NULL, reduction modulo \p P is done using a generic algorithm. + * Otherwise, \p modp must point to a function that takes an \p mbedtls_mpi in the + * range of 0..2^(2*pbits)-1, and transforms it in-place to an integer + * which is congruent mod \p P to the given MPI, and is close enough to \p pbits + * in size, so that it may be efficiently brought in the 0..P-1 range by a few + * additions or subtractions. Therefore, it is only an approximative modular + * reduction. It must return 0 on success and non-zero on failure. * - * \return \c 0 on success - * \return Non-zero error code on failure. */ typedef struct { @@ -169,10 +168,10 @@ typedef struct mbedtls_mpi N; /*!< The order of \p G. */ size_t pbits; /*!< The number of bits in \p P.*/ size_t nbits; /*!< For Short Weierstrass: The number of bits in \p P. - For Montgomery curves: the number of bits in the + For Montgomery curves: the number of bits in the private keys. */ unsigned int h; /*!< \internal 1 if the constants are static. */ - int (*modp)(mbedtls_mpi *); /*!< The function for fast pseudo-reduction + int (*modp)(mbedtls_mpi *); /*!< The function for fast pseudo-reduction mod \p P (see above).*/ int (*t_pre)(mbedtls_ecp_point *, void *); /*!< Unused. */ int (*t_post)(mbedtls_ecp_point *, void *); /*!< Unused. */ @@ -187,7 +186,7 @@ mbedtls_ecp_group; * * A generic key-pair that may be used for ECDSA and fixed ECDH, for example. * - * \note Members are deliberately in the same order as in the + * \note Members are deliberately in the same order as in the * ::mbedtls_ecdsa_context structure. */ typedef struct @@ -298,7 +297,7 @@ const mbedtls_ecp_group_id *mbedtls_ecp_grp_id_list( void ); const mbedtls_ecp_curve_info *mbedtls_ecp_curve_info_from_grp_id( mbedtls_ecp_group_id grp_id ); /** - * \brief This function retrieves curve information from a TLS + * \brief This function retrieves curve information from a TLS * NamedCurve value. * * \param tls_id An \c MBEDTLS_ECP_DP_XXX value. @@ -309,7 +308,7 @@ const mbedtls_ecp_curve_info *mbedtls_ecp_curve_info_from_grp_id( mbedtls_ecp_gr const mbedtls_ecp_curve_info *mbedtls_ecp_curve_info_from_tls_id( uint16_t tls_id ); /** - * \brief This function retrieves curve information from a + * \brief This function retrieves curve information from a * human-readable name. * * \param name The human-readable name. @@ -328,7 +327,7 @@ void mbedtls_ecp_point_init( mbedtls_ecp_point *pt ); /** * \brief This function initializes an ECP group context - * without loading any domain parameters. + * without loading any domain parameters. * * \note After this function is called, domain parameters * for various ECP groups can be loaded through the @@ -364,7 +363,7 @@ void mbedtls_ecp_group_free( mbedtls_ecp_group *grp ); void mbedtls_ecp_keypair_free( mbedtls_ecp_keypair *key ); /** - * \brief This function copies the contents of point \p Q into + * \brief This function copies the contents of point \p Q into * point \p P. * * \param P The destination point. @@ -376,7 +375,7 @@ void mbedtls_ecp_keypair_free( mbedtls_ecp_keypair *key ); int mbedtls_ecp_copy( mbedtls_ecp_point *P, const mbedtls_ecp_point *Q ); /** - * \brief This function copies the contents of group \p src into + * \brief This function copies the contents of group \p src into * group \p dst. * * \param dst The destination group. @@ -423,7 +422,7 @@ int mbedtls_ecp_point_cmp( const mbedtls_ecp_point *P, const mbedtls_ecp_point *Q ); /** - * \brief This function imports a non-zero point from two ASCII + * \brief This function imports a non-zero point from two ASCII * strings. * * \param P The destination point. @@ -459,7 +458,7 @@ int mbedtls_ecp_point_write_binary( const mbedtls_ecp_group *grp, const mbedtls_ * \brief This function imports a point from unsigned binary data. * * \note This function does not check that the point actually - * belongs to the given group, see mbedtls_ecp_check_pubkey() + * belongs to the given group, see mbedtls_ecp_check_pubkey() * for that. * * \param grp The group to which the point should belong. @@ -518,7 +517,7 @@ int mbedtls_ecp_tls_write_point( const mbedtls_ecp_group *grp, const mbedtls_ecp * \brief This function sets a group using standardized domain parameters. * * \note The index should be a value of the NamedCurve enum, - * as defined in RFC-4492: Elliptic Curve Cryptography + * as defined in RFC-4492: Elliptic Curve Cryptography * (ECC) Cipher Suites for Transport Layer Security (TLS), * usually in the form of an \c MBEDTLS_ECP_DP_XXX macro. * @@ -528,7 +527,7 @@ int mbedtls_ecp_tls_write_point( const mbedtls_ecp_group *grp, const mbedtls_ecp * \return \c 0 on success, * \return An \c MBEDTLS_ERR_MPI_XXX error code on initialization failure. * \return #MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE for unkownn groups. - + */ int mbedtls_ecp_group_load( mbedtls_ecp_group *grp, mbedtls_ecp_group_id id ); @@ -563,7 +562,7 @@ int mbedtls_ecp_tls_write_group( const mbedtls_ecp_group *grp, size_t *olen, unsigned char *buf, size_t blen ); /** - * \brief This function performs multiplication of a point by + * \brief This function performs multiplication of a point by * an integer: \p R = \p m * \p P. * * It is not thread-safe to use same group in multiple threads. @@ -595,12 +594,12 @@ int mbedtls_ecp_mul( mbedtls_ecp_group *grp, mbedtls_ecp_point *R, int (*f_rng)(void *, unsigned char *, size_t), void *p_rng ); /** - * \brief This function performs multiplication and addition of two + * \brief This function performs multiplication and addition of two * points by integers: \p R = \p m * \p P + \p n * \p Q * * It is not thread-safe to use same group in multiple threads. * - * \note In contrast to mbedtls_ecp_mul(), this function does not + * \note In contrast to mbedtls_ecp_mul(), this function does not * guarantee a constant execution flow and timing. * * \param grp The ECP group. @@ -611,8 +610,8 @@ int mbedtls_ecp_mul( mbedtls_ecp_group *grp, mbedtls_ecp_point *R, * \param Q The point to be multiplied by \p n. * * \return \c 0 on success. - * \return #MBEDTLS_ERR_ECP_INVALID_KEY if \p m or \p n are not - * valid private keys, or \p P or \p Q are not valid public + * \return #MBEDTLS_ERR_ECP_INVALID_KEY if \p m or \p n are not + * valid private keys, or \p P or \p Q are not valid public * keys. * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory-allocation failure. */ @@ -621,20 +620,20 @@ int mbedtls_ecp_muladd( mbedtls_ecp_group *grp, mbedtls_ecp_point *R, const mbedtls_mpi *n, const mbedtls_ecp_point *Q ); /** - * \brief This function checks that a point is a valid public key + * \brief This function checks that a point is a valid public key * on this curve. * - * It only checks that the point is non-zero, has - * valid coordinates and lies on the curve. It does not verify - * that it is indeed a multiple of \p G. This additional + * It only checks that the point is non-zero, has + * valid coordinates and lies on the curve. It does not verify + * that it is indeed a multiple of \p G. This additional * check is computationally more expensive, is not required * by standards, and should not be necessary if the group - * used has a small cofactor. In particular, it is useless for + * used has a small cofactor. In particular, it is useless for * the NIST groups which all have a cofactor of 1. * - * \note This function uses bare components rather than an - * ::mbedtls_ecp_keypair structure, to ease use with other - * structures, such as ::mbedtls_ecdh_context or + * \note This function uses bare components rather than an + * ::mbedtls_ecp_keypair structure, to ease use with other + * structures, such as ::mbedtls_ecdh_context or * ::mbedtls_ecdsa_context. * * \param grp The curve the point should lie on. @@ -646,12 +645,12 @@ int mbedtls_ecp_muladd( mbedtls_ecp_group *grp, mbedtls_ecp_point *R, int mbedtls_ecp_check_pubkey( const mbedtls_ecp_group *grp, const mbedtls_ecp_point *pt ); /** - * \brief This function checks that an \p mbedtls_mpi is a valid private + * \brief This function checks that an \p mbedtls_mpi is a valid private * key for this curve. * - * \note This function uses bare components rather than an - * ::mbedtls_ecp_keypair structure to ease use with other - * structures, such as ::mbedtls_ecdh_context or + * \note This function uses bare components rather than an + * ::mbedtls_ecp_keypair structure to ease use with other + * structures, such as ::mbedtls_ecdh_context or * ::mbedtls_ecdsa_context. * * \param grp The group used. @@ -663,12 +662,12 @@ int mbedtls_ecp_check_pubkey( const mbedtls_ecp_group *grp, const mbedtls_ecp_po int mbedtls_ecp_check_privkey( const mbedtls_ecp_group *grp, const mbedtls_mpi *d ); /** - * \brief This function generates a keypair with a configurable base + * \brief This function generates a keypair with a configurable base * point. * - * \note This function uses bare components rather than an - * ::mbedtls_ecp_keypair structure to ease use with other - * structures, such as ::mbedtls_ecdh_context or + * \note This function uses bare components rather than an + * ::mbedtls_ecp_keypair structure to ease use with other + * structures, such as ::mbedtls_ecdh_context or * ::mbedtls_ecdsa_context. * * \param grp The ECP group. @@ -691,9 +690,9 @@ int mbedtls_ecp_gen_keypair_base( mbedtls_ecp_group *grp, /** * \brief This function generates an ECP keypair. * - * \note This function uses bare components rather than an - * ::mbedtls_ecp_keypair structure to ease use with other - * structures, such as ::mbedtls_ecdh_context or + * \note This function uses bare components rather than an + * ::mbedtls_ecp_keypair structure to ease use with other + * structures, such as ::mbedtls_ecdh_context or * ::mbedtls_ecdsa_context. * * \param grp The ECP group. @@ -726,7 +725,7 @@ int mbedtls_ecp_gen_key( mbedtls_ecp_group_id grp_id, mbedtls_ecp_keypair *key, int (*f_rng)(void *, unsigned char *, size_t), void *p_rng ); /** - * \brief This function checks that the keypair objects + * \brief This function checks that the keypair objects * \p pub and \p prv have the same group and the * same public point, and that the private key in * \p prv is consistent with the public key. @@ -735,9 +734,9 @@ int mbedtls_ecp_gen_key( mbedtls_ecp_group_id grp_id, mbedtls_ecp_keypair *key, * If it contains a private key, that part is ignored. * \param prv The keypair structure holding the full keypair. * - * \return \c 0 on success, meaning that the keys are valid and match. + * \return \c 0 on success, meaning that the keys are valid and match. * \return #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if the keys are invalid or do not match. - * \return An \c MBEDTLS_ERR_ECP_XXX or an \c MBEDTLS_ERR_MPI_XXX + * \return An \c MBEDTLS_ERR_ECP_XXX or an \c MBEDTLS_ERR_MPI_XXX * error code on calculation failure. */ int mbedtls_ecp_check_pub_priv( const mbedtls_ecp_keypair *pub, const mbedtls_ecp_keypair *prv ); From 3dd8abd037f9b5a0a7b543fc38e18d0f349b0a42 Mon Sep 17 00:00:00 2001 From: Jaeden Amero Date: Tue, 24 Apr 2018 10:56:55 +0100 Subject: [PATCH 30/30] Regenerate errors after ecp.h updates The error descriptions were updated in ecp.h (PR #1578), so also update the strings in error.c. --- library/error.c | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/library/error.c b/library/error.c index 96ab20376..222d85b62 100644 --- a/library/error.c +++ b/library/error.c @@ -256,19 +256,19 @@ void mbedtls_strerror( int ret, char *buf, size_t buflen ) if( use_ret == -(MBEDTLS_ERR_ECP_BUFFER_TOO_SMALL) ) mbedtls_snprintf( buf, buflen, "ECP - The buffer is too small to write to" ); if( use_ret == -(MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE) ) - mbedtls_snprintf( buf, buflen, "ECP - Requested curve not available" ); + mbedtls_snprintf( buf, buflen, "ECP - The requested feature is not available, for example, the requested curve is not supported" ); if( use_ret == -(MBEDTLS_ERR_ECP_VERIFY_FAILED) ) mbedtls_snprintf( buf, buflen, "ECP - The signature is not valid" ); if( use_ret == -(MBEDTLS_ERR_ECP_ALLOC_FAILED) ) mbedtls_snprintf( buf, buflen, "ECP - Memory allocation failed" ); if( use_ret == -(MBEDTLS_ERR_ECP_RANDOM_FAILED) ) - mbedtls_snprintf( buf, buflen, "ECP - Generation of random value, such as (ephemeral) key, failed" ); + mbedtls_snprintf( buf, buflen, "ECP - Generation of random value, such as ephemeral key, failed" ); if( use_ret == -(MBEDTLS_ERR_ECP_INVALID_KEY) ) mbedtls_snprintf( buf, buflen, "ECP - Invalid private or public key" ); if( use_ret == -(MBEDTLS_ERR_ECP_SIG_LEN_MISMATCH) ) mbedtls_snprintf( buf, buflen, "ECP - The buffer contains a valid signature followed by more data" ); if( use_ret == -(MBEDTLS_ERR_ECP_HW_ACCEL_FAILED) ) - mbedtls_snprintf( buf, buflen, "ECP - ECP hardware accelerator failed" ); + mbedtls_snprintf( buf, buflen, "ECP - The ECP hardware accelerator failed" ); #endif /* MBEDTLS_ECP_C */ #if defined(MBEDTLS_MD_C)