Update ecdh.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".
*Removed bullets from parameter descriptions.
diff --git a/include/mbedtls/ecdh.h b/include/mbedtls/ecdh.h
index 99cfde0..70455e8 100644
--- a/include/mbedtls/ecdh.h
+++ b/include/mbedtls/ecdh.h
@@ -1,10 +1,11 @@
/**
* \file ecdh.h
*
- * \brief The Elliptic Curve Diffie-Hellman (ECDH) protocol APIs.
- *
- * ECDH is an anonymous key agreement protocol allowing two parties to
- * establish a shared secret over an insecure channel. Each party must have an
+ * \brief This file contains ECDH definitions and functions.
+ *
+ * The Elliptic Curve Diffie-Hellman (ECDH) protocol is an anonymous
+ * key agreement protocol allowing two parties to establish a shared
+ * secret over an insecure channel. Each party must have an
* elliptic-curve public–private key pair.
*
* For more information, see <em>NIST SP 800-56A Rev. 2: Recommendation for
@@ -40,14 +41,12 @@
#endif
/**
- * Defines the source of the imported EC key:
- * <ul><li>Our key.</li>
- * <li>The key of the peer.</li></ul>
+ * Defines the source of the imported EC key.
*/
typedef enum
{
- MBEDTLS_ECDH_OURS,
- MBEDTLS_ECDH_THEIRS,
+ MBEDTLS_ECDH_OURS, /**< Our key. */
+ MBEDTLS_ECDH_THEIRS, /**< The key of the peer. */
} mbedtls_ecdh_side;
/**
@@ -75,16 +74,18 @@
* implemented during the ECDH key exchange. The second core
* computation is performed by mbedtls_ecdh_compute_shared().
*
+ * \see ecp.h
+ *
* \param grp The ECP group.
* \param d The destination MPI (private key).
* \param Q The destination point (public key).
* \param f_rng The RNG function.
- * \param p_rng The RNG parameter.
+ * \param p_rng The RNG context.
*
- * \return \c 0 on success, or an \c MBEDTLS_ERR_ECP_XXX or
+ * \return \c 0 on success.
+ * \return An \c MBEDTLS_ERR_ECP_XXX or
* \c MBEDTLS_MPI_XXX error code on failure.
*
- * \see ecp.h
*/
int mbedtls_ecdh_gen_public( mbedtls_ecp_group *grp, mbedtls_mpi *d, mbedtls_ecp_point *Q,
int (*f_rng)(void *, unsigned char *, size_t),
@@ -97,21 +98,22 @@
* implemented during the ECDH key exchange. The first core
* computation is performed by mbedtls_ecdh_gen_public().
*
- * \param grp The ECP group.
- * \param z The destination MPI (shared secret).
- * \param Q The public key from another party.
- * \param d Our secret exponent (private key).
- * \param f_rng The RNG function.
- * \param p_rng The RNG parameter.
- *
- * \return \c 0 on success, or an \c MBEDTLS_ERR_ECP_XXX or
- * \c MBEDTLS_MPI_XXX error code on failure.
- *
* \see ecp.h
*
* \note If \p f_rng is not NULL, it is used to implement
* countermeasures against potential elaborate timing
* attacks. For more information, see mbedtls_ecp_mul().
+ *
+ * \param grp The ECP group.
+ * \param z The destination MPI (shared secret).
+ * \param Q The public key from another party.
+ * \param d Our secret exponent (private key).
+ * \param f_rng The RNG function.
+ * \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.
*/
int mbedtls_ecdh_compute_shared( mbedtls_ecp_group *grp, mbedtls_mpi *z,
const mbedtls_ecp_point *Q, const mbedtls_mpi *d,
@@ -139,21 +141,21 @@
* This is the first function used by a TLS server for ECDHE
* ciphersuites.
*
+ * \note This function assumes that the ECP group (grp) of the
+ * \p ctx context has already been properly set,
+ * for example, using mbedtls_ecp_group_load().
+ *
+ * \see ecp.h
+ *
* \param ctx The ECDH context.
* \param olen The number of characters written.
* \param buf The destination buffer.
* \param blen The length of the destination buffer.
* \param f_rng The RNG function.
- * \param p_rng The RNG parameter.
+ * \param p_rng The RNG context.
*
- * \note This function assumes that the ECP group (grp) of the
- * \p ctx context has already been properly set,
- * for example, using mbedtls_ecp_group_load().
- *
- * \return \c 0 on success, or an \c MBEDTLS_ERR_ECP_XXX error code
- * on failure.
- *
- * \see ecp.h
+ * \return \c 0 on success.
+ * \return An \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,
@@ -167,14 +169,15 @@
* This is the first function used by a TLS client for ECDHE
* ciphersuites.
*
+ * \see ecp.h
+ *
* \param ctx The ECDH context.
* \param buf The pointer to the start of the input buffer.
* \param end The address for one Byte past the end of the buffer.
*
- * \return \c 0 on success, or an \c MBEDTLS_ERR_ECP_XXX error code
- * on failure.
+ * \return \c 0 on success.
+ * \return An \c MBEDTLS_ERR_ECP_XXX error code on failure.
*
- * \see ecp.h
*/
int mbedtls_ecdh_read_params( mbedtls_ecdh_context *ctx,
const unsigned char **buf, const unsigned char *end );
@@ -186,16 +189,16 @@
* ServerKeyEchange for static ECDH, and imports ECDH
* parameters from the EC key information of a certificate.
*
+ * \see ecp.h
+ *
* \param ctx The ECDH context to set up.
* \param key The EC key to use.
- * \param side Defines the source of the key:
- * <ul><li>1: Our key.</li>
- <li>0: The key of the peer.</li></ul>
+ * \param side Defines the source of the key: 1: Our key, or
+ * 0: The key of the peer.
*
- * \return \c 0 on success, or an \c MBEDTLS_ERR_ECP_XXX error code
- * on failure.
+ * \return \c 0 on success.
+ * \return An \c MBEDTLS_ERR_ECP_XXX error code on failure.
*
- * \see ecp.h
*/
int mbedtls_ecdh_get_params( mbedtls_ecdh_context *ctx, const mbedtls_ecp_keypair *key,
mbedtls_ecdh_side side );
@@ -207,17 +210,17 @@
* This is the second function used by a TLS client for ECDH(E)
* ciphersuites.
*
+ * \see ecp.h
+ *
* \param ctx The ECDH context.
* \param olen The number of Bytes written.
* \param buf The destination buffer.
* \param blen The size of the destination buffer.
* \param f_rng The RNG function.
- * \param p_rng The RNG parameter.
+ * \param p_rng The RNG context.
*
- * \return \c 0 on success, or an \c MBEDTLS_ERR_ECP_XXX error code
- * on failure.
- *
- * \see ecp.h
+ * \return \c 0 on success.
+ * \return An \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,
@@ -231,14 +234,14 @@
* This is the second function used by a TLS server for ECDH(E)
* ciphersuites.
*
+ * \see ecp.h
+ *
* \param ctx The ECDH context.
* \param buf The start of the input buffer.
* \param blen The length of the input buffer.
*
- * \return \c 0 on success, or an \c MBEDTLS_ERR_ECP_XXX error code
- * on failure.
- *
- * \see ecp.h
+ * \return \c 0 on success.
+ * \return An \c MBEDTLS_ERR_ECP_XXX error code on failure.
*/
int mbedtls_ecdh_read_public( mbedtls_ecdh_context *ctx,
const unsigned char *buf, size_t blen );
@@ -249,21 +252,21 @@
* This is the last function used by both TLS client
* and servers.
*
+ * \note If \p f_rng is not NULL, it is used to implement
+ * countermeasures against potential elaborate timing
+ * attacks. For more information, see mbedtls_ecp_mul().
+ *
+ * \see ecp.h
+ *
* \param ctx The ECDH context.
* \param olen The number of Bytes written.
* \param buf The destination buffer.
* \param blen The length of the destination buffer.
* \param f_rng The RNG function.
- * \param p_rng The RNG parameter.
+ * \param p_rng The RNG context.
*
- * \return \c 0 on success, or an \c MBEDTLS_ERR_ECP_XXX error code
- * on failure.
- *
- * \see ecp.h
- *
- * \note If \p f_rng is not NULL, it is used to implement
- * countermeasures against potential elaborate timing
- * attacks. For more information, see mbedtls_ecp_mul().
+ * \return \c 0 on success.
+ * \return An \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,