From f763f2bbc1c92416d12874fd5f14969279036cb0 Mon Sep 17 00:00:00 2001 From: Rose Zadik Date: Tue, 17 Apr 2018 11:00:40 +0100 Subject: [PATCH] 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 );