include/mbedtls/sha1.h

0001 /**
0002  * \file sha1.h
0003  *
0004  * \brief This file contains SHA-1 definitions and functions.
0005  *
0006  * The Secure Hash Algorithm 1 (SHA-1) cryptographic hash function is defined in
0007  * <em>FIPS 180-4: Secure Hash Standard (SHS)</em>.
0008  *
0009  * \warning   SHA-1 is considered a weak message digest and its use constitutes
0010  *            a security risk. We recommend considering stronger message
0011  *            digests instead.
0012  */
0013 /*
0014  *  Copyright The Mbed TLS Contributors
0015  *  SPDX-License-Identifier: Apache-2.0 OR GPL-2.0-or-later
0016  */
0017 #ifndef MBEDTLS_SHA1_H
0018 #define MBEDTLS_SHA1_H
0019 #include "mbedtls/private_access.h"
0020
0021 #include "mbedtls/build_info.h"
0022
0023 #include <stddef.h>
0024 #include <stdint.h>
0025
0026 /** SHA-1 input data was malformed. */
0027 #define MBEDTLS_ERR_SHA1_BAD_INPUT_DATA                   -0x0073
0028
0029 #ifdef __cplusplus
0030 extern "C" {
0031 #endif
0032
0033 #if !defined(MBEDTLS_SHA1_ALT)
0034 // Regular implementation
0035 //
0036
0037 /**
0038  * \brief          The SHA-1 context structure.
0039  *
0040  * \warning        SHA-1 is considered a weak message digest and its use
0041  *                 constitutes a security risk. We recommend considering
0042  *                 stronger message digests instead.
0043  *
0044  */
0045 typedef struct mbedtls_sha1_context {
0046     uint32_t MBEDTLS_PRIVATE(total)[2];          /*!< The number of Bytes processed.  */
0047     uint32_t MBEDTLS_PRIVATE(state)[5];          /*!< The intermediate digest state.  */
0048     unsigned char MBEDTLS_PRIVATE(buffer)[64];   /*!< The data block being processed. */
0049 }
0050 mbedtls_sha1_context;
0051
0052 #else  /* MBEDTLS_SHA1_ALT */
0053 #include "sha1_alt.h"
0054 #endif /* MBEDTLS_SHA1_ALT */
0055
0056 /**
0057  * \brief          This function initializes a SHA-1 context.
0058  *
0059  * \warning        SHA-1 is considered a weak message digest and its use
0060  *                 constitutes a security risk. We recommend considering
0061  *                 stronger message digests instead.
0062  *
0063  * \param ctx      The SHA-1 context to initialize.
0064  *                 This must not be \c NULL.
0065  *
0066  */
0067 void mbedtls_sha1_init(mbedtls_sha1_context *ctx);
0068
0069 /**
0070  * \brief          This function clears a SHA-1 context.
0071  *
0072  * \warning        SHA-1 is considered a weak message digest and its use
0073  *                 constitutes a security risk. We recommend considering
0074  *                 stronger message digests instead.
0075  *
0076  * \param ctx      The SHA-1 context to clear. This may be \c NULL,
0077  *                 in which case this function does nothing. If it is
0078  *                 not \c NULL, it must point to an initialized
0079  *                 SHA-1 context.
0080  *
0081  */
0082 void mbedtls_sha1_free(mbedtls_sha1_context *ctx);
0083
0084 /**
0085  * \brief          This function clones the state of a SHA-1 context.
0086  *
0087  * \warning        SHA-1 is considered a weak message digest and its use
0088  *                 constitutes a security risk. We recommend considering
0089  *                 stronger message digests instead.
0090  *
0091  * \param dst      The SHA-1 context to clone to. This must be initialized.
0092  * \param src      The SHA-1 context to clone from. This must be initialized.
0093  *
0094  */
0095 void mbedtls_sha1_clone(mbedtls_sha1_context *dst,
0096                         const mbedtls_sha1_context *src);
0097
0098 /**
0099  * \brief          This function starts a SHA-1 checksum calculation.
0100  *
0101  * \warning        SHA-1 is considered a weak message digest and its use
0102  *                 constitutes a security risk. We recommend considering
0103  *                 stronger message digests instead.
0104  *
0105  * \param ctx      The SHA-1 context to initialize. This must be initialized.
0106  *
0107  * \return         \c 0 on success.
0108  * \return         A negative error code on failure.
0109  *
0110  */
0111 int mbedtls_sha1_starts(mbedtls_sha1_context *ctx);
0112
0113 /**
0114  * \brief          This function feeds an input buffer into an ongoing SHA-1
0115  *                 checksum calculation.
0116  *
0117  * \warning        SHA-1 is considered a weak message digest and its use
0118  *                 constitutes a security risk. We recommend considering
0119  *                 stronger message digests instead.
0120  *
0121  * \param ctx      The SHA-1 context. This must be initialized
0122  *                 and have a hash operation started.
0123  * \param input    The buffer holding the input data.
0124  *                 This must be a readable buffer of length \p ilen Bytes.
0125  * \param ilen     The length of the input data \p input in Bytes.
0126  *
0127  * \return         \c 0 on success.
0128  * \return         A negative error code on failure.
0129  */
0130 int mbedtls_sha1_update(mbedtls_sha1_context *ctx,
0131                         const unsigned char *input,
0132                         size_t ilen);
0133
0134 /**
0135  * \brief          This function finishes the SHA-1 operation, and writes
0136  *                 the result to the output buffer.
0137  *
0138  * \warning        SHA-1 is considered a weak message digest and its use
0139  *                 constitutes a security risk. We recommend considering
0140  *                 stronger message digests instead.
0141  *
0142  * \param ctx      The SHA-1 context to use. This must be initialized and
0143  *                 have a hash operation started.
0144  * \param output   The SHA-1 checksum result. This must be a writable
0145  *                 buffer of length \c 20 Bytes.
0146  *
0147  * \return         \c 0 on success.
0148  * \return         A negative error code on failure.
0149  */
0150 int mbedtls_sha1_finish(mbedtls_sha1_context *ctx,
0151                         unsigned char output[20]);
0152
0153 /**
0154  * \brief          SHA-1 process data block (internal use only).
0155  *
0156  * \warning        SHA-1 is considered a weak message digest and its use
0157  *                 constitutes a security risk. We recommend considering
0158  *                 stronger message digests instead.
0159  *
0160  * \param ctx      The SHA-1 context to use. This must be initialized.
0161  * \param data     The data block being processed. This must be a
0162  *                 readable buffer of length \c 64 Bytes.
0163  *
0164  * \return         \c 0 on success.
0165  * \return         A negative error code on failure.
0166  *
0167  */
0168 int mbedtls_internal_sha1_process(mbedtls_sha1_context *ctx,
0169                                   const unsigned char data[64]);
0170
0171 /**
0172  * \brief          This function calculates the SHA-1 checksum of a buffer.
0173  *
0174  *                 The function allocates the context, performs the
0175  *                 calculation, and frees the context.
0176  *
0177  *                 The SHA-1 result is calculated as
0178  *                 output = SHA-1(input buffer).
0179  *
0180  * \warning        SHA-1 is considered a weak message digest and its use
0181  *                 constitutes a security risk. We recommend considering
0182  *                 stronger message digests instead.
0183  *
0184  * \param input    The buffer holding the input data.
0185  *                 This must be a readable buffer of length \p ilen Bytes.
0186  * \param ilen     The length of the input data \p input in Bytes.
0187  * \param output   The SHA-1 checksum result.
0188  *                 This must be a writable buffer of length \c 20 Bytes.
0189  *
0190  * \return         \c 0 on success.
0191  * \return         A negative error code on failure.
0192  *
0193  */
0194 int mbedtls_sha1(const unsigned char *input,
0195                  size_t ilen,
0196                  unsigned char output[20]);
0197
0198 #if defined(MBEDTLS_SELF_TEST)
0199
0200 /**
0201  * \brief          The SHA-1 checkup routine.
0202  *
0203  * \warning        SHA-1 is considered a weak message digest and its use
0204  *                 constitutes a security risk. We recommend considering
0205  *                 stronger message digests instead.
0206  *
0207  * \return         \c 0 on success.
0208  * \return         \c 1 on failure.
0209  *
0210  */
0211 int mbedtls_sha1_self_test(int verbose);
0212
0213 #endif /* MBEDTLS_SELF_TEST */
0214
0215 #ifdef __cplusplus
0216 }
0217 #endif
0218
0219 #endif /* mbedtls_sha1.h */