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
diff --git a/include/mbedtls/sha512.h b/include/mbedtls/sha512.h
index 7453c44..52ae204 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 @@
#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.
+ * <ul><li>0: Use SHA-512.</li>
+ * <li>1: Use SHA-384.</li></ul> */
}
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.
+ * <ul><li>0: Use SHA-512.</li>
+ * <li>1: Use SHA-384.</li></ul>
*
- * \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 @@
#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.
+ * <ul><li>0: Use SHA-512.</li>
+ * <li>1: Use SHA-384.</li></ul>
*/
MBEDTLS_DEPRECATED static inline void mbedtls_sha512_starts(
mbedtls_sha512_context *ctx,
@@ -150,13 +164,14 @@
}
/**
- * \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 @@
}
/**
- * \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 @@
}
/**
- * \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 @@
#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.
+ * <ul><li>0: Use SHA-512.</li>
+ * <li>1: Use SHA-384.</li></ul>
+ *
+ * \return \c 0 on success.
*/
int mbedtls_sha512_ret( const unsigned char *input,
size_t ilen,
@@ -233,14 +260,23 @@
#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.
+ * <ul><li>0: Use SHA-512.</li>
+ * <li>1: Use SHA-384.</li></ul>
*/
MBEDTLS_DEPRECATED static inline void mbedtls_sha512(
const unsigned char *input,
@@ -253,11 +289,10 @@
#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 );