yuzu-emu/mbedtls
1
0
Fork 0
mirror of https://github.com/yuzu-emu/mbedtls.git synced 2024-11-23 04:25:44 +01:00
Code Issues Packages Projects Releases Wiki Activity

Update dhm.h

Browse Source 
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.
This commit is contained in:
Rose Zadik 2018-04-17 11:00:40 +01:00 committed by GitHub
parent 4ca9a45756
commit f763f2bbc1
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 57 additions and 51 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

108
include/mbedtls/dhm.h
View File

@ -1,7 +1,12 @@
/** /**
* \file dhm.h * \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
* <em>RFC-2631: Diffie-Hellman Key Agreement Method</em> and
* <em>Public-Key Cryptography Standards (PKCS) #3: Diffie
* Hellman Key Agreement Standard</em>.
* *
* <em>RFC-3526: More Modular Exponential (MODP) Diffie-Hellman groups for * <em>RFC-3526: More Modular Exponential (MODP) Diffie-Hellman groups for
* Internet Key Exchange (IKE)</em> defines a number of standardized * Internet Key Exchange (IKE)</em> defines a number of standardized
@ -125,8 +130,8 @@ void mbedtls_dhm_init( mbedtls_dhm_context *ctx );
* failures. * failures.
* \param end The end of the input buffer. * \param end The end of the input buffer.
* *
* \return \c 0 on success, or an \c MBEDTLS_ERR_DHM_XXX error code * \return \c 0 on success.
* on failure. * \return An \c MBEDTLS_ERR_DHM_XXX error code on failure.
*/ */
int mbedtls_dhm_read_params( mbedtls_dhm_context *ctx, int mbedtls_dhm_read_params( mbedtls_dhm_context *ctx,
unsigned char **p, 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 * \brief This function sets up and writes the ServerKeyExchange
* parameters. * 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 * \note The destination buffer must be large enough to hold
* the reduced binary presentation of the modulus, the generator * the reduced binary presentation of the modulus, the generator
* and the public key, each wrapped with a 2-byte length field. * 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_dhm_set_group() below in conjunction with
* mbedtls_mpi_read_binary() and mbedtls_mpi_read_string(). * mbedtls_mpi_read_binary() and mbedtls_mpi_read_string().
* *
* \return \c 0 on success, or an \c MBEDTLS_ERR_DHM_XXX error code * \param ctx The DHM context.
* on failure. * \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, int mbedtls_dhm_make_params( mbedtls_dhm_context *ctx, int x_size,
unsigned char *output, size_t *olen, 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 ); 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 ctx The DHM context.
* \param P The MPI holding DHM prime modulus. * \param P The MPI holding the DHM prime modulus.
* \param G The MPI holding DHM generator. * \param G The MPI holding the DHM generator.
* *
* \note This function can be used to set P, G * \return \c 0 if successful.
* in preparation for \c mbedtls_dhm_make_params. * \return An \c MBEDTLS_ERR_DHM_XXX error code on failure.
*
* \return \c 0 if successful, or an \c MBEDTLS_ERR_DHM_XXX error code
* on failure.
*/ */
int mbedtls_dhm_set_group( mbedtls_dhm_context *ctx, int mbedtls_dhm_set_group( mbedtls_dhm_context *ctx,
const mbedtls_mpi *P, const mbedtls_mpi *P,
const mbedtls_mpi *G ); 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 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. * \param ilen The size of the input buffer.
* *
* \return \c 0 on success, or an \c MBEDTLS_ERR_DHM_XXX error code * \return \c 0 on success.
* on failure. * \return An \c MBEDTLS_ERR_DHM_XXX error code on failure.
*/ */
int mbedtls_dhm_read_public( mbedtls_dhm_context *ctx, int mbedtls_dhm_read_public( mbedtls_dhm_context *ctx,
const unsigned char *input, size_t ilen ); 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. * 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 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 output The destination buffer.
* \param olen The length of the destination buffer. Must be at least * \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 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 * \return \c 0 on success.
* so as to contain a big-endian presentation of G^X mod P. * \return An \c MBEDTLS_ERR_DHM_XXX error code on failure.
* 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.
*/ */
int mbedtls_dhm_make_public( mbedtls_dhm_context *ctx, int x_size, int mbedtls_dhm_make_public( mbedtls_dhm_context *ctx, int x_size,
unsigned char *output, size_t olen, 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 * \brief This function derives and exports the shared secret
* \c (G^Y)^X mod \c P. * \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 ctx The DHM context.
* \param output The destination buffer. * \param output The destination buffer.
* \param output_size The size of the destination buffer. Must be at least * \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 olen On exit, holds the actual number of Bytes written.
* \param f_rng The RNG function, for blinding purposes. * \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 * \return \c 0 on success.
* on failure. * \return 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.
*/ */
int mbedtls_dhm_calc_secret( mbedtls_dhm_context *ctx, int mbedtls_dhm_calc_secret( mbedtls_dhm_context *ctx,
unsigned char *output, size_t output_size, size_t *olen, 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 ); 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. * \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 * \param dhminlen The size of the buffer, including the terminating null
* Byte for PEM data. * Byte for PEM data.
* *
* \return \c 0 on success, or a specific DHM or PEM error code * \return \c 0 on success.
* on failure. * \return A specific DHM or PEM error code on failure.
*/ */
int mbedtls_dhm_parse_dhm( mbedtls_dhm_context *dhm, const unsigned char *dhmin, int mbedtls_dhm_parse_dhm( mbedtls_dhm_context *dhm, const unsigned char *dhmin,
size_t dhminlen ); 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 dhm The DHM context to load the parameters to.
* \param path The filename to read the DHM parameters from. * \param path The filename to read the DHM parameters from.
* *
* \return \c 0 on success, or a specific DHM or PEM error code * \return \c 0 on success.
* on failure. * \return A specific DHM or PEM error code on failure.
*/ */
int mbedtls_dhm_parse_dhmfile( mbedtls_dhm_context *dhm, const char *path ); int mbedtls_dhm_parse_dhmfile( mbedtls_dhm_context *dhm, const char *path );
#endif /* MBEDTLS_FS_IO */ #endif /* MBEDTLS_FS_IO */
@ -297,7 +302,8 @@ extern "C" {
/** /**
* \brief The DMH checkup routine. * \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 ); int mbedtls_dhm_self_test( int verbose );