diff --git a/include/mbedtls/sha1.h b/include/mbedtls/sha1.h index 4d3a16401..700a34831 100644 --- a/include/mbedtls/sha1.h +++ b/include/mbedtls/sha1.h @@ -1,10 +1,10 @@ /** * \file sha1.h * - * \brief SHA-1 cryptographic hash function + * \brief The SHA-1 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_SHA1_H #define MBEDTLS_SHA1_H @@ -49,68 +49,70 @@ extern "C" { #endif /** - * \brief SHA-1 context structure + * \brief The SHA-1 context structure. */ typedef struct { - uint32_t total[2]; /*!< number of bytes processed */ - uint32_t state[5]; /*!< intermediate digest state */ - unsigned char buffer[64]; /*!< data block being processed */ + uint32_t total[2]; /*!< The number of Bytes processed. */ + uint32_t state[5]; /*!< The intermediate digest state. */ + unsigned char buffer[64]; /*!< The data block being processed. */ } mbedtls_sha1_context; /** - * \brief Initialize SHA-1 context + * \brief This function initializes a SHA-1 context. * - * \param ctx SHA-1 context to be initialized + * \param ctx The SHA-1 context to initialize. */ void mbedtls_sha1_init( mbedtls_sha1_context *ctx ); /** - * \brief Clear SHA-1 context + * \brief This function clears a SHA-1 context. * - * \param ctx SHA-1 context to be cleared + * \param ctx The SHA-1 context to clear. */ void mbedtls_sha1_free( mbedtls_sha1_context *ctx ); /** - * \brief Clone (the state of) a SHA-1 context + * \brief This function clones the state of a SHA-1 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_sha1_clone( mbedtls_sha1_context *dst, const mbedtls_sha1_context *src ); /** - * \brief SHA-1 context setup + * \brief This function starts a SHA-1 checksum calculation. * - * \param ctx context to be initialized + * \param ctx The context to initialize. * - * \return 0 if successful + * \return \c 0 if successful */ int mbedtls_sha1_starts_ret( mbedtls_sha1_context *ctx ); /** - * \brief SHA-1 process buffer + * \brief This function feeds an input buffer into an ongoing SHA-1 + * checksum calculation. * - * \param ctx SHA-1 context - * \param input buffer holding the data - * \param ilen length of the input data + * \param ctx The SHA-1 context. + * \param input The buffer holding the input data. + * \param ilen The length of the input data. * - * \return 0 if successful + * \return \c 0 if successful */ int mbedtls_sha1_update_ret( mbedtls_sha1_context *ctx, const unsigned char *input, size_t ilen ); /** - * \brief SHA-1 final digest + * \brief This function finishes the SHA-1 operation, and writes + * the result to the output buffer. * - * \param ctx SHA-1 context - * \param output SHA-1 checksum result + * \param ctx The SHA-1 context. + * \param output The SHA-1 checksum result. * - * \return 0 if successful + * \return \c 0 if successful */ int mbedtls_sha1_finish_ret( mbedtls_sha1_context *ctx, unsigned char output[20] ); @@ -119,9 +121,9 @@ int mbedtls_sha1_finish_ret( mbedtls_sha1_context *ctx, * \brief SHA-1 process data block (internal use only) * * \param ctx SHA-1 context - * \param data buffer holding one block of data + * \param data The data block being processed. * - * \return 0 if successful + * \return \c 0 if successful */ int mbedtls_internal_sha1_process( mbedtls_sha1_context *ctx, const unsigned char data[64] ); @@ -137,7 +139,7 @@ int mbedtls_internal_sha1_process( mbedtls_sha1_context *ctx, * * \deprecated Superseded by mbedtls_sha1_starts_ret() in 2.7.0 * - * \param ctx context to be initialized + * \param ctx The SHA-1 context to be initialized. */ MBEDTLS_DEPRECATED static inline void mbedtls_sha1_starts( mbedtls_sha1_context *ctx ) @@ -150,9 +152,9 @@ MBEDTLS_DEPRECATED static inline void mbedtls_sha1_starts( * * \deprecated Superseded by mbedtls_sha1_update_ret() in 2.7.0 * - * \param ctx SHA-1 context - * \param input buffer holding the data - * \param ilen length of the input data + * \param ctx The SHA-1 context. + * \param input The buffer holding the input data. + * \param ilen The length of the input data. */ MBEDTLS_DEPRECATED static inline void mbedtls_sha1_update( mbedtls_sha1_context *ctx, @@ -167,8 +169,8 @@ MBEDTLS_DEPRECATED static inline void mbedtls_sha1_update( * * \deprecated Superseded by mbedtls_sha1_finish_ret() in 2.7.0 * - * \param ctx SHA-1 context - * \param output SHA-1 checksum result + * \param ctx The SHA-1 context. + * \param output The SHA-1 checksum result. */ MBEDTLS_DEPRECATED static inline void mbedtls_sha1_finish( mbedtls_sha1_context *ctx, @@ -182,8 +184,8 @@ MBEDTLS_DEPRECATED static inline void mbedtls_sha1_finish( * * \deprecated Superseded by mbedtls_internal_sha1_process() in 2.7.0 * - * \param ctx SHA-1 context - * \param data buffer holding one block of data + * \param ctx The SHA-1 context. + * \param data The data block being processed. */ MBEDTLS_DEPRECATED static inline void mbedtls_sha1_process( mbedtls_sha1_context *ctx, @@ -208,13 +210,19 @@ extern "C" { #endif /** - * \brief Output = SHA-1( input buffer ) + * \brief This function calculates the SHA-1 checksum of a buffer. * - * \param input buffer holding the data - * \param ilen length of the input data - * \param output SHA-1 checksum result + * The function allocates the context, performs the + * calculation, and frees the context. * - * \return 0 if successful + * The SHA-1 result is calculated as + * output = SHA-1(input buffer). + * + * \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 */ int mbedtls_sha1_ret( const unsigned char *input, size_t ilen, @@ -231,9 +239,9 @@ int mbedtls_sha1_ret( const unsigned char *input, * * \deprecated Superseded by mbedtls_sha1_ret() in 2.7.0 * - * \param input buffer holding the data - * \param ilen length of the input data - * \param output SHA-1 checksum result + * \param input The buffer holding the input data. + * \param ilen The length of the input data. + * \param output The SHA-1 checksum result. */ MBEDTLS_DEPRECATED static inline void mbedtls_sha1( const unsigned char *input, size_t ilen, @@ -246,9 +254,9 @@ MBEDTLS_DEPRECATED static inline void mbedtls_sha1( const unsigned char *input, #endif /* !MBEDTLS_DEPRECATED_REMOVED */ /** - * \brief Checkup routine + * \brief The SHA-1 checkup routine. * - * \return 0 if successful, or 1 if the test failed + * \return \c 0 on success, or \c 1 on failure. */ int mbedtls_sha1_self_test( int verbose );