From f0bbd7e3fd6c5ce10dbc5ab0bc4e3e11759a45ca Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Manuel=20P=C3=A9gouri=C3=A9-Gonnard?= Date: Mon, 15 Oct 2018 13:22:41 +0200 Subject: [PATCH] Misc documentation fixes/improvements. --- ChangeLog | 16 ++++++++++------ include/mbedtls/config.h | 14 ++++++++------ include/mbedtls/ecdh.h | 16 ++++++++-------- include/mbedtls/ecdsa.h | 14 +++++++------- include/mbedtls/ecp.h | 6 +++--- include/mbedtls/pk.h | 4 ++-- include/mbedtls/x509_crt.h | 2 +- library/error.c | 2 +- 8 files changed, 40 insertions(+), 34 deletions(-) diff --git a/ChangeLog b/ChangeLog index 9ec9d4d94..e7a2f4df6 100644 --- a/ChangeLog +++ b/ChangeLog @@ -3,12 +3,16 @@ mbed TLS ChangeLog (Sorted per branch, date) = mbed TLS x.x.x branch released xxxx-xx-xx Features - * Add support for restartable ECC operations, enabled by - MBEDTLS_ECP_RESTARTABLE (disabled by default) at compile time and - mbedtls_ecp_set_max_ops() at runtime, using new xxx_restartable functions - in ECP, ECDSA, PK and X509 (CRL not supported yet), and using existing - functions in ECDH and SSL (currently only implemented client-side, for - ECDHE-ECDSA ciphersuites with TLS 1.2, including client authentication). + * Add support for temporarily suspending expensive ECC computations after + some configurable amount of operations, to be used in single-threaded + constrained systems where ECC is time consuming and blocking until + completion cannot be tolerated. This is enabled by + MBEDTLS_ECP_RESTARTABLE at compile time (disabled by default) and + configured by mbedtls_ecp_set_max_ops() at runtime. It applies to new + xxx_restartable functions in ECP, ECDSA, PK and X.509 (CRL not supported + yet), and to existing functions in ECDH and SSL (currently only + implemented client-side, for ECDHE-ECDSA ciphersuites in TLS 1.2, + including client authentication). Bugfix * Fix a bug in the update function for SSL ticket keys which previously diff --git a/include/mbedtls/config.h b/include/mbedtls/config.h index 3f248d5c4..92f024a17 100644 --- a/include/mbedtls/config.h +++ b/include/mbedtls/config.h @@ -682,14 +682,16 @@ * * Enable "non-blocking" ECC operations that can return early and be resumed. * - * This enables \c mbedtls_ecp_set_max_ops() and allows various functions - * to return #MBEDTLS_ERR_ECP_IN_PROGRESS (or, for functions in the SSL - * module, #MBEDTLS_ERR_SSL_CRYPTO_IN_PROGRESS) when needed, and then be - * called again later with the same arguments in order to further progress and - * eventually complete the operation, see \c mbedtls_ecp_set_max_ops(). + * This allows various functions to pause by returning + * #MBEDTLS_ERR_ECP_IN_PROGRESS (or, for functions in the SSL module, + * #MBEDTLS_ERR_SSL_CRYPTO_IN_PROGRESS) and then be called later again in + * order to further progress and eventually complete their operation. This is + * controlled through mbedtls_ecp_set_max_ops() which limits the maximum + * number of ECC operations a function may perform before pausing; see + * mbedtls_ecp_set_max_ops() for more information. * * This is useful in non-threaded environments if you want to avoid blocking - * for too long on ECC (hence, X509 or SSL/TLS) operations. + * for too long on ECC (and, hence, X.509 or SSL/TLS) operations. * * Uncomment this macro to enable restartable ECC computations. */ diff --git a/include/mbedtls/ecdh.h b/include/mbedtls/ecdh.h index ed3e8df42..8b75b9386 100644 --- a/include/mbedtls/ecdh.h +++ b/include/mbedtls/ecdh.h @@ -91,10 +91,10 @@ mbedtls_ecdh_context; * \param p_rng The RNG context. * * \return \c 0 on success. - * \return An \c MBEDTLS_ERR_ECP_XXX or - * \c MBEDTLS_MPI_XXX error code on failure. * \return #MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of * operations was reached: see \c mbedtls_ecp_set_max_ops(). + * \return Another \c MBEDTLS_ERR_ECP_XXX or + * \c MBEDTLS_MPI_XXX error code on failure. */ int mbedtls_ecdh_gen_public( mbedtls_ecp_group *grp, mbedtls_mpi *d, mbedtls_ecp_point *Q, int (*f_rng)(void *, unsigned char *, size_t), @@ -121,10 +121,10 @@ int mbedtls_ecdh_gen_public( mbedtls_ecp_group *grp, mbedtls_mpi *d, mbedtls_ecp * \param p_rng The RNG context. * * \return \c 0 on success. - * \return An \c MBEDTLS_ERR_ECP_XXX or - * \c MBEDTLS_MPI_XXX error code on failure. * \return #MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of * operations was reached: see \c mbedtls_ecp_set_max_ops(). + * \return Another \c MBEDTLS_ERR_ECP_XXX or + * \c MBEDTLS_MPI_XXX error code on failure. */ int mbedtls_ecdh_compute_shared( mbedtls_ecp_group *grp, mbedtls_mpi *z, const mbedtls_ecp_point *Q, const mbedtls_mpi *d, @@ -166,9 +166,9 @@ void mbedtls_ecdh_free( mbedtls_ecdh_context *ctx ); * \param p_rng The RNG context. * * \return \c 0 on success. - * \return An \c MBEDTLS_ERR_ECP_XXX error code on failure. * \return #MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of * operations was reached: see \c mbedtls_ecp_set_max_ops(). + * \return Another \c MBEDTLS_ERR_ECP_XXX error code on failure. */ int mbedtls_ecdh_make_params( mbedtls_ecdh_context *ctx, size_t *olen, unsigned char *buf, size_t blen, @@ -210,9 +210,9 @@ int mbedtls_ecdh_read_params( mbedtls_ecdh_context *ctx, * 0: The key of the peer. * * \return \c 0 on success. - * \return An \c MBEDTLS_ERR_ECP_XXX error code on failure. * \return #MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of * operations was reached: see \c mbedtls_ecp_set_max_ops(). + * \return Another \c MBEDTLS_ERR_ECP_XXX error code on failure. * */ int mbedtls_ecdh_get_params( mbedtls_ecdh_context *ctx, const mbedtls_ecp_keypair *key, @@ -235,9 +235,9 @@ int mbedtls_ecdh_get_params( mbedtls_ecdh_context *ctx, const mbedtls_ecp_keypai * \param p_rng The RNG context. * * \return \c 0 on success. - * \return An \c MBEDTLS_ERR_ECP_XXX error code on failure. * \return #MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of * operations was reached: see \c mbedtls_ecp_set_max_ops(). + * \return Another \c MBEDTLS_ERR_ECP_XXX error code on failure. */ int mbedtls_ecdh_make_public( mbedtls_ecdh_context *ctx, size_t *olen, unsigned char *buf, size_t blen, @@ -283,9 +283,9 @@ int mbedtls_ecdh_read_public( mbedtls_ecdh_context *ctx, * \param p_rng The RNG context. * * \return \c 0 on success. - * \return An \c MBEDTLS_ERR_ECP_XXX error code on failure. * \return #MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of * operations was reached: see \c mbedtls_ecp_set_max_ops(). + * \return Another \c MBEDTLS_ERR_ECP_XXX error code on failure. */ int mbedtls_ecdh_calc_secret( mbedtls_ecdh_context *ctx, size_t *olen, unsigned char *buf, size_t blen, diff --git a/include/mbedtls/ecdsa.h b/include/mbedtls/ecdsa.h index d5f7985cd..4057828d4 100644 --- a/include/mbedtls/ecdsa.h +++ b/include/mbedtls/ecdsa.h @@ -73,7 +73,7 @@ typedef mbedtls_ecp_keypair mbedtls_ecdsa_context; /** * \brief Internal restart context for ecdsa_verify() * - * \note Opaque struct + * \note Opaque struct, defined in ecdsa.c */ typedef struct mbedtls_ecdsa_restart_ver mbedtls_ecdsa_restart_ver_ctx; @@ -273,13 +273,13 @@ int mbedtls_ecdsa_write_signature( mbedtls_ecdsa_context *ctx, mbedtls_md_type_t * \param slen The length of the signature written. * \param f_rng The RNG function. * \param p_rng The RNG context. - * \param rs_ctx The restart context. + * \param rs_ctx The restart context (NULL disables restart). * * \return \c 0 on success. - * \return An \c MBEDTLS_ERR_ECP_XXX, \c MBEDTLS_ERR_MPI_XXX or - * \c MBEDTLS_ERR_ASN1_XXX error code on failure. * \return #MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of * operations was reached: see \c mbedtls_ecp_set_max_ops(). + * \return Another \c MBEDTLS_ERR_ECP_XXX, \c MBEDTLS_ERR_MPI_XXX or + * \c MBEDTLS_ERR_ASN1_XXX error code on failure. */ int mbedtls_ecdsa_write_signature_restartable( mbedtls_ecdsa_context *ctx, mbedtls_md_type_t md_alg, @@ -387,16 +387,16 @@ int mbedtls_ecdsa_read_signature( mbedtls_ecdsa_context *ctx, * \param hlen The size of the hash. * \param sig The signature to read and verify. * \param slen The size of \p sig. - * \param rs_ctx The restart context + * \param rs_ctx The restart context (NULL disables restart). * * \return \c 0 on success. * \return #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if signature is invalid. * \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. * \return #MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of * operations was reached: see \c mbedtls_ecp_set_max_ops(). + * \return Another \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_ERR_MPI_XXX + * error code on failure for any other reason. */ int mbedtls_ecdsa_read_signature_restartable( mbedtls_ecdsa_context *ctx, const unsigned char *hash, size_t hlen, diff --git a/include/mbedtls/ecp.h b/include/mbedtls/ecp.h index 15aee04c7..d13f3ba22 100644 --- a/include/mbedtls/ecp.h +++ b/include/mbedtls/ecp.h @@ -50,7 +50,7 @@ #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 /**< The ECP hardware accelerator failed. */ -#define MBEDTLS_ERR_ECP_IN_PROGRESS -0x4B00 /**< Operation in progress, try again with the same parameters. */ +#define MBEDTLS_ERR_ECP_IN_PROGRESS -0x4B00 /**< Operation in progress, call again with the same parameters to continue. */ #ifdef __cplusplus extern "C" { @@ -747,7 +747,7 @@ int mbedtls_ecp_mul( mbedtls_ecp_group *grp, mbedtls_ecp_point *R, * \param P The point to multiply. * \param f_rng The RNG function. * \param p_rng The RNG context. - * \param rs_ctx The restart context. + * \param rs_ctx The restart context (NULL disables restart). * * \return \c 0 on success. * \return #MBEDTLS_ERR_ECP_INVALID_KEY if \p m is not a valid private @@ -804,7 +804,7 @@ int mbedtls_ecp_muladd( mbedtls_ecp_group *grp, mbedtls_ecp_point *R, * \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. - * \param rs_ctx The restart context. + * \param rs_ctx The restart context (NULL disables restart). * * \return \c 0 on success. * \return #MBEDTLS_ERR_ECP_INVALID_KEY if \p m or \p n are not diff --git a/include/mbedtls/pk.h b/include/mbedtls/pk.h index 3b486cfe9..9ec33da05 100644 --- a/include/mbedtls/pk.h +++ b/include/mbedtls/pk.h @@ -127,7 +127,7 @@ typedef struct mbedtls_pk_info_t mbedtls_pk_info_t; */ typedef struct mbedtls_pk_context { - const mbedtls_pk_info_t * pk_info; /**< Public key informations */ + const mbedtls_pk_info_t * pk_info; /**< Public key information */ void * pk_ctx; /**< Underlying public key context */ } mbedtls_pk_context; @@ -137,7 +137,7 @@ typedef struct mbedtls_pk_context */ typedef struct { - const mbedtls_pk_info_t * pk_info; /**< Public key informations */ + const mbedtls_pk_info_t * pk_info; /**< Public key information */ void * rs_ctx; /**< Underlying restart context */ } mbedtls_pk_restart_ctx; #else /* MBEDTLS_ECDSA_C && MBEDTLS_ECP_RESTARTABLE */ diff --git a/include/mbedtls/x509_crt.h b/include/mbedtls/x509_crt.h index 961db9844..afeefca60 100644 --- a/include/mbedtls/x509_crt.h +++ b/include/mbedtls/x509_crt.h @@ -426,7 +426,7 @@ int mbedtls_x509_crt_verify_with_profile( mbedtls_x509_crt *crt, * \param flags result of the verification * \param f_vrfy verification function * \param p_vrfy verification parameter - * \param rs_ctx restart context + * \param rs_ctx restart context (NULL to disable restart) * * \return See \c mbedtls_crt_verify_with_profile(), or * \return #MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of diff --git a/library/error.c b/library/error.c index d48ba8f79..3345481f0 100644 --- a/library/error.c +++ b/library/error.c @@ -290,7 +290,7 @@ void mbedtls_strerror( int ret, char *buf, size_t buflen ) if( use_ret == -(MBEDTLS_ERR_ECP_HW_ACCEL_FAILED) ) mbedtls_snprintf( buf, buflen, "ECP - The ECP hardware accelerator failed" ); if( use_ret == -(MBEDTLS_ERR_ECP_IN_PROGRESS) ) - mbedtls_snprintf( buf, buflen, "ECP - Operation in progress, try again with the same parameters" ); + mbedtls_snprintf( buf, buflen, "ECP - Operation in progress, call again with the same parameters to continue" ); #endif /* MBEDTLS_ECP_C */ #if defined(MBEDTLS_MD_C)