From 27ff120a6121528de9f9a726dfd80a209ee05a1a Mon Sep 17 00:00:00 2001 From: Rose Zadik Date: Fri, 26 Jan 2018 11:01:31 +0000 Subject: [PATCH] Improve SHA-512 documentation - Rephrase file/function/parameter/enum/define/error descriptions into full and clear sentences. - Make sure to adhere to the Arm writing guidelines. - Fix missing/incorrect Doxygen tags. - Standardize terminology used within the file. - Align deprecated function descriptions with those of the superseding functions. GitHub PR: #1326 --- include/mbedtls/sha512.h | 163 ++++++++++++++++++++++++--------------- 1 file changed, 99 insertions(+), 64 deletions(-) diff --git a/include/mbedtls/sha512.h b/include/mbedtls/sha512.h index 7453c44d4..52ae204d4 100644 --- a/include/mbedtls/sha512.h +++ b/include/mbedtls/sha512.h @@ -1,10 +1,10 @@ /** * \file sha512.h * - * \brief SHA-384 and SHA-512 cryptographic hash function + * \brief The SHA-384 and SHA-512 cryptographic hash function. */ /* - * Copyright (C) 2006-2015, ARM Limited, All Rights Reserved + * Copyright (C) 2006-2018, Arm Limited (or its affiliates), All Rights Reserved * SPDX-License-Identifier: Apache-2.0 * * Licensed under the Apache License, Version 2.0 (the "License"); you may @@ -19,7 +19,7 @@ * See the License for the specific language governing permissions and * limitations under the License. * - * This file is part of mbed TLS (https://tls.mbed.org) + * This file is part of Mbed TLS (https://tls.mbed.org) */ #ifndef MBEDTLS_SHA512_H #define MBEDTLS_SHA512_H @@ -39,7 +39,6 @@ !defined(inline) && !defined(__cplusplus) #define inline __inline #endif - #if !defined(MBEDTLS_SHA512_ALT) // Regular implementation // @@ -49,85 +48,97 @@ extern "C" { #endif /** - * \brief SHA-512 context structure + * \brief The SHA-512 context structure. + * + * The structure is used both for SHA-384 and for SHA-512 + * checksum calculations. The choice between these two is + * made in the call to mbedtls_sha512_starts_ret(). */ typedef struct { - uint64_t total[2]; /*!< number of bytes processed */ - uint64_t state[8]; /*!< intermediate digest state */ - unsigned char buffer[128]; /*!< data block being processed */ - int is384; /*!< 0 => SHA-512, else SHA-384 */ + uint64_t total[2]; /*!< The number of Bytes processed. */ + uint64_t state[8]; /*!< The intermediate digest state. */ + unsigned char buffer[128]; /*!< The data block being processed. */ + int is384; /*!< Determines which function to use. + * */ } mbedtls_sha512_context; /** - * \brief Initialize SHA-512 context + * \brief This function initializes a SHA-512 context. * - * \param ctx SHA-512 context to be initialized + * \param ctx The SHA-512 context to initialize. */ void mbedtls_sha512_init( mbedtls_sha512_context *ctx ); /** - * \brief Clear SHA-512 context + * \brief This function clears a SHA-512 context. * - * \param ctx SHA-512 context to be cleared + * \param ctx The SHA-512 context to clear. */ void mbedtls_sha512_free( mbedtls_sha512_context *ctx ); /** - * \brief Clone (the state of) a SHA-512 context + * \brief This function clones the state of a SHA-512 context. * - * \param dst The destination context - * \param src The context to be cloned + * \param dst The destination context. + * \param src The context to clone. */ void mbedtls_sha512_clone( mbedtls_sha512_context *dst, const mbedtls_sha512_context *src ); /** - * \brief SHA-512 context setup + * \brief This function starts a SHA-384 or SHA-512 checksum + * calculation. * - * \param ctx context to be initialized - * \param is384 0 = use SHA512, 1 = use SHA384 + * \param ctx The SHA-512 context to initialize. + * \param is384 Determines which function to use. + * * - * \return 0 if successful + * \return \c 0 on success. */ int mbedtls_sha512_starts_ret( mbedtls_sha512_context *ctx, int is384 ); /** - * \brief SHA-512 process buffer + * \brief This function feeds an input buffer into an ongoing + * SHA-512 checksum calculation. * - * \param ctx SHA-512 context - * \param input buffer holding the data - * \param ilen length of the input data + * \param ctx The SHA-512 context. + * \param input The buffer holding the input data. + * \param ilen The length of the input data. * - * \return 0 if successful + * \return \c 0 on success. */ int mbedtls_sha512_update_ret( mbedtls_sha512_context *ctx, - const unsigned char *input, - size_t ilen ); + const unsigned char *input, + size_t ilen ); /** - * \brief SHA-512 final digest + * \brief This function finishes the SHA-512 operation, and writes + * the result to the output buffer. This function is for + * internal use only. * - * \param ctx SHA-512 context - * \param output SHA-384/512 checksum result + * \param ctx The SHA-512 context. + * \param output The SHA-384 or SHA-512 checksum result. * - * \return 0 if successful + * \return \c 0 on success. */ int mbedtls_sha512_finish_ret( mbedtls_sha512_context *ctx, unsigned char output[64] ); /** - * \brief SHA-512 process data block (internal use only) + * \brief This function processes a single data block within + * the ongoing SHA-512 computation. * - * \param ctx SHA-512 context - * \param data buffer holding one block of data + * \param ctx The SHA-512 context. + * \param data The buffer holding one block of data. * - * \return 0 if successful + * \return \c 0 on success. */ int mbedtls_internal_sha512_process( mbedtls_sha512_context *ctx, const unsigned char data[128] ); - #if !defined(MBEDTLS_DEPRECATED_REMOVED) #if defined(MBEDTLS_DEPRECATED_WARNING) #define MBEDTLS_DEPRECATED __attribute__((deprecated)) @@ -135,12 +146,15 @@ int mbedtls_internal_sha512_process( mbedtls_sha512_context *ctx, #define MBEDTLS_DEPRECATED #endif /** - * \brief SHA-512 context setup + * \brief This function starts a SHA-384 or SHA-512 checksum + * calculation. * * \deprecated Superseded by mbedtls_sha512_starts_ret() in 2.7.0 * - * \param ctx context to be initialized - * \param is384 0 = use SHA512, 1 = use SHA384 + * \param ctx The SHA-512 context to initialize. + * \param is384 Determines which function to use. + * */ MBEDTLS_DEPRECATED static inline void mbedtls_sha512_starts( mbedtls_sha512_context *ctx, @@ -150,13 +164,14 @@ MBEDTLS_DEPRECATED static inline void mbedtls_sha512_starts( } /** - * \brief SHA-512 process buffer + * \brief This function feeds an input buffer into an ongoing + * SHA-512 checksum calculation. * * \deprecated Superseded by mbedtls_sha512_update_ret() in 2.7.0 * - * \param ctx SHA-512 context - * \param input buffer holding the data - * \param ilen length of the input data + * \param ctx The SHA-512 context. + * \param input The buffer holding the data. + * \param ilen The length of the input data. */ MBEDTLS_DEPRECATED static inline void mbedtls_sha512_update( mbedtls_sha512_context *ctx, @@ -167,12 +182,13 @@ MBEDTLS_DEPRECATED static inline void mbedtls_sha512_update( } /** - * \brief SHA-512 final digest + * \brief This function finishes the SHA-512 operation, and writes + * the result to the output buffer. * * \deprecated Superseded by mbedtls_sha512_finish_ret() in 2.7.0 * - * \param ctx SHA-512 context - * \param output SHA-384/512 checksum result + * \param ctx The SHA-512 context. + * \param output The SHA-384 or SHA-512 checksum result. */ MBEDTLS_DEPRECATED static inline void mbedtls_sha512_finish( mbedtls_sha512_context *ctx, @@ -182,12 +198,14 @@ MBEDTLS_DEPRECATED static inline void mbedtls_sha512_finish( } /** - * \brief SHA-512 process data block (internal use only) + * \brief This function processes a single data block within + * the ongoing SHA-512 computation. This function is for + * internal use only. * * \deprecated Superseded by mbedtls_internal_sha512_process() in 2.7.0 * - * \param ctx SHA-512 context - * \param data buffer holding one block of data + * \param ctx The SHA-512 context. + * \param data The buffer holding one block of data. */ MBEDTLS_DEPRECATED static inline void mbedtls_sha512_process( mbedtls_sha512_context *ctx, @@ -212,14 +230,23 @@ extern "C" { #endif /** - * \brief Output = SHA-512( input buffer ) + * \brief This function calculates the SHA-512 or SHA-384 + * checksum of a buffer. * - * \param input buffer holding the data - * \param ilen length of the input data - * \param output SHA-384/512 checksum result - * \param is384 0 = use SHA512, 1 = use SHA384 + * The function allocates the context, performs the + * calculation, and frees the context. * - * \return 0 if successful + * The SHA-512 result is calculated as + * output = SHA-512(input buffer). + * + * \param input The buffer holding the input data. + * \param ilen The length of the input data. + * \param output The SHA-384 or SHA-512 checksum result. + * \param is384 Determines which function to use. + * + * + * \return \c 0 on success. */ int mbedtls_sha512_ret( const unsigned char *input, size_t ilen, @@ -233,14 +260,23 @@ int mbedtls_sha512_ret( const unsigned char *input, #define MBEDTLS_DEPRECATED #endif /** - * \brief Output = SHA-512( input buffer ) + * \brief This function calculates the SHA-512 or SHA-384 + * checksum of a buffer. + * + * The function allocates the context, performs the + * calculation, and frees the context. + * + * The SHA-512 result is calculated as + * output = SHA-512(input buffer). * * \deprecated Superseded by mbedtls_sha512_ret() in 2.7.0 * - * \param input buffer holding the data - * \param ilen length of the input data - * \param output SHA-384/512 checksum result - * \param is384 0 = use SHA512, 1 = use SHA384 + * \param input The buffer holding the data. + * \param ilen The length of the input data. + * \param output The SHA-384 or SHA-512 checksum result. + * \param is384 Determines which function to use. + * */ MBEDTLS_DEPRECATED static inline void mbedtls_sha512( const unsigned char *input, @@ -253,11 +289,10 @@ MBEDTLS_DEPRECATED static inline void mbedtls_sha512( #undef MBEDTLS_DEPRECATED #endif /* !MBEDTLS_DEPRECATED_REMOVED */ - -/** - * \brief Checkup routine + /** + * \brief The SHA-384 or SHA-512 checkup routine. * - * \return 0 if successful, or 1 if the test failed + * \return \c 0 on success, or \c 1 on failure. */ int mbedtls_sha512_self_test( int verbose );