From 12e4a8be2ade943bc60774f6bfe9ae53da92c875 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Manuel=20P=C3=A9gouri=C3=A9-Gonnard?= Date: Wed, 12 Sep 2018 10:55:15 +0200 Subject: [PATCH] Improve documentation wording and formatting --- include/mbedtls/config.h | 5 +++-- include/mbedtls/ecdsa.h | 3 ++- include/mbedtls/ecp.h | 27 +++++++++++++++------------ include/mbedtls/pk.h | 4 ++-- include/mbedtls/x509_crt.h | 2 +- 5 files changed, 23 insertions(+), 18 deletions(-) diff --git a/include/mbedtls/config.h b/include/mbedtls/config.h index 8b5ae9f57..3f248d5c4 100644 --- a/include/mbedtls/config.h +++ b/include/mbedtls/config.h @@ -683,8 +683,9 @@ * 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 \c MBEDTLS_ERR_ECP_IN_PROGRESS when needed, and then be called - * again later with the same arguments in order to further progress and + * 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 is useful in non-threaded environments if you want to avoid blocking diff --git a/include/mbedtls/ecdsa.h b/include/mbedtls/ecdsa.h index 710fdb9d6..d5f7985cd 100644 --- a/include/mbedtls/ecdsa.h +++ b/include/mbedtls/ecdsa.h @@ -98,7 +98,8 @@ typedef struct mbedtls_ecdsa_restart_det mbedtls_ecdsa_restart_det_ctx; */ typedef struct { - mbedtls_ecp_restart_ctx ecp; /*!< base context (admin+ecp info) */ + mbedtls_ecp_restart_ctx ecp; /*!< base context for ECP restart and + shared administrative info */ mbedtls_ecdsa_restart_ver_ctx *ver; /*!< ecdsa_verify() sub-context */ mbedtls_ecdsa_restart_sig_ctx *sig; /*!< ecdsa_sign() sub-context */ #if defined(MBEDTLS_ECDSA_DETERMINISTIC) diff --git a/include/mbedtls/ecp.h b/include/mbedtls/ecp.h index 4ac2926e7..15aee04c7 100644 --- a/include/mbedtls/ecp.h +++ b/include/mbedtls/ecp.h @@ -225,8 +225,8 @@ typedef struct * \param rs_ctx Restart context * \param ops Number of basic ops to do * - * \return 0 is doing 'ops' basic ops is still allowed, - * MBEDTLS_ERR_ECP_IN_PROGRESS otherwise. + * \return \c 0 if doing \p ops basic ops is still allowed, + * \return #MBEDTLS_ERR_ECP_IN_PROGRESS otherwise. */ int mbedtls_ecp_check_budget( const mbedtls_ecp_group *grp, mbedtls_ecp_restart_ctx *rs_ctx, @@ -338,7 +338,7 @@ mbedtls_ecp_keypair; * \brief Set the maximum number of basic operations done in a row. * * If more operations are needed to complete a computation, - * MBEDTLS_ERR_ECP_IN_PROGRESS will be returned by the + * #MBEDTLS_ERR_ECP_IN_PROGRESS will be returned by the * function performing the computation. It is then the * caller's responsibility to either call again with the same * parameters until it returns 0 or an error code; or to free @@ -352,7 +352,7 @@ mbedtls_ecp_keypair; * * This only affects functions that accept a pointer to a * \c mbedtls_ecp_restart_ctx as an argument, and only works - * if that pointer valid (in particular, not NULL). + * if that pointer is valid (in particular, not NULL). * * \param max_ops Maximum number of basic operations done in a row. * Default: 0 (unlimited). @@ -379,15 +379,15 @@ mbedtls_ecp_keypair; * P-384 682 416 320 272 248 * P-521 1364 832 640 544 496 * - * \note This setting is currently ignored by Curve25519 + * \note This setting is currently ignored by Curve25519. */ void mbedtls_ecp_set_max_ops( unsigned max_ops ); /** * \brief Check if restart is enabled (max_ops != 0) * - * \return 0 if max_ops == 0 (restart disabled) - * 1 otherwise (restart enabled) + * \return \c 0 if \c max_ops == 0 (restart disabled) + * \return \c 1 otherwise (restart enabled) */ int mbedtls_ecp_restart_enabled( void ); #endif /* MBEDTLS_ECP_RESTARTABLE */ @@ -735,7 +735,7 @@ int mbedtls_ecp_mul( mbedtls_ecp_group *grp, mbedtls_ecp_point *R, * \brief This function performs multiplication of a point by * an integer: \p R = \p m * \p P in a restartable way. * - * \c mbedtls_ecp_mul() + * \see mbedtls_ecp_mul() * * \note This function does the same as \c mbedtls_ecp_mul(), but * it can return early and restart according to the limit set @@ -749,8 +749,11 @@ int mbedtls_ecp_mul( mbedtls_ecp_group *grp, mbedtls_ecp_point *R, * \param p_rng The RNG context. * \param rs_ctx The restart context. * - * \return See \c mbedtls_ecp_mul(), or - * MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of + * \return \c 0 on success. + * \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. + * \return #MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of * operations was reached: see \c mbedtls_ecp_set_max_ops(). */ int mbedtls_ecp_mul_restartable( mbedtls_ecp_group *grp, mbedtls_ecp_point *R, @@ -787,7 +790,7 @@ int mbedtls_ecp_muladd( 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 in a - * reastartable way. + * restartable way. * * \see \c mbedtls_ecp_muladd() * @@ -863,7 +866,7 @@ int mbedtls_ecp_check_privkey( const mbedtls_ecp_group *grp, const mbedtls_mpi * * \brief This function generates a private key. * * \param grp The ECP group. - * \param d The Destination MPI (secret part). + * \param d The destination MPI (secret part). * \param f_rng The RNG function. * \param p_rng The RNG parameter. * diff --git a/include/mbedtls/pk.h b/include/mbedtls/pk.h index 37a79cca4..3b486cfe9 100644 --- a/include/mbedtls/pk.h +++ b/include/mbedtls/pk.h @@ -329,7 +329,7 @@ int mbedtls_pk_verify( mbedtls_pk_context *ctx, mbedtls_md_type_t md_alg, * \param rs_ctx Restart context (NULL to disable restart) * * \return See \c mbedtls_pk_verify(), or - * MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of + * \return #MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of * operations was reached: see \c mbedtls_ecp_set_max_ops(). */ int mbedtls_pk_verify_restartable( mbedtls_pk_context *ctx, @@ -420,7 +420,7 @@ int mbedtls_pk_sign( mbedtls_pk_context *ctx, mbedtls_md_type_t md_alg, * \param rs_ctx Restart context (NULL to disable restart) * * \return See \c mbedtls_pk_sign(), or - * MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of + * \return #MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of * operations was reached: see \c mbedtls_ecp_set_max_ops(). */ int mbedtls_pk_sign_restartable( mbedtls_pk_context *ctx, diff --git a/include/mbedtls/x509_crt.h b/include/mbedtls/x509_crt.h index 494ea99d7..961db9844 100644 --- a/include/mbedtls/x509_crt.h +++ b/include/mbedtls/x509_crt.h @@ -429,7 +429,7 @@ int mbedtls_x509_crt_verify_with_profile( mbedtls_x509_crt *crt, * \param rs_ctx restart context * * \return See \c mbedtls_crt_verify_with_profile(), or - * MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of + * \return #MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of * operations was reached: see \c mbedtls_ecp_set_max_ops(). */ int mbedtls_x509_crt_verify_restartable( mbedtls_x509_crt *crt,