cuberite/polarssl
1
0
Fork 0
mirror of https://github.com/cuberite/polarssl.git synced 2025-10-30 19:20:40 -04:00
Code Issues Packages Projects Releases Wiki Activity

Improve SHA-512 documentation

Browse Source 
- 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
This commit is contained in:
Rose Zadik 2018-01-26 11:01:31 +00:00 committed by Jaeden Amero
parent 602285eac2
commit 27ff120a61
1 changed files with 99 additions and 64 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

159
include/mbedtls/sha512.h
View File

@ -1,10 +1,10 @@
/** /**
* \file sha512.h * \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 * SPDX-License-Identifier: Apache-2.0
* *
* Licensed under the Apache License, Version 2.0 (the "License"); you may * 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 * See the License for the specific language governing permissions and
* limitations under the License. * 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 #ifndef MBEDTLS_SHA512_H
#define MBEDTLS_SHA512_H #define MBEDTLS_SHA512_H
@ -39,7 +39,6 @@
!defined(inline) && !defined(__cplusplus) !defined(inline) && !defined(__cplusplus)
#define inline __inline #define inline __inline
#endif #endif
#if !defined(MBEDTLS_SHA512_ALT) #if !defined(MBEDTLS_SHA512_ALT)
// Regular implementation // Regular implementation
// //
@ -49,85 +48,97 @@ extern "C" {
#endif #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 typedef struct
{ {
uint64_t total[2]; /*!< number of bytes processed */ uint64_t total[2]; /*!< The number of Bytes processed. */
uint64_t state[8]; /*!< intermediate digest state */ uint64_t state[8]; /*!< The intermediate digest state. */
unsigned char buffer[128]; /*!< data block being processed */ unsigned char buffer[128]; /*!< The data block being processed. */
int is384; /*!< 0 => SHA-512, else SHA-384 */ int is384; /*!< Determines which function to use.
* <ul><li>0: Use SHA-512.</li>
* <li>1: Use SHA-384.</li></ul> */
} }
mbedtls_sha512_context; 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 ); 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 ); 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 dst The destination context.
* \param src The context to be cloned * \param src The context to clone.
*/ */
void mbedtls_sha512_clone( mbedtls_sha512_context *dst, void mbedtls_sha512_clone( mbedtls_sha512_context *dst,
const mbedtls_sha512_context *src ); 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 ctx The SHA-512 context to initialize.
* \param is384 0 = use SHA512, 1 = use SHA384 * \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 ); 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 ctx The SHA-512 context.
* \param input buffer holding the data * \param input The buffer holding the input data.
* \param ilen length of 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, int mbedtls_sha512_update_ret( mbedtls_sha512_context *ctx,
const unsigned char *input, const unsigned char *input,
size_t ilen ); 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 ctx The SHA-512 context.
* \param output SHA-384/512 checksum result * \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, int mbedtls_sha512_finish_ret( mbedtls_sha512_context *ctx,
unsigned char output[64] ); 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 ctx The SHA-512 context.
* \param data buffer holding one block of data * \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, int mbedtls_internal_sha512_process( mbedtls_sha512_context *ctx,
const unsigned char data[128] ); const unsigned char data[128] );
#if !defined(MBEDTLS_DEPRECATED_REMOVED) #if !defined(MBEDTLS_DEPRECATED_REMOVED)
#if defined(MBEDTLS_DEPRECATED_WARNING) #if defined(MBEDTLS_DEPRECATED_WARNING)
#define MBEDTLS_DEPRECATED __attribute__((deprecated)) #define MBEDTLS_DEPRECATED __attribute__((deprecated))
@ -135,12 +146,15 @@ int mbedtls_internal_sha512_process( mbedtls_sha512_context *ctx,
#define MBEDTLS_DEPRECATED #define MBEDTLS_DEPRECATED
#endif #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 * \deprecated Superseded by mbedtls_sha512_starts_ret() in 2.7.0
* *
* \param ctx context to be initialized * \param ctx The SHA-512 context to initialize.
* \param is384 0 = use SHA512, 1 = use SHA384 * \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_DEPRECATED static inline void mbedtls_sha512_starts(
mbedtls_sha512_context *ctx, mbedtls_sha512_context *ctx,
@ -150,13 +164,14 @@ MBEDTLS_DEPRECATED static inline void mbedtls_sha512_starts(
} }
/** /**
* \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 * \deprecated Superseded by mbedtls_sha512_update_ret() in 2.7.0
* *
* \param ctx SHA-512 context * \param ctx The SHA-512 context.
* \param input buffer holding the data * \param input The buffer holding the data.
* \param ilen length of the input data * \param ilen The length of the input data.
*/ */
MBEDTLS_DEPRECATED static inline void mbedtls_sha512_update( MBEDTLS_DEPRECATED static inline void mbedtls_sha512_update(
mbedtls_sha512_context *ctx, mbedtls_sha512_context *ctx,
@ -167,12 +182,13 @@ MBEDTLS_DEPRECATED static inline void mbedtls_sha512_update(
} }
/** /**
* \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 * \deprecated Superseded by mbedtls_sha512_finish_ret() in 2.7.0
* *
* \param ctx SHA-512 context * \param ctx The SHA-512 context.
* \param output SHA-384/512 checksum result * \param output The SHA-384 or SHA-512 checksum result.
*/ */
MBEDTLS_DEPRECATED static inline void mbedtls_sha512_finish( MBEDTLS_DEPRECATED static inline void mbedtls_sha512_finish(
mbedtls_sha512_context *ctx, mbedtls_sha512_context *ctx,
@ -182,12 +198,14 @@ MBEDTLS_DEPRECATED static inline void mbedtls_sha512_finish(
} }
/** /**
* \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 * \deprecated Superseded by mbedtls_internal_sha512_process() in 2.7.0
* *
* \param ctx SHA-512 context * \param ctx The SHA-512 context.
* \param data buffer holding one block of data * \param data The buffer holding one block of data.
*/ */
MBEDTLS_DEPRECATED static inline void mbedtls_sha512_process( MBEDTLS_DEPRECATED static inline void mbedtls_sha512_process(
mbedtls_sha512_context *ctx, mbedtls_sha512_context *ctx,
@ -212,14 +230,23 @@ extern "C" {
#endif #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 * The function allocates the context, performs the
* \param ilen length of the input data * calculation, and frees the context.
* \param output SHA-384/512 checksum result
* \param is384 0 = use SHA512, 1 = use SHA384
* *
* \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, int mbedtls_sha512_ret( const unsigned char *input,
size_t ilen, size_t ilen,
@ -233,14 +260,23 @@ int mbedtls_sha512_ret( const unsigned char *input,
#define MBEDTLS_DEPRECATED #define MBEDTLS_DEPRECATED
#endif #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 * \deprecated Superseded by mbedtls_sha512_ret() in 2.7.0
* *
* \param input buffer holding the data * \param input The buffer holding the data.
* \param ilen length of the input data * \param ilen The length of the input data.
* \param output SHA-384/512 checksum result * \param output The SHA-384 or SHA-512 checksum result.
* \param is384 0 = use SHA512, 1 = use SHA384 * \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( MBEDTLS_DEPRECATED static inline void mbedtls_sha512(
const unsigned char *input, const unsigned char *input,
@ -253,11 +289,10 @@ MBEDTLS_DEPRECATED static inline void mbedtls_sha512(
#undef MBEDTLS_DEPRECATED #undef MBEDTLS_DEPRECATED
#endif /* !MBEDTLS_DEPRECATED_REMOVED */ #endif /* !MBEDTLS_DEPRECATED_REMOVED */
/**
/** * \brief The SHA-384 or SHA-512 checkup routine.
* \brief 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 ); int mbedtls_sha512_self_test( int verbose );