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
This commit is contained in:
Rose Zadik
Jaeden Amero
parent
64feefb4a2
commit
602285eac2
1 changed files with 96 additions and 62 deletions
|
|
@ -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 @@ extern "C" {
|
|||
#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 @@ int mbedtls_internal_sha256_process( mbedtls_sha256_context *ctx,
|
|||
#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 @@ MBEDTLS_DEPRECATED static inline void mbedtls_sha256_starts(
|
|||
}
|
||||
|
||||
/**
|
||||
* \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 @@ MBEDTLS_DEPRECATED static inline void mbedtls_sha256_update(
|
|||
}
|
||||
|
||||
/**
|
||||
* \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 @@ MBEDTLS_DEPRECATED static inline void mbedtls_sha256_finish(
|
|||
}
|
||||
|
||||
/**
|
||||
* \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 @@ MBEDTLS_DEPRECATED static inline void mbedtls_sha256_process(
|
|||
|
||||
#undef MBEDTLS_DEPRECATED
|
||||
#endif /* !MBEDTLS_DEPRECATED_REMOVED */
|
||||
|
||||
#ifdef __cplusplus
|
||||
}
|
||||
#endif
|
||||
|
|
@ -212,14 +229,21 @@ extern "C" {
|
|||
#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 @@ int mbedtls_sha256_ret( const unsigned char *input,
|
|||
#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 @@ MBEDTLS_DEPRECATED static inline void mbedtls_sha256(
|
|||
#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 );
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue