From 8c9c794518d27ef538308493666557a4807b7f74 Mon Sep 17 00:00:00 2001 From: Rose Zadik Date: Tue, 27 Mar 2018 11:52:58 +0100 Subject: [PATCH 1/2] Update md.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. --- include/mbedtls/md.h | 99 ++++++++++++++++++++++++-------------------- 1 file changed, 54 insertions(+), 45 deletions(-) diff --git a/include/mbedtls/md.h b/include/mbedtls/md.h index 06538c382..df2ab630b 100644 --- a/include/mbedtls/md.h +++ b/include/mbedtls/md.h @@ -1,7 +1,7 @@ /** * \file md.h * - * \brief The generic message-digest wrapper. + * \brief This file contains the generic message-digest wrapper. * * \author Adriaan de Jong */ @@ -46,7 +46,7 @@ extern "C" { #endif /** - * \brief Enumeration of supported message digests + * \brief Supported message digests. * * \warning MD2, MD4, MD5 and SHA-1 are considered weak message digests and * their use constitutes a security risk. We recommend considering @@ -54,16 +54,16 @@ extern "C" { * */ typedef enum { - MBEDTLS_MD_NONE=0, - MBEDTLS_MD_MD2, - MBEDTLS_MD_MD4, - MBEDTLS_MD_MD5, - MBEDTLS_MD_SHA1, - MBEDTLS_MD_SHA224, - MBEDTLS_MD_SHA256, - MBEDTLS_MD_SHA384, - MBEDTLS_MD_SHA512, - MBEDTLS_MD_RIPEMD160, + MBEDTLS_MD_NONE=0, /**< None. */ + MBEDTLS_MD_MD2, /**< The MD2 message digest. */ + MBEDTLS_MD_MD4, /**< The MD4 message digest. */ + MBEDTLS_MD_MD5, /**< The MD5 message digest. */ + MBEDTLS_MD_SHA1, /**< The SHA-1 message digest. */ + MBEDTLS_MD_SHA224, /**< The SHA-224 message digest. */ + MBEDTLS_MD_SHA256, /**< The SHA-256 message digest. */ + MBEDTLS_MD_SHA384, /**< The SHA-384 message digest. */ + MBEDTLS_MD_SHA512, /**< The SHA-512 message digest. */ + MBEDTLS_MD_RIPEMD160, /**< The RIPEMD-160 message digest. */ } mbedtls_md_type_t; #if defined(MBEDTLS_SHA512_C) @@ -119,8 +119,8 @@ const mbedtls_md_info_t *mbedtls_md_info_from_string( const char *md_name ); * * \param md_type The type of digest to search for. * - * \return The message-digest information associated with \p md_type, - * or NULL if not found. + * \return The message-digest information associated with \p md_type. + * \return NULL if the associated message-digest information is not found. */ const mbedtls_md_info_t *mbedtls_md_info_from_type( mbedtls_md_type_t md_type ); @@ -168,9 +168,9 @@ void mbedtls_md_free( mbedtls_md_context_t *ctx ); * \param md_info The information structure of the message-digest algorithm * to use. * - * \returns \c 0 on success, - * #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter failure, - * #MBEDTLS_ERR_MD_ALLOC_FAILED memory allocation failure. + * \returns \c 0 on success. + * \returns #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter failure. + * \returns #MBEDTLS_ERR_MD_ALLOC_FAILED memory allocation failure. */ int mbedtls_md_init_ctx( mbedtls_md_context_t *ctx, const mbedtls_md_info_t *md_info ) MBEDTLS_DEPRECATED; #undef MBEDTLS_DEPRECATED @@ -187,12 +187,12 @@ int mbedtls_md_init_ctx( mbedtls_md_context_t *ctx, const mbedtls_md_info_t *md_ * \param ctx The context to set up. * \param md_info The information structure of the message-digest algorithm * to use. - * \param hmac + * \param hmac Defines if HMAC is used. 0: HMAC is not used (saves some memory), + * or non-zero: HMAC is used with this context. * - * \returns \c 0 on success, - * #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter failure, or - * #MBEDTLS_ERR_MD_ALLOC_FAILED on memory allocation failure. + * \returns \c 0 on success. + * \returns #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter failure. + * \returns #MBEDTLS_ERR_MD_ALLOC_FAILED on memory allocation failure. */ int mbedtls_md_setup( mbedtls_md_context_t *ctx, const mbedtls_md_info_t *md_info, int hmac ); @@ -212,8 +212,8 @@ int mbedtls_md_setup( mbedtls_md_context_t *ctx, const mbedtls_md_info_t *md_inf * \param dst The destination context. * \param src The context to be cloned. * - * \return \c 0 on success, - * #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter failure. + * \return \c 0 on success. + * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter failure. */ int mbedtls_md_clone( mbedtls_md_context_t *dst, const mbedtls_md_context_t *src ); @@ -260,8 +260,9 @@ const char *mbedtls_md_get_name( const mbedtls_md_info_t *md_info ); * * \param ctx The generic message-digest context. * - * \returns \c 0 on success, #MBEDTLS_ERR_MD_BAD_INPUT_DATA if - * parameter verification fails. + * \returns \c 0 on success. + * \returns #MBEDTLS_ERR_MD_BAD_INPUT_DATA if parameter verification + * fails. */ int mbedtls_md_starts( mbedtls_md_context_t *ctx ); @@ -277,8 +278,9 @@ int mbedtls_md_starts( mbedtls_md_context_t *ctx ); * \param input The buffer holding the input data. * \param ilen The length of the input data. * - * \returns \c 0 on success, #MBEDTLS_ERR_MD_BAD_INPUT_DATA if - * parameter verification fails. + * \returns \c 0 on success. + * \returns #MBEDTLS_ERR_MD_BAD_INPUT_DATA if parameter verification + * fails. */ int mbedtls_md_update( mbedtls_md_context_t *ctx, const unsigned char *input, size_t ilen ); @@ -296,8 +298,9 @@ int mbedtls_md_update( mbedtls_md_context_t *ctx, const unsigned char *input, si * \param ctx The generic message-digest context. * \param output The buffer for the generic message-digest checksum result. * - * \returns \c 0 on success, or #MBEDTLS_ERR_MD_BAD_INPUT_DATA if - * parameter verification fails. + * \returns \c 0 on success. + * \returns #MBEDTLS_ERR_MD_BAD_INPUT_DATA if parameter verification + * fails. */ int mbedtls_md_finish( mbedtls_md_context_t *ctx, unsigned char *output ); @@ -315,8 +318,9 @@ int mbedtls_md_finish( mbedtls_md_context_t *ctx, unsigned char *output ); * \param ilen The length of the input data. * \param output The generic message-digest checksum result. * - * \returns \c 0 on success, or #MBEDTLS_ERR_MD_BAD_INPUT_DATA if - * parameter verification fails. + * \returns \c 0 on success. + * \returns #MBEDTLS_ERR_MD_BAD_INPUT_DATA if parameter verification + * fails. */ int mbedtls_md( const mbedtls_md_info_t *md_info, const unsigned char *input, size_t ilen, unsigned char *output ); @@ -334,9 +338,9 @@ int mbedtls_md( const mbedtls_md_info_t *md_info, const unsigned char *input, si * \param path The input file name. * \param output The generic message-digest checksum result. * - * \return \c 0 on success, - * #MBEDTLS_ERR_MD_FILE_IO_ERROR if file input failed, or - * #MBEDTLS_ERR_MD_BAD_INPUT_DATA if \p md_info was NULL. + * \return \c 0 on success. + * \returns #MBEDTLS_ERR_MD_FILE_IO_ERROR if file input failed. + * \returns #MBEDTLS_ERR_MD_BAD_INPUT_DATA if \p md_info was NULL. */ int mbedtls_md_file( const mbedtls_md_info_t *md_info, const char *path, unsigned char *output ); @@ -356,8 +360,9 @@ int mbedtls_md_file( const mbedtls_md_info_t *md_info, const char *path, * \param key The HMAC secret key. * \param keylen The length of the HMAC key in Bytes. * - * \returns \c 0 on success, or #MBEDTLS_ERR_MD_BAD_INPUT_DATA if - * parameter verification fails. + * \returns \c 0 on success. + * \returns #MBEDTLS_ERR_MD_BAD_INPUT_DATA if parameter verification + * fails. */ int mbedtls_md_hmac_starts( mbedtls_md_context_t *ctx, const unsigned char *key, size_t keylen ); @@ -377,8 +382,9 @@ int mbedtls_md_hmac_starts( mbedtls_md_context_t *ctx, const unsigned char *key, * \param input The buffer holding the input data. * \param ilen The length of the input data. * - * \returns \c 0 on success, or #MBEDTLS_ERR_MD_BAD_INPUT_DATA if - * parameter verification fails. + * \returns \c 0 on success. + * \returns #MBEDTLS_ERR_MD_BAD_INPUT_DATA if parameter verification + * fails. */ int mbedtls_md_hmac_update( mbedtls_md_context_t *ctx, const unsigned char *input, size_t ilen ); @@ -397,8 +403,9 @@ int mbedtls_md_hmac_update( mbedtls_md_context_t *ctx, const unsigned char *inpu * context. * \param output The generic HMAC checksum result. * - * \returns \c 0 on success, or #MBEDTLS_ERR_MD_BAD_INPUT_DATA if - * parameter verification fails. + * \returns \c 0 on success. + * \returns #MBEDTLS_ERR_MD_BAD_INPUT_DATA if parameter verification + * fails. */ int mbedtls_md_hmac_finish( mbedtls_md_context_t *ctx, unsigned char *output); @@ -413,8 +420,9 @@ int mbedtls_md_hmac_finish( mbedtls_md_context_t *ctx, unsigned char *output); * \param ctx The message digest context containing an embedded HMAC * context. * - * \returns \c 0 on success, or #MBEDTLS_ERR_MD_BAD_INPUT_DATA if - * parameter verification fails. + * \returns \c 0 on success. + * \returns #MBEDTLS_ERR_MD_BAD_INPUT_DATA if parameter verification + * fails. */ int mbedtls_md_hmac_reset( mbedtls_md_context_t *ctx ); @@ -436,8 +444,9 @@ int mbedtls_md_hmac_reset( mbedtls_md_context_t *ctx ); * \param ilen The length of the input data. * \param output The generic HMAC result. * - * \returns \c 0 on success, or #MBEDTLS_ERR_MD_BAD_INPUT_DATA if - * parameter verification fails. + * \returns \c 0 on success. + * \returns #MBEDTLS_ERR_MD_BAD_INPUT_DATA if parameter verification + * fails. */ int mbedtls_md_hmac( const mbedtls_md_info_t *md_info, const unsigned char *key, size_t keylen, const unsigned char *input, size_t ilen, From f3e4736131f1ee9c4e37d9924c1690dd7d0eb222 Mon Sep 17 00:00:00 2001 From: Rose Zadik Date: Mon, 16 Apr 2018 16:31:16 +0100 Subject: [PATCH 2/2] Update md.h Changes based on review comments --- include/mbedtls/md.h | 97 +++++++++++++++++++++++--------------------- 1 file changed, 50 insertions(+), 47 deletions(-) diff --git a/include/mbedtls/md.h b/include/mbedtls/md.h index df2ab630b..6b6f5c53d 100644 --- a/include/mbedtls/md.h +++ b/include/mbedtls/md.h @@ -54,15 +54,15 @@ extern "C" { * */ typedef enum { - MBEDTLS_MD_NONE=0, /**< None. */ - MBEDTLS_MD_MD2, /**< The MD2 message digest. */ - MBEDTLS_MD_MD4, /**< The MD4 message digest. */ - MBEDTLS_MD_MD5, /**< The MD5 message digest. */ - MBEDTLS_MD_SHA1, /**< The SHA-1 message digest. */ - MBEDTLS_MD_SHA224, /**< The SHA-224 message digest. */ - MBEDTLS_MD_SHA256, /**< The SHA-256 message digest. */ - MBEDTLS_MD_SHA384, /**< The SHA-384 message digest. */ - MBEDTLS_MD_SHA512, /**< The SHA-512 message digest. */ + MBEDTLS_MD_NONE=0, /**< None. */ + MBEDTLS_MD_MD2, /**< The MD2 message digest. */ + MBEDTLS_MD_MD4, /**< The MD4 message digest. */ + MBEDTLS_MD_MD5, /**< The MD5 message digest. */ + MBEDTLS_MD_SHA1, /**< The SHA-1 message digest. */ + MBEDTLS_MD_SHA224, /**< The SHA-224 message digest. */ + MBEDTLS_MD_SHA256, /**< The SHA-256 message digest. */ + MBEDTLS_MD_SHA384, /**< The SHA-384 message digest. */ + MBEDTLS_MD_SHA512, /**< The SHA-512 message digest. */ MBEDTLS_MD_RIPEMD160, /**< The RIPEMD-160 message digest. */ } mbedtls_md_type_t; @@ -108,8 +108,8 @@ const int *mbedtls_md_list( void ); * * \param md_name The name of the digest to search for. * - * \return The message-digest information associated with \p md_name, - * or NULL if not found. + * \return The message-digest information associated with \p md_name. + * \return NULL if the associated message-digest information is not found. */ const mbedtls_md_info_t *mbedtls_md_info_from_string( const char *md_name ); @@ -168,9 +168,10 @@ void mbedtls_md_free( mbedtls_md_context_t *ctx ); * \param md_info The information structure of the message-digest algorithm * to use. * - * \returns \c 0 on success. - * \returns #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter failure. - * \returns #MBEDTLS_ERR_MD_ALLOC_FAILED memory allocation failure. + * \return \c 0 on success. + * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification + * failure. + * \return #MBEDTLS_ERR_MD_ALLOC_FAILED on memory-allocation failure. */ int mbedtls_md_init_ctx( mbedtls_md_context_t *ctx, const mbedtls_md_info_t *md_info ) MBEDTLS_DEPRECATED; #undef MBEDTLS_DEPRECATED @@ -190,9 +191,10 @@ int mbedtls_md_init_ctx( mbedtls_md_context_t *ctx, const mbedtls_md_info_t *md_ * \param hmac Defines if HMAC is used. 0: HMAC is not used (saves some memory), * or non-zero: HMAC is used with this context. * - * \returns \c 0 on success. - * \returns #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter failure. - * \returns #MBEDTLS_ERR_MD_ALLOC_FAILED on memory allocation failure. + * \return \c 0 on success. + * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification + * failure. + * \return #MBEDTLS_ERR_MD_ALLOC_FAILED on memory-allocation failure. */ int mbedtls_md_setup( mbedtls_md_context_t *ctx, const mbedtls_md_info_t *md_info, int hmac ); @@ -213,7 +215,7 @@ int mbedtls_md_setup( mbedtls_md_context_t *ctx, const mbedtls_md_info_t *md_inf * \param src The context to be cloned. * * \return \c 0 on success. - * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter failure. + * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification failure. */ int mbedtls_md_clone( mbedtls_md_context_t *dst, const mbedtls_md_context_t *src ); @@ -260,9 +262,9 @@ const char *mbedtls_md_get_name( const mbedtls_md_info_t *md_info ); * * \param ctx The generic message-digest context. * - * \returns \c 0 on success. - * \returns #MBEDTLS_ERR_MD_BAD_INPUT_DATA if parameter verification - * fails. + * \return \c 0 on success. + * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification + * failure. */ int mbedtls_md_starts( mbedtls_md_context_t *ctx ); @@ -278,9 +280,9 @@ int mbedtls_md_starts( mbedtls_md_context_t *ctx ); * \param input The buffer holding the input data. * \param ilen The length of the input data. * - * \returns \c 0 on success. - * \returns #MBEDTLS_ERR_MD_BAD_INPUT_DATA if parameter verification - * fails. + * \return \c 0 on success. + * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification + * failure. */ int mbedtls_md_update( mbedtls_md_context_t *ctx, const unsigned char *input, size_t ilen ); @@ -298,9 +300,9 @@ int mbedtls_md_update( mbedtls_md_context_t *ctx, const unsigned char *input, si * \param ctx The generic message-digest context. * \param output The buffer for the generic message-digest checksum result. * - * \returns \c 0 on success. - * \returns #MBEDTLS_ERR_MD_BAD_INPUT_DATA if parameter verification - * fails. + * \return \c 0 on success. + * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification + * failure. */ int mbedtls_md_finish( mbedtls_md_context_t *ctx, unsigned char *output ); @@ -318,9 +320,9 @@ int mbedtls_md_finish( mbedtls_md_context_t *ctx, unsigned char *output ); * \param ilen The length of the input data. * \param output The generic message-digest checksum result. * - * \returns \c 0 on success. - * \returns #MBEDTLS_ERR_MD_BAD_INPUT_DATA if parameter verification - * fails. + * \return \c 0 on success. + * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification + * failure. */ int mbedtls_md( const mbedtls_md_info_t *md_info, const unsigned char *input, size_t ilen, unsigned char *output ); @@ -339,8 +341,9 @@ int mbedtls_md( const mbedtls_md_info_t *md_info, const unsigned char *input, si * \param output The generic message-digest checksum result. * * \return \c 0 on success. - * \returns #MBEDTLS_ERR_MD_FILE_IO_ERROR if file input failed. - * \returns #MBEDTLS_ERR_MD_BAD_INPUT_DATA if \p md_info was NULL. + * \return #MBEDTLS_ERR_MD_FILE_IO_ERROR on an I/O error accessing + * the file pointed by \p path. + * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA if \p md_info was NULL. */ int mbedtls_md_file( const mbedtls_md_info_t *md_info, const char *path, unsigned char *output ); @@ -360,9 +363,9 @@ int mbedtls_md_file( const mbedtls_md_info_t *md_info, const char *path, * \param key The HMAC secret key. * \param keylen The length of the HMAC key in Bytes. * - * \returns \c 0 on success. - * \returns #MBEDTLS_ERR_MD_BAD_INPUT_DATA if parameter verification - * fails. + * \return \c 0 on success. + * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification + * failure. */ int mbedtls_md_hmac_starts( mbedtls_md_context_t *ctx, const unsigned char *key, size_t keylen ); @@ -382,9 +385,9 @@ int mbedtls_md_hmac_starts( mbedtls_md_context_t *ctx, const unsigned char *key, * \param input The buffer holding the input data. * \param ilen The length of the input data. * - * \returns \c 0 on success. - * \returns #MBEDTLS_ERR_MD_BAD_INPUT_DATA if parameter verification - * fails. + * \return \c 0 on success. + * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification + * failure. */ int mbedtls_md_hmac_update( mbedtls_md_context_t *ctx, const unsigned char *input, size_t ilen ); @@ -403,9 +406,9 @@ int mbedtls_md_hmac_update( mbedtls_md_context_t *ctx, const unsigned char *inpu * context. * \param output The generic HMAC checksum result. * - * \returns \c 0 on success. - * \returns #MBEDTLS_ERR_MD_BAD_INPUT_DATA if parameter verification - * fails. + * \return \c 0 on success. + * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification + * failure. */ int mbedtls_md_hmac_finish( mbedtls_md_context_t *ctx, unsigned char *output); @@ -420,9 +423,9 @@ int mbedtls_md_hmac_finish( mbedtls_md_context_t *ctx, unsigned char *output); * \param ctx The message digest context containing an embedded HMAC * context. * - * \returns \c 0 on success. - * \returns #MBEDTLS_ERR_MD_BAD_INPUT_DATA if parameter verification - * fails. + * \return \c 0 on success. + * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification + * failure. */ int mbedtls_md_hmac_reset( mbedtls_md_context_t *ctx ); @@ -444,9 +447,9 @@ int mbedtls_md_hmac_reset( mbedtls_md_context_t *ctx ); * \param ilen The length of the input data. * \param output The generic HMAC result. * - * \returns \c 0 on success. - * \returns #MBEDTLS_ERR_MD_BAD_INPUT_DATA if parameter verification - * fails. + * \return \c 0 on success. + * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification + * failure. */ int mbedtls_md_hmac( const mbedtls_md_info_t *md_info, const unsigned char *key, size_t keylen, const unsigned char *input, size_t ilen,