mirror/mbedtls
1
0
Fork 0
mirror of https://github.com/Mbed-TLS/mbedtls.git synced 2025-04-03 10:20:36 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Update sha1.h

Browse Source 
Minor documentation improvements:
*Standardized file brief description.
*Separated return statements.
*Reordered tags within documentation blocks so that params and returns are last in block.
*Applied previous function documentation improvements to depracated functions.
This commit is contained in:
Rose Zadik 2018-03-27 12:49:48 +01:00 committed by GitHub
parent f65379bc40
commit 8274142e45
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 75 additions and 65 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

140
include/mbedtls/sha1.h
View File

@ -1,7 +1,10 @@
/** /**
* \file sha1.h * \file sha1.h
* *
* \brief The SHA-1 cryptographic hash function. * \brief This file contains SHA-1 definitions and functions.
*
* The Secure Hash Algorithm 1 (SHA-1) cryptographic hash function is defined in
* <em>FIPS 180-4: Secure Hash Standard (SHS)</em>.
* *
* \warning SHA-1 is considered a weak message digest and its use constitutes * \warning SHA-1 is considered a weak message digest and its use constitutes
* a security risk. We recommend considering stronger message * a security risk. We recommend considering stronger message
@ -66,37 +69,37 @@ mbedtls_sha1_context;
/** /**
* \brief This function initializes a SHA-1 context. * \brief This function initializes a SHA-1 context.
* *
* \param ctx The SHA-1 context to initialize.
*
* \warning SHA-1 is considered a weak message digest and its use * \warning SHA-1 is considered a weak message digest and its use
* constitutes a security risk. We recommend considering * constitutes a security risk. We recommend considering
* stronger message digests instead. * stronger message digests instead.
* *
* \param ctx The SHA-1 context to initialize.
*
*/ */
void mbedtls_sha1_init( mbedtls_sha1_context *ctx ); void mbedtls_sha1_init( mbedtls_sha1_context *ctx );
/** /**
* \brief This function clears a SHA-1 context. * \brief This function clears a SHA-1 context.
* *
* \param ctx The SHA-1 context to clear.
*
* \warning SHA-1 is considered a weak message digest and its use * \warning SHA-1 is considered a weak message digest and its use
* constitutes a security risk. We recommend considering * constitutes a security risk. We recommend considering
* stronger message digests instead. * stronger message digests instead.
* *
* \param ctx The SHA-1 context to clear.
*
*/ */
void mbedtls_sha1_free( mbedtls_sha1_context *ctx ); void mbedtls_sha1_free( mbedtls_sha1_context *ctx );
/** /**
* \brief This function clones 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 clone.
*
* \warning SHA-1 is considered a weak message digest and its use * \warning SHA-1 is considered a weak message digest and its use
* constitutes a security risk. We recommend considering * constitutes a security risk. We recommend considering
* stronger message digests instead. * stronger message digests instead.
* *
* \param dst The destination context.
* \param src The context to clone.
*
*/ */
void mbedtls_sha1_clone( mbedtls_sha1_context *dst, void mbedtls_sha1_clone( mbedtls_sha1_context *dst,
const mbedtls_sha1_context *src ); const mbedtls_sha1_context *src );
@ -104,14 +107,14 @@ void mbedtls_sha1_clone( mbedtls_sha1_context *dst,
/** /**
* \brief This function starts a SHA-1 checksum calculation. * \brief This function starts a SHA-1 checksum calculation.
* *
* \param ctx The context to initialize.
*
* \return \c 0 if successful
*
* \warning SHA-1 is considered a weak message digest and its use * \warning SHA-1 is considered a weak message digest and its use
* constitutes a security risk. We recommend considering * constitutes a security risk. We recommend considering
* stronger message digests instead. * stronger message digests instead.
* *
* \param ctx The context to initialize.
*
* \return \c 0 on success.
*
*/ */
int mbedtls_sha1_starts_ret( mbedtls_sha1_context *ctx ); int mbedtls_sha1_starts_ret( mbedtls_sha1_context *ctx );
@ -119,16 +122,15 @@ int mbedtls_sha1_starts_ret( mbedtls_sha1_context *ctx );
* \brief This function feeds an input buffer into an ongoing SHA-1 * \brief This function feeds an input buffer into an ongoing SHA-1
* checksum calculation. * checksum calculation.
* *
* \param ctx The SHA-1 context.
* \param input The buffer holding the input data.
* \param ilen The length of the input data.
*
* \return \c 0 if successful
*
* \warning SHA-1 is considered a weak message digest and its use * \warning SHA-1 is considered a weak message digest and its use
* constitutes a security risk. We recommend considering * constitutes a security risk. We recommend considering
* stronger message digests instead. * stronger message digests instead.
* *
* \param ctx The SHA-1 context.
* \param input The buffer holding the input data.
* \param ilen The length of the input data.
*
* \return \c 0 on success.
*/ */
int mbedtls_sha1_update_ret( mbedtls_sha1_context *ctx, int mbedtls_sha1_update_ret( mbedtls_sha1_context *ctx,
const unsigned char *input, const unsigned char *input,
@ -138,31 +140,30 @@ int mbedtls_sha1_update_ret( mbedtls_sha1_context *ctx,
* \brief This function finishes the SHA-1 operation, and writes * \brief This function finishes the SHA-1 operation, and writes
* the result to the output buffer. * the result to the output buffer.
* *
* \param ctx The SHA-1 context.
* \param output The SHA-1 checksum result.
*
* \return \c 0 if successful
*
* \warning SHA-1 is considered a weak message digest and its use * \warning SHA-1 is considered a weak message digest and its use
* constitutes a security risk. We recommend considering * constitutes a security risk. We recommend considering
* stronger message digests instead. * stronger message digests instead.
* *
* \param ctx The SHA-1 context.
* \param output The SHA-1 checksum result.
*
* \return \c 0 on success.
*/ */
int mbedtls_sha1_finish_ret( mbedtls_sha1_context *ctx, int mbedtls_sha1_finish_ret( mbedtls_sha1_context *ctx,
unsigned char output[20] ); unsigned char output[20] );
/** /**
* \brief SHA-1 process data block (internal use only) * \brief SHA-1 process data block (internal use only).
*
* \param ctx SHA-1 context
* \param data The data block being processed.
*
* \return \c 0 if successful
* *
* \warning SHA-1 is considered a weak message digest and its use * \warning SHA-1 is considered a weak message digest and its use
* constitutes a security risk. We recommend considering * constitutes a security risk. We recommend considering
* stronger message digests instead. * stronger message digests instead.
* *
* \param ctx The SHA-1 context.
* \param data The data block being processed.
*
* \return \c 0 on success.
*
*/ */
int mbedtls_internal_sha1_process( mbedtls_sha1_context *ctx, int mbedtls_internal_sha1_process( mbedtls_sha1_context *ctx,
const unsigned char data[64] ); const unsigned char data[64] );
@ -174,65 +175,67 @@ int mbedtls_internal_sha1_process( mbedtls_sha1_context *ctx,
#define MBEDTLS_DEPRECATED #define MBEDTLS_DEPRECATED
#endif #endif
/** /**
* \brief SHA-1 context setup * \brief This function starts a SHA-1 checksum calculation.
*
* \deprecated Superseded by mbedtls_sha1_starts_ret() in 2.7.0
*
* \param ctx The SHA-1 context to be initialized.
* *
* \warning SHA-1 is considered a weak message digest and its use * \warning SHA-1 is considered a weak message digest and its use
* constitutes a security risk. We recommend considering * constitutes a security risk. We recommend considering
* stronger message digests instead. * stronger message digests instead.
* *
* \deprecated Superseded by mbedtls_sha1_starts_ret() in 2.7.0.
*
* \param ctx The context to initialize.
*
*/ */
MBEDTLS_DEPRECATED void mbedtls_sha1_starts( mbedtls_sha1_context *ctx ); MBEDTLS_DEPRECATED void mbedtls_sha1_starts( mbedtls_sha1_context *ctx );
/** /**
* \brief SHA-1 process buffer * \brief This function feeds an input buffer into an ongoing SHA-1
* * checksum calculation.
* \deprecated Superseded by mbedtls_sha1_update_ret() in 2.7.0
*
* \param ctx The SHA-1 context.
* \param input The buffer holding the input data.
* \param ilen The length of the input data.
* *
* \warning SHA-1 is considered a weak message digest and its use * \warning SHA-1 is considered a weak message digest and its use
* constitutes a security risk. We recommend considering * constitutes a security risk. We recommend considering
* stronger message digests instead. * stronger message digests instead.
* *
* \deprecated Superseded by mbedtls_sha1_update_ret() in 2.7.0.
*
* \param ctx The SHA-1 context.
* \param input The buffer holding the input data.
* \param ilen The length of the input data.
*
*/ */
MBEDTLS_DEPRECATED void mbedtls_sha1_update( mbedtls_sha1_context *ctx, MBEDTLS_DEPRECATED void mbedtls_sha1_update( mbedtls_sha1_context *ctx,
const unsigned char *input, const unsigned char *input,
size_t ilen ); size_t ilen );
/** /**
* \brief SHA-1 final digest * \brief This function finishes the SHA-1 operation, and writes
* * the result to the output buffer.
* \deprecated Superseded by mbedtls_sha1_finish_ret() in 2.7.0
*
* \param ctx The SHA-1 context.
* \param output The SHA-1 checksum result.
* *
* \warning SHA-1 is considered a weak message digest and its use * \warning SHA-1 is considered a weak message digest and its use
* constitutes a security risk. We recommend considering * constitutes a security risk. We recommend considering
* stronger message digests instead. * stronger message digests instead.
* *
* \deprecated Superseded by mbedtls_sha1_finish_ret() in 2.7.0.
*
* \param ctx The SHA-1 context.
* \param output The SHA-1 checksum result.
*
*/ */
MBEDTLS_DEPRECATED void mbedtls_sha1_finish( mbedtls_sha1_context *ctx, MBEDTLS_DEPRECATED void mbedtls_sha1_finish( mbedtls_sha1_context *ctx,
unsigned char output[20] ); unsigned char output[20] );
/** /**
* \brief SHA-1 process data block (internal use only) * \brief SHA-1 process data block (internal use only).
*
* \deprecated Superseded by mbedtls_internal_sha1_process() in 2.7.0
*
* \param ctx The SHA-1 context.
* \param data The data block being processed.
* *
* \warning SHA-1 is considered a weak message digest and its use * \warning SHA-1 is considered a weak message digest and its use
* constitutes a security risk. We recommend considering * constitutes a security risk. We recommend considering
* stronger message digests instead. * stronger message digests instead.
* *
* \deprecated Superseded by mbedtls_internal_sha1_process() in 2.7.0.
*
* \param ctx The SHA-1 context.
* \param data The data block being processed.
*
*/ */
MBEDTLS_DEPRECATED void mbedtls_sha1_process( mbedtls_sha1_context *ctx, MBEDTLS_DEPRECATED void mbedtls_sha1_process( mbedtls_sha1_context *ctx,
const unsigned char data[64] ); const unsigned char data[64] );
@ -261,15 +264,15 @@ extern "C" {
* The SHA-1 result is calculated as * The SHA-1 result is calculated as
* output = SHA-1(input buffer). * output = SHA-1(input buffer).
* *
* \warning SHA-1 is considered a weak message digest and its use
* constitutes a security risk. We recommend considering
* stronger message digests instead.
*
* \param input The buffer holding the input data. * \param input The buffer holding the input data.
* \param ilen The length of the input data. * \param ilen The length of the input data.
* \param output The SHA-1 checksum result. * \param output The SHA-1 checksum result.
* *
* \return \c 0 if successful * \return \c 0 on success.
*
* \warning SHA-1 is considered a weak message digest and its use
* constitutes a security risk. We recommend considering
* stronger message digests instead.
* *
*/ */
int mbedtls_sha1_ret( const unsigned char *input, int mbedtls_sha1_ret( const unsigned char *input,
@ -283,7 +286,17 @@ int mbedtls_sha1_ret( const unsigned char *input,
#define MBEDTLS_DEPRECATED #define MBEDTLS_DEPRECATED
#endif #endif
/** /**
* \brief Output = SHA-1( input buffer ) * \brief This function calculates the SHA-1 checksum of a buffer.
*
* The function allocates the context, performs the
* calculation, and frees the context.
*
* The SHA-1 result is calculated as
* output = SHA-1(input buffer).
*
* \warning SHA-1 is considered a weak message digest and its use
* constitutes a security risk. We recommend considering
* stronger message digests instead.
* *
* \deprecated Superseded by mbedtls_sha1_ret() in 2.7.0 * \deprecated Superseded by mbedtls_sha1_ret() in 2.7.0
* *
@ -291,10 +304,6 @@ int mbedtls_sha1_ret( const unsigned char *input,
* \param ilen The length of the input data. * \param ilen The length of the input data.
* \param output The SHA-1 checksum result. * \param output The SHA-1 checksum result.
* *
* \warning SHA-1 is considered a weak message digest and its use
* constitutes a security risk. We recommend considering
* stronger message digests instead.
*
*/ */
MBEDTLS_DEPRECATED void mbedtls_sha1( const unsigned char *input, MBEDTLS_DEPRECATED void mbedtls_sha1( const unsigned char *input,
size_t ilen, size_t ilen,
@ -306,12 +315,13 @@ MBEDTLS_DEPRECATED void mbedtls_sha1( const unsigned char *input,
/** /**
* \brief The SHA-1 checkup routine. * \brief The SHA-1 checkup routine.
* *
* \return \c 0 on success, or \c 1 on failure.
*
* \warning SHA-1 is considered a weak message digest and its use * \warning SHA-1 is considered a weak message digest and its use
* constitutes a security risk. We recommend considering * constitutes a security risk. We recommend considering
* stronger message digests instead. * stronger message digests instead.
* *
* \return \c 0 on success.
* \return \c 1 on failure.
*
*/ */
int mbedtls_sha1_self_test( int verbose ); int mbedtls_sha1_self_test( int verbose );