From 8274142e45bb14a116a55f11388c099c3981b91f Mon Sep 17 00:00:00 2001 From: Rose Zadik Date: Tue, 27 Mar 2018 12:49:48 +0100 Subject: [PATCH 1/3] Update sha1.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. *Applied previous function documentation improvements to depracated functions. --- include/mbedtls/sha1.h | 140 ++++++++++++++++++++++------------------- 1 file changed, 75 insertions(+), 65 deletions(-) diff --git a/include/mbedtls/sha1.h b/include/mbedtls/sha1.h index 05540cde1..4a43c0101 100644 --- a/include/mbedtls/sha1.h +++ b/include/mbedtls/sha1.h @@ -1,7 +1,10 @@ /** * \file sha1.h * - * \brief The SHA-1 cryptographic hash function. + * \brief This file contains SHA-1 definitions and functions. + * + * The Secure Hash Algorithm 1 (SHA-1) cryptographic hash function is defined in + * FIPS 180-4: Secure Hash Standard (SHS). * * \warning SHA-1 is considered a weak message digest and its use constitutes * a security risk. We recommend considering stronger message @@ -66,37 +69,37 @@ mbedtls_sha1_context; /** * \brief This function initializes a SHA-1 context. * - * \param ctx The SHA-1 context to initialize. - * * \warning SHA-1 is considered a weak message digest and its use * constitutes a security risk. We recommend considering * stronger message digests instead. * + * \param ctx The SHA-1 context to initialize. + * */ void mbedtls_sha1_init( mbedtls_sha1_context *ctx ); /** * \brief This function clears a SHA-1 context. * - * \param ctx The SHA-1 context to clear. - * * \warning SHA-1 is considered a weak message digest and its use * constitutes a security risk. We recommend considering * stronger message digests instead. * + * \param ctx The SHA-1 context to clear. + * */ void mbedtls_sha1_free( mbedtls_sha1_context *ctx ); /** * \brief This function clones the state of a SHA-1 context. * - * \param dst The destination context. - * \param src The context to clone. - * * \warning SHA-1 is considered a weak message digest and its use * constitutes a security risk. We recommend considering * stronger message digests instead. * + * \param dst The destination context. + * \param src The context to clone. + * */ void mbedtls_sha1_clone( mbedtls_sha1_context *dst, const mbedtls_sha1_context *src ); @@ -104,14 +107,14 @@ void mbedtls_sha1_clone( mbedtls_sha1_context *dst, /** * \brief This function starts a SHA-1 checksum calculation. * - * \param ctx The context to initialize. - * - * \return \c 0 if successful - * * \warning SHA-1 is considered a weak message digest and its use * constitutes a security risk. We recommend considering * stronger message digests instead. * + * \param ctx The context to initialize. + * + * \return \c 0 on success. + * */ int mbedtls_sha1_starts_ret( mbedtls_sha1_context *ctx ); @@ -119,16 +122,15 @@ int mbedtls_sha1_starts_ret( mbedtls_sha1_context *ctx ); * \brief This function feeds an input buffer into an ongoing SHA-1 * checksum calculation. * - * \param ctx The SHA-1 context. - * \param input The buffer holding the input data. - * \param ilen The length of the input data. - * - * \return \c 0 if successful - * * \warning SHA-1 is considered a weak message digest and its use * constitutes a security risk. We recommend considering * stronger message digests instead. * + * \param ctx The SHA-1 context. + * \param input The buffer holding the input data. + * \param ilen The length of the input data. + * + * \return \c 0 on success. */ int mbedtls_sha1_update_ret( mbedtls_sha1_context *ctx, const unsigned char *input, @@ -138,31 +140,30 @@ int mbedtls_sha1_update_ret( mbedtls_sha1_context *ctx, * \brief This function finishes the SHA-1 operation, and writes * the result to the output buffer. * - * \param ctx The SHA-1 context. - * \param output The SHA-1 checksum result. - * - * \return \c 0 if successful - * * \warning SHA-1 is considered a weak message digest and its use * constitutes a security risk. We recommend considering * stronger message digests instead. * + * \param ctx The SHA-1 context. + * \param output The SHA-1 checksum result. + * + * \return \c 0 on success. */ int mbedtls_sha1_finish_ret( mbedtls_sha1_context *ctx, unsigned char output[20] ); /** - * \brief SHA-1 process data block (internal use only) - * - * \param ctx SHA-1 context - * \param data The data block being processed. - * - * \return \c 0 if successful + * \brief SHA-1 process data block (internal use only). * * \warning SHA-1 is considered a weak message digest and its use * constitutes a security risk. We recommend considering * stronger message digests instead. * + * \param ctx The SHA-1 context. + * \param data The data block being processed. + * + * \return \c 0 on success. + * */ int mbedtls_internal_sha1_process( mbedtls_sha1_context *ctx, const unsigned char data[64] ); @@ -174,65 +175,67 @@ int mbedtls_internal_sha1_process( mbedtls_sha1_context *ctx, #define MBEDTLS_DEPRECATED #endif /** - * \brief SHA-1 context setup - * - * \deprecated Superseded by mbedtls_sha1_starts_ret() in 2.7.0 - * - * \param ctx The SHA-1 context to be initialized. + * \brief This function starts a SHA-1 checksum calculation. * * \warning SHA-1 is considered a weak message digest and its use * constitutes a security risk. We recommend considering * stronger message digests instead. * + * \deprecated Superseded by mbedtls_sha1_starts_ret() in 2.7.0. + * + * \param ctx The context to initialize. + * */ MBEDTLS_DEPRECATED void mbedtls_sha1_starts( mbedtls_sha1_context *ctx ); /** - * \brief SHA-1 process buffer - * - * \deprecated Superseded by mbedtls_sha1_update_ret() in 2.7.0 - * - * \param ctx The SHA-1 context. - * \param input The buffer holding the input data. - * \param ilen The length of the input data. + * \brief This function feeds an input buffer into an ongoing SHA-1 + * checksum calculation. * * \warning SHA-1 is considered a weak message digest and its use * constitutes a security risk. We recommend considering * stronger message digests instead. * + * \deprecated Superseded by mbedtls_sha1_update_ret() in 2.7.0. + * + * \param ctx The SHA-1 context. + * \param input The buffer holding the input data. + * \param ilen The length of the input data. + * */ MBEDTLS_DEPRECATED void mbedtls_sha1_update( mbedtls_sha1_context *ctx, const unsigned char *input, size_t ilen ); /** - * \brief SHA-1 final digest - * - * \deprecated Superseded by mbedtls_sha1_finish_ret() in 2.7.0 - * - * \param ctx The SHA-1 context. - * \param output The SHA-1 checksum result. + * \brief This function finishes the SHA-1 operation, and writes + * the result to the output buffer. * * \warning SHA-1 is considered a weak message digest and its use * constitutes a security risk. We recommend considering * stronger message digests instead. * + * \deprecated Superseded by mbedtls_sha1_finish_ret() in 2.7.0. + * + * \param ctx The SHA-1 context. + * \param output The SHA-1 checksum result. + * */ MBEDTLS_DEPRECATED void mbedtls_sha1_finish( mbedtls_sha1_context *ctx, unsigned char output[20] ); /** - * \brief SHA-1 process data block (internal use only) - * - * \deprecated Superseded by mbedtls_internal_sha1_process() in 2.7.0 - * - * \param ctx The SHA-1 context. - * \param data The data block being processed. + * \brief SHA-1 process data block (internal use only). * * \warning SHA-1 is considered a weak message digest and its use * constitutes a security risk. We recommend considering * stronger message digests instead. * + * \deprecated Superseded by mbedtls_internal_sha1_process() in 2.7.0. + * + * \param ctx The SHA-1 context. + * \param data The data block being processed. + * */ MBEDTLS_DEPRECATED void mbedtls_sha1_process( mbedtls_sha1_context *ctx, const unsigned char data[64] ); @@ -261,15 +264,15 @@ extern "C" { * The SHA-1 result is calculated as * output = SHA-1(input buffer). * + * \warning SHA-1 is considered a weak message digest and its use + * constitutes a security risk. We recommend considering + * stronger message digests instead. + * * \param input The buffer holding the input data. * \param ilen The length of the input data. * \param output The SHA-1 checksum result. * - * \return \c 0 if successful - * - * \warning SHA-1 is considered a weak message digest and its use - * constitutes a security risk. We recommend considering - * stronger message digests instead. + * \return \c 0 on success. * */ int mbedtls_sha1_ret( const unsigned char *input, @@ -283,7 +286,17 @@ int mbedtls_sha1_ret( const unsigned char *input, #define MBEDTLS_DEPRECATED #endif /** - * \brief Output = SHA-1( input buffer ) +* \brief This function calculates the SHA-1 checksum of a buffer. + * + * The function allocates the context, performs the + * calculation, and frees the context. + * + * The SHA-1 result is calculated as + * output = SHA-1(input buffer). + * + * \warning SHA-1 is considered a weak message digest and its use + * constitutes a security risk. We recommend considering + * stronger message digests instead. * * \deprecated Superseded by mbedtls_sha1_ret() in 2.7.0 * @@ -291,10 +304,6 @@ int mbedtls_sha1_ret( const unsigned char *input, * \param ilen The length of the input data. * \param output The SHA-1 checksum result. * - * \warning SHA-1 is considered a weak message digest and its use - * constitutes a security risk. We recommend considering - * stronger message digests instead. - * */ MBEDTLS_DEPRECATED void mbedtls_sha1( const unsigned char *input, size_t ilen, @@ -306,12 +315,13 @@ MBEDTLS_DEPRECATED void mbedtls_sha1( const unsigned char *input, /** * \brief The SHA-1 checkup routine. * - * \return \c 0 on success, or \c 1 on failure. - * * \warning SHA-1 is considered a weak message digest and its use * constitutes a security risk. We recommend considering * stronger message digests instead. * + * \return \c 0 on success. + * \return \c 1 on failure. + * */ int mbedtls_sha1_self_test( int verbose ); From 92d66b88aeab09f0828e0d98ede669956c857ad0 Mon Sep 17 00:00:00 2001 From: Rose Zadik Date: Tue, 17 Apr 2018 10:36:56 +0100 Subject: [PATCH 2/3] Update sha1.h Changes based on review comments --- include/mbedtls/sha1.h | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/include/mbedtls/sha1.h b/include/mbedtls/sha1.h index 4a43c0101..d8ce3c63b 100644 --- a/include/mbedtls/sha1.h +++ b/include/mbedtls/sha1.h @@ -97,8 +97,8 @@ void mbedtls_sha1_free( mbedtls_sha1_context *ctx ); * constitutes a security risk. We recommend considering * stronger message digests instead. * - * \param dst The destination context. - * \param src The context to clone. + * \param dst The SHA-1 context to clone to. + * \param src The SHA-1 context to clone from. * */ void mbedtls_sha1_clone( mbedtls_sha1_context *dst, @@ -111,7 +111,7 @@ void mbedtls_sha1_clone( mbedtls_sha1_context *dst, * constitutes a security risk. We recommend considering * stronger message digests instead. * - * \param ctx The context to initialize. + * \param ctx The SHA-1 context to initialize. * * \return \c 0 on success. * @@ -183,7 +183,7 @@ int mbedtls_internal_sha1_process( mbedtls_sha1_context *ctx, * * \deprecated Superseded by mbedtls_sha1_starts_ret() in 2.7.0. * - * \param ctx The context to initialize. + * \param ctx The SHA-1 context to initialize. * */ MBEDTLS_DEPRECATED void mbedtls_sha1_starts( mbedtls_sha1_context *ctx ); From 2e1934ac0c0a5b3a48739faea03b361aad26934b Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Wed, 18 Apr 2018 16:05:29 +0200 Subject: [PATCH 3/3] Fix comment formatting to pacify check-names.sh --- include/mbedtls/sha1.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/include/mbedtls/sha1.h b/include/mbedtls/sha1.h index d8ce3c63b..eec3f95bc 100644 --- a/include/mbedtls/sha1.h +++ b/include/mbedtls/sha1.h @@ -286,7 +286,7 @@ int mbedtls_sha1_ret( const unsigned char *input, #define MBEDTLS_DEPRECATED #endif /** -* \brief This function calculates the SHA-1 checksum of a buffer. + * \brief This function calculates the SHA-1 checksum of a buffer. * * The function allocates the context, performs the * calculation, and frees the context.