Improve SHA-1 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.
GitHub PR: #1322
diff --git a/include/mbedtls/sha1.h b/include/mbedtls/sha1.h
index 4d3a164..700a348 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 @@
#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 @@
* \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 @@
*
* \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 @@
*
* \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 @@
*
* \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 @@
*
* \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 @@
#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 @@
*
* \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 @@
#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 );