Improve SHA-256 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: #1325
diff --git a/include/mbedtls/sha256.h b/include/mbedtls/sha256.h
index 5c5d07a..a2b6e11 100644
--- a/include/mbedtls/sha256.h
+++ b/include/mbedtls/sha256.h
@@ -1,10 +1,10 @@
/**
* \file sha256.h
*
- * \brief SHA-224 and SHA-256 cryptographic hash function
+ * \brief The SHA-224 and SHA-256 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_SHA256_H
#define MBEDTLS_SHA256_H
@@ -39,7 +39,6 @@
!defined(inline) && !defined(__cplusplus)
#define inline __inline
#endif
-
#if !defined(MBEDTLS_SHA256_ALT)
// Regular implementation
//
@@ -49,81 +48,94 @@
#endif
/**
- * \brief SHA-256 context structure
+ * \brief The SHA-256 context structure.
+ *
+ * The structure is used both for SHA-256 and for SHA-224
+ * checksum calculations. The choice between these two is
+ * made in the call to mbedtls_sha256_starts_ret().
*/
typedef struct
{
- uint32_t total[2]; /*!< number of bytes processed */
- uint32_t state[8]; /*!< intermediate digest state */
- unsigned char buffer[64]; /*!< data block being processed */
- int is224; /*!< 0 => SHA-256, else SHA-224 */
+ uint32_t total[2]; /*!< The number of Bytes processed. */
+ uint32_t state[8]; /*!< The intermediate digest state. */
+ unsigned char buffer[64]; /*!< The data block being processed. */
+ int is224; /*!< Determines which function to use.
+ <ul><li>0: Use SHA-256.</li>
+ <li>1: Use SHA-224.</li></ul> */
}
mbedtls_sha256_context;
/**
- * \brief Initialize SHA-256 context
+ * \brief This function initializes a SHA-256 context.
*
- * \param ctx SHA-256 context to be initialized
+ * \param ctx The SHA-256 context to initialize.
*/
void mbedtls_sha256_init( mbedtls_sha256_context *ctx );
/**
- * \brief Clear SHA-256 context
+ * \brief This function clears a SHA-256 context.
*
- * \param ctx SHA-256 context to be cleared
+ * \param ctx The SHA-256 context to clear.
*/
void mbedtls_sha256_free( mbedtls_sha256_context *ctx );
/**
- * \brief Clone (the state of) a SHA-256 context
+ * \brief This function clones the state of a SHA-256 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_sha256_clone( mbedtls_sha256_context *dst,
const mbedtls_sha256_context *src );
/**
- * \brief SHA-256 context setup
+ * \brief This function starts a SHA-224 or SHA-256 checksum
+ * calculation.
*
- * \param ctx context to be initialized
- * \param is224 0 = use SHA256, 1 = use SHA224
+ * \param ctx The context to initialize.
+ * \param is224 Determines which function to use.
+ * <ul><li>0: Use SHA-256.</li>
+ * <li>1: Use SHA-224.</li></ul>
*
- * \return 0 if successful
+ * \return \c 0 on success.
*/
int mbedtls_sha256_starts_ret( mbedtls_sha256_context *ctx, int is224 );
/**
- * \brief SHA-256 process buffer
+ * \brief This function feeds an input buffer into an ongoing
+ * SHA-256 checksum calculation.
*
* \param ctx SHA-256 context
* \param input buffer holding the data
* \param ilen length of the input data
*
- * \return 0 if successful
+ * \return \c 0 on success.
*/
int mbedtls_sha256_update_ret( mbedtls_sha256_context *ctx,
const unsigned char *input,
size_t ilen );
/**
- * \brief SHA-256 final digest
+ * \brief This function finishes the SHA-256 operation, and writes
+ * the result to the output buffer.
*
- * \param ctx SHA-256 context
- * \param output SHA-224/256 checksum result
+ * \param ctx The SHA-256 context.
+ * \param output The SHA-224 or SHA-256 checksum result.
*
- * \return 0 if successful
+ * \return \c 0 on success.
*/
int mbedtls_sha256_finish_ret( mbedtls_sha256_context *ctx,
unsigned char output[32] );
/**
- * \brief SHA-256 process data block (internal use only)
+ * \brief This function processes a single data block within
+ * the ongoing SHA-256 computation. This function is for
+ * internal use only.
*
- * \param ctx SHA-256 context
- * \param data buffer holding one block of data
+ * \param ctx The SHA-256 context.
+ * \param data The buffer holding one block of data.
*
- * \return 0 if successful
+ * \return \c 0 on success.
*/
int mbedtls_internal_sha256_process( mbedtls_sha256_context *ctx,
const unsigned char data[64] );
@@ -135,12 +147,14 @@
#define MBEDTLS_DEPRECATED
#endif
/**
- * \brief SHA-256 context setup
+ * \brief This function starts a SHA-256 checksum calculation.
*
- * \deprecated Superseded by mbedtls_sha256_starts_ret() in 2.7.0
+ * \deprecated Superseded by mbedtls_sha256_starts_ret() in 2.7.0.
*
- * \param ctx context to be initialized
- * \param is224 0 = use SHA256, 1 = use SHA224
+ * \param ctx The SHA-256 context to initialize.
+ * \param is224 Determines which function to use.
+ * <ul><li>0: Use SHA-256.</li>
+ * <li>1: Use SHA-224.</li></ul>
*/
MBEDTLS_DEPRECATED static inline void mbedtls_sha256_starts(
mbedtls_sha256_context *ctx,
@@ -150,13 +164,14 @@
}
/**
- * \brief SHA-256 process buffer
+ * \brief This function feeds an input buffer into an ongoing
+ * SHA-256 checksum calculation.
*
- * \deprecated Superseded by mbedtls_sha256_update_ret() in 2.7.0
+ * \deprecated Superseded by mbedtls_sha256_update_ret() in 2.7.0.
*
- * \param ctx SHA-256 context
- * \param input buffer holding the data
- * \param ilen length of the input data
+ * \param ctx The SHA-256 context to initialize.
+ * \param input The buffer holding the data.
+ * \param ilen The length of the input data.
*/
MBEDTLS_DEPRECATED static inline void mbedtls_sha256_update(
mbedtls_sha256_context *ctx,
@@ -167,12 +182,13 @@
}
/**
- * \brief SHA-256 final digest
+ * \brief This function finishes the SHA-256 operation, and writes
+ * the result to the output buffer.
*
- * \deprecated Superseded by mbedtls_sha256_finish_ret() in 2.7.0
+ * \deprecated Superseded by mbedtls_sha256_finish_ret() in 2.7.0.
*
- * \param ctx SHA-256 context
- * \param output SHA-224/256 checksum result
+ * \param ctx The SHA-256 context.
+ * \param output The SHA-224or SHA-256 checksum result.
*/
MBEDTLS_DEPRECATED static inline void mbedtls_sha256_finish(
mbedtls_sha256_context *ctx,
@@ -182,12 +198,14 @@
}
/**
- * \brief SHA-256 process data block (internal use only)
+ * \brief This function processes a single data block within
+ * the ongoing SHA-256 computation. This function is for
+ * internal use only.
*
- * \deprecated Superseded by mbedtls_internal_sha256_process() in 2.7.0
+ * \deprecated Superseded by mbedtls_internal_sha256_process() in 2.7.0.
*
- * \param ctx SHA-256 context
- * \param data buffer holding one block of data
+ * \param ctx The SHA-256 context.
+ * \param data The buffer holding one block of data.
*/
MBEDTLS_DEPRECATED static inline void mbedtls_sha256_process(
mbedtls_sha256_context *ctx,
@@ -198,7 +216,6 @@
#undef MBEDTLS_DEPRECATED
#endif /* !MBEDTLS_DEPRECATED_REMOVED */
-
#ifdef __cplusplus
}
#endif
@@ -212,14 +229,21 @@
#endif
/**
- * \brief Output = SHA-256( input buffer )
+ * \brief This function calculates the SHA-224 or SHA-256
+ * checksum of a buffer.
*
- * \param input buffer holding the data
- * \param ilen length of the input data
- * \param output SHA-224/256 checksum result
- * \param is224 0 = use SHA256, 1 = use SHA224
+ * The function allocates the context, performs the
+ * calculation, and frees the context.
*
- * \return 0 if successful
+ * The SHA-256 result is calculated as
+ * output = SHA-256(input buffer).
+ *
+ * \param input The buffer holding the input data.
+ * \param ilen The length of the input data.
+ * \param output The SHA-224 or SHA-256 checksum result.
+ * \param is224 Determines which function to use.
+ * <ul><li>0: Use SHA-256.</li>
+ * <li>1: Use SHA-224.</li></ul>
*/
int mbedtls_sha256_ret( const unsigned char *input,
size_t ilen,
@@ -232,15 +256,25 @@
#else
#define MBEDTLS_DEPRECATED
#endif
+
/**
- * \brief Output = SHA-256( input buffer )
+ * \brief This function calculates the SHA-224 or SHA-256 checksum
+ * of a buffer.
*
- * \deprecated Superseded by mbedtls_sha256_ret() in 2.7.0
+ * The function allocates the context, performs the
+ * calculation, and frees the context.
*
- * \param input buffer holding the data
- * \param ilen length of the input data
- * \param output SHA-224/256 checksum result
- * \param is224 0 = use SHA256, 1 = use SHA224
+ * The SHA-256 result is calculated as
+ * output = SHA-256(input buffer).
+ *
+ * \deprecated Superseded by mbedtls_sha256_ret() in 2.7.0.
+ *
+ * \param input The buffer holding the data.
+ * \param ilen The length of the input data.
+ * \param output The SHA-224 or SHA-256 checksum result.
+ * \param is224 Determines which function to use.
+ * <ul><li>0: Use SHA-256.</li>
+ * <li>1: Use SHA-224.</li></ul>
*/
MBEDTLS_DEPRECATED static inline void mbedtls_sha256(
const unsigned char *input,
@@ -255,9 +289,9 @@
#endif /* !MBEDTLS_DEPRECATED_REMOVED */
/**
- * \brief Checkup routine
+ * \brief The SHA-224 and SHA-256 checkup routine.
*
- * \return 0 if successful, or 1 if the test failed
+ * \return \c 0 on success, or \c 1 on failure.
*/
int mbedtls_sha256_self_test( int verbose );