mbedtls/private/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 "tf-psa-crypto/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                   PSA_ERROR_INVALID_ARGUMENT
0028
0029 #ifdef __cplusplus
0030 extern "C" {
0031 #endif
0032
0033 /**
0034  * \brief          The SHA-1 context structure.
0035  *
0036  * \warning        SHA-1 is considered a weak message digest and its use
0037  *                 constitutes a security risk. We recommend considering
0038  *                 stronger message digests instead.
0039  *
0040  */
0041 typedef struct mbedtls_sha1_context {
0042     uint32_t MBEDTLS_PRIVATE(total)[2];          /*!< The number of Bytes processed.  */
0043     uint32_t MBEDTLS_PRIVATE(state)[5];          /*!< The intermediate digest state.  */
0044     unsigned char MBEDTLS_PRIVATE(buffer)[64];   /*!< The data block being processed. */
0045 }
0046 mbedtls_sha1_context;
0047
0048 #if defined(MBEDTLS_DECLARE_PRIVATE_IDENTIFIERS)
0049 /**
0050  * \brief          This function initializes a SHA-1 context.
0051  *
0052  * \warning        SHA-1 is considered a weak message digest and its use
0053  *                 constitutes a security risk. We recommend considering
0054  *                 stronger message digests instead.
0055  *
0056  * \param ctx      The SHA-1 context to initialize.
0057  *                 This must not be \c NULL.
0058  *
0059  */
0060 void mbedtls_sha1_init(mbedtls_sha1_context *ctx);
0061
0062 /**
0063  * \brief          This function clears a SHA-1 context.
0064  *
0065  * \warning        SHA-1 is considered a weak message digest and its use
0066  *                 constitutes a security risk. We recommend considering
0067  *                 stronger message digests instead.
0068  *
0069  * \param ctx      The SHA-1 context to clear. This may be \c NULL,
0070  *                 in which case this function does nothing. If it is
0071  *                 not \c NULL, it must point to an initialized
0072  *                 SHA-1 context.
0073  *
0074  */
0075 void mbedtls_sha1_free(mbedtls_sha1_context *ctx);
0076
0077 /**
0078  * \brief          This function clones the state of a SHA-1 context.
0079  *
0080  * \warning        SHA-1 is considered a weak message digest and its use
0081  *                 constitutes a security risk. We recommend considering
0082  *                 stronger message digests instead.
0083  *
0084  * \param dst      The SHA-1 context to clone to. This must be initialized.
0085  * \param src      The SHA-1 context to clone from. This must be initialized.
0086  *
0087  */
0088 void mbedtls_sha1_clone(mbedtls_sha1_context *dst,
0089                         const mbedtls_sha1_context *src);
0090
0091 /**
0092  * \brief          This function starts a SHA-1 checksum calculation.
0093  *
0094  * \warning        SHA-1 is considered a weak message digest and its use
0095  *                 constitutes a security risk. We recommend considering
0096  *                 stronger message digests instead.
0097  *
0098  * \param ctx      The SHA-1 context to initialize. This must be initialized.
0099  *
0100  * \return         \c 0 on success.
0101  * \return         A negative error code on failure.
0102  *
0103  */
0104 int mbedtls_sha1_starts(mbedtls_sha1_context *ctx);
0105
0106 /**
0107  * \brief          This function feeds an input buffer into an ongoing SHA-1
0108  *                 checksum calculation.
0109  *
0110  * \warning        SHA-1 is considered a weak message digest and its use
0111  *                 constitutes a security risk. We recommend considering
0112  *                 stronger message digests instead.
0113  *
0114  * \param ctx      The SHA-1 context. This must be initialized
0115  *                 and have a hash operation started.
0116  * \param input    The buffer holding the input data.
0117  *                 This must be a readable buffer of length \p ilen Bytes.
0118  * \param ilen     The length of the input data \p input in Bytes.
0119  *
0120  * \return         \c 0 on success.
0121  * \return         A negative error code on failure.
0122  */
0123 int mbedtls_sha1_update(mbedtls_sha1_context *ctx,
0124                         const unsigned char *input,
0125                         size_t ilen);
0126
0127 /**
0128  * \brief          This function finishes the SHA-1 operation, and writes
0129  *                 the result to the output buffer.
0130  *
0131  * \warning        SHA-1 is considered a weak message digest and its use
0132  *                 constitutes a security risk. We recommend considering
0133  *                 stronger message digests instead.
0134  *
0135  * \param ctx      The SHA-1 context to use. This must be initialized and
0136  *                 have a hash operation started.
0137  * \param output   The SHA-1 checksum result. This must be a writable
0138  *                 buffer of length \c 20 Bytes.
0139  *
0140  * \return         \c 0 on success.
0141  * \return         A negative error code on failure.
0142  */
0143 int mbedtls_sha1_finish(mbedtls_sha1_context *ctx,
0144                         unsigned char output[20]);
0145
0146 /**
0147  * \brief          This function calculates the SHA-1 checksum of a buffer.
0148  *
0149  *                 The function allocates the context, performs the
0150  *                 calculation, and frees the context.
0151  *
0152  *                 The SHA-1 result is calculated as
0153  *                 output = SHA-1(input buffer).
0154  *
0155  * \warning        SHA-1 is considered a weak message digest and its use
0156  *                 constitutes a security risk. We recommend considering
0157  *                 stronger message digests instead.
0158  *
0159  * \param input    The buffer holding the input data.
0160  *                 This must be a readable buffer of length \p ilen Bytes.
0161  * \param ilen     The length of the input data \p input in Bytes.
0162  * \param output   The SHA-1 checksum result.
0163  *                 This must be a writable buffer of length \c 20 Bytes.
0164  *
0165  * \return         \c 0 on success.
0166  * \return         A negative error code on failure.
0167  *
0168  */
0169 int mbedtls_sha1(const unsigned char *input,
0170                  size_t ilen,
0171                  unsigned char output[20]);
0172
0173 #if defined(MBEDTLS_SELF_TEST)
0174
0175 /**
0176  * \brief          The SHA-1 checkup routine.
0177  *
0178  * \warning        SHA-1 is considered a weak message digest and its use
0179  *                 constitutes a security risk. We recommend considering
0180  *                 stronger message digests instead.
0181  *
0182  * \return         \c 0 on success.
0183  * \return         \c 1 on failure.
0184  *
0185  */
0186 int mbedtls_sha1_self_test(int verbose);
0187
0188 #endif /* MBEDTLS_SELF_TEST */
0189
0190 #endif /* MBEDTLS_DECLARE_PRIVATE_IDENTIFIERS */
0191
0192 #ifdef __cplusplus
0193 }
0194 #endif
0195
0196 #endif /* mbedtls_sha1.h */