common/mbedtls/sha1.h

   1 /**
   2  * \file sha1.h
   3  *
   4  * \brief This file contains SHA-1 definitions and functions.
   5  *
   6  * The Secure Hash Algorithm 1 (SHA-1) cryptographic hash function is defined in
   7  * <em>FIPS 180-4: Secure Hash Standard (SHS)</em>.
   8  *
   9  * \warning   SHA-1 is considered a weak message digest and its use constitutes
  10  *            a security risk. We recommend considering stronger message
  11  *            digests instead.
  12  */
  13 /*
  14  *  Copyright The Mbed TLS Contributors
  15  *  SPDX-License-Identifier: Apache-2.0
  16  *
  17  *  Licensed under the Apache License, Version 2.0 (the "License"); you may
  18  *  not use this file except in compliance with the License.
  19  *  You may obtain a copy of the License at
  20  *
  21  *  http://www.apache.org/licenses/LICENSE-2.0
  22  *
  23  *  Unless required by applicable law or agreed to in writing, software
  24  *  distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
  25  *  WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  26  *  See the License for the specific language governing permissions and
  27  *  limitations under the License.
  28  */
  29 #ifndef MBEDTLS_SHA1_H
  30 #define MBEDTLS_SHA1_H
  31
  32 #if !defined(MBEDTLS_CONFIG_FILE)
  33 #include "mbedtls/config.h"
  34 #else
  35 #include MBEDTLS_CONFIG_FILE
  36 #endif
  37
  38 #include <stddef.h>
  39 #include <stdint.h>
  40
  41 /* MBEDTLS_ERR_SHA1_HW_ACCEL_FAILED is deprecated and should not be used. */
  42 #define MBEDTLS_ERR_SHA1_HW_ACCEL_FAILED                  -0x0035  /**< SHA-1 hardware accelerator failed */
  43 #define MBEDTLS_ERR_SHA1_BAD_INPUT_DATA                   -0x0073  /**< SHA-1 input data was malformed. */
  44
  45 #ifdef __cplusplus
  46 extern "C" {
  47 #endif
  48
  49 #if !defined(MBEDTLS_SHA1_ALT)
  50 // Regular implementation
  51 //
  52
  53 /**
  54  * \brief          The SHA-1 context structure.
  55  *
  56  * \warning        SHA-1 is considered a weak message digest and its use
  57  *                 constitutes a security risk. We recommend considering
  58  *                 stronger message digests instead.
  59  *
  60  */
  61 typedef struct mbedtls_sha1_context {
  62     uint32_t total[2];          /*!< The number of Bytes processed.  */
  63     uint32_t state[5];          /*!< The intermediate digest state.  */
  64     unsigned char buffer[64];   /*!< The data block being processed. */
  65 }
  66 mbedtls_sha1_context;
  67
  68 #else  /* MBEDTLS_SHA1_ALT */
  69 #include "sha1_alt.h"
  70 #endif /* MBEDTLS_SHA1_ALT */
  71
  72 /**
  73  * \brief          This function initializes a SHA-1 context.
  74  *
  75  * \warning        SHA-1 is considered a weak message digest and its use
  76  *                 constitutes a security risk. We recommend considering
  77  *                 stronger message digests instead.
  78  *
  79  * \param ctx      The SHA-1 context to initialize.
  80  *                 This must not be \c NULL.
  81  *
  82  */
  83 void mbedtls_sha1_init(mbedtls_sha1_context *ctx);
  84
  85 /**
  86  * \brief          This function clears a SHA-1 context.
  87  *
  88  * \warning        SHA-1 is considered a weak message digest and its use
  89  *                 constitutes a security risk. We recommend considering
  90  *                 stronger message digests instead.
  91  *
  92  * \param ctx      The SHA-1 context to clear. This may be \c NULL,
  93  *                 in which case this function does nothing. If it is
  94  *                 not \c NULL, it must point to an initialized
  95  *                 SHA-1 context.
  96  *
  97  */
  98 void mbedtls_sha1_free(mbedtls_sha1_context *ctx);
  99
 100 /**
 101  * \brief          This function clones the state of a SHA-1 context.
 102  *
 103  * \warning        SHA-1 is considered a weak message digest and its use
 104  *                 constitutes a security risk. We recommend considering
 105  *                 stronger message digests instead.
 106  *
 107  * \param dst      The SHA-1 context to clone to. This must be initialized.
 108  * \param src      The SHA-1 context to clone from. This must be initialized.
 109  *
 110  */
 111 void mbedtls_sha1_clone(mbedtls_sha1_context *dst,
 112                         const mbedtls_sha1_context *src);
 113
 114 /**
 115  * \brief          This function starts a SHA-1 checksum calculation.
 116  *
 117  * \warning        SHA-1 is considered a weak message digest and its use
 118  *                 constitutes a security risk. We recommend considering
 119  *                 stronger message digests instead.
 120  *
 121  * \param ctx      The SHA-1 context to initialize. This must be initialized.
 122  *
 123  * \return         \c 0 on success.
 124  * \return         A negative error code on failure.
 125  *
 126  */
 127 int mbedtls_sha1_starts_ret(mbedtls_sha1_context *ctx);
 128
 129 /**
 130  * \brief          This function feeds an input buffer into an ongoing SHA-1
 131  *                 checksum calculation.
 132  *
 133  * \warning        SHA-1 is considered a weak message digest and its use
 134  *                 constitutes a security risk. We recommend considering
 135  *                 stronger message digests instead.
 136  *
 137  * \param ctx      The SHA-1 context. This must be initialized
 138  *                 and have a hash operation started.
 139  * \param input    The buffer holding the input data.
 140  *                 This must be a readable buffer of length \p ilen Bytes.
 141  * \param ilen     The length of the input data \p input in Bytes.
 142  *
 143  * \return         \c 0 on success.
 144  * \return         A negative error code on failure.
 145  */
 146 int mbedtls_sha1_update_ret(mbedtls_sha1_context *ctx,
 147                             const unsigned char *input,
 148                             size_t ilen);
 149
 150 /**
 151  * \brief          This function finishes the SHA-1 operation, and writes
 152  *                 the result to the output buffer.
 153  *
 154  * \warning        SHA-1 is considered a weak message digest and its use
 155  *                 constitutes a security risk. We recommend considering
 156  *                 stronger message digests instead.
 157  *
 158  * \param ctx      The SHA-1 context to use. This must be initialized and
 159  *                 have a hash operation started.
 160  * \param output   The SHA-1 checksum result. This must be a writable
 161  *                 buffer of length \c 20 Bytes.
 162  *
 163  * \return         \c 0 on success.
 164  * \return         A negative error code on failure.
 165  */
 166 int mbedtls_sha1_finish_ret(mbedtls_sha1_context *ctx,
 167                             unsigned char output[20]);
 168
 169 /**
 170  * \brief          SHA-1 process data block (internal use only).
 171  *
 172  * \warning        SHA-1 is considered a weak message digest and its use
 173  *                 constitutes a security risk. We recommend considering
 174  *                 stronger message digests instead.
 175  *
 176  * \param ctx      The SHA-1 context to use. This must be initialized.
 177  * \param data     The data block being processed. This must be a
 178  *                 readable buffer of length \c 64 Bytes.
 179  *
 180  * \return         \c 0 on success.
 181  * \return         A negative error code on failure.
 182  *
 183  */
 184 int mbedtls_internal_sha1_process(mbedtls_sha1_context *ctx,
 185                                   const unsigned char data[64]);
 186
 187 #if !defined(MBEDTLS_DEPRECATED_REMOVED)
 188 #if defined(MBEDTLS_DEPRECATED_WARNING)
 189 #define MBEDTLS_DEPRECATED      __attribute__((deprecated))
 190 #else
 191 #define MBEDTLS_DEPRECATED
 192 #endif
 193 /**
 194  * \brief          This function starts a SHA-1 checksum calculation.
 195  *
 196  * \warning        SHA-1 is considered a weak message digest and its use
 197  *                 constitutes a security risk. We recommend considering
 198  *                 stronger message digests instead.
 199  *
 200  * \deprecated     Superseded by mbedtls_sha1_starts_ret() in 2.7.0.
 201  *
 202  * \param ctx      The SHA-1 context to initialize. This must be initialized.
 203  *
 204  */
 205 MBEDTLS_DEPRECATED void mbedtls_sha1_starts(mbedtls_sha1_context *ctx);
 206
 207 /**
 208  * \brief          This function feeds an input buffer into an ongoing SHA-1
 209  *                 checksum calculation.
 210  *
 211  * \warning        SHA-1 is considered a weak message digest and its use
 212  *                 constitutes a security risk. We recommend considering
 213  *                 stronger message digests instead.
 214  *
 215  * \deprecated     Superseded by mbedtls_sha1_update_ret() in 2.7.0.
 216  *
 217  * \param ctx      The SHA-1 context. This must be initialized and
 218  *                 have a hash operation started.
 219  * \param input    The buffer holding the input data.
 220  *                 This must be a readable buffer of length \p ilen Bytes.
 221  * \param ilen     The length of the input data \p input in Bytes.
 222  *
 223  */
 224 MBEDTLS_DEPRECATED void mbedtls_sha1_update(mbedtls_sha1_context *ctx,
 225                                             const unsigned char *input,
 226                                             size_t ilen);
 227
 228 /**
 229  * \brief          This function finishes the SHA-1 operation, and writes
 230  *                 the result to the output buffer.
 231  *
 232  * \warning        SHA-1 is considered a weak message digest and its use
 233  *                 constitutes a security risk. We recommend considering
 234  *                 stronger message digests instead.
 235  *
 236  * \deprecated     Superseded by mbedtls_sha1_finish_ret() in 2.7.0.
 237  *
 238  * \param ctx      The SHA-1 context. This must be initialized and
 239  *                 have a hash operation started.
 240  * \param output   The SHA-1 checksum result.
 241  *                 This must be a writable buffer of length \c 20 Bytes.
 242  */
 243 MBEDTLS_DEPRECATED void mbedtls_sha1_finish(mbedtls_sha1_context *ctx,
 244                                             unsigned char output[20]);
 245
 246 /**
 247  * \brief          SHA-1 process data block (internal use only).
 248  *
 249  * \warning        SHA-1 is considered a weak message digest and its use
 250  *                 constitutes a security risk. We recommend considering
 251  *                 stronger message digests instead.
 252  *
 253  * \deprecated     Superseded by mbedtls_internal_sha1_process() in 2.7.0.
 254  *
 255  * \param ctx      The SHA-1 context. This must be initialized.
 256  * \param data     The data block being processed.
 257  *                 This must be a readable buffer of length \c 64 bytes.
 258  *
 259  */
 260 MBEDTLS_DEPRECATED void mbedtls_sha1_process(mbedtls_sha1_context *ctx,
 261                                              const unsigned char data[64]);
 262
 263 #undef MBEDTLS_DEPRECATED
 264 #endif /* !MBEDTLS_DEPRECATED_REMOVED */
 265
 266 /**
 267  * \brief          This function calculates the SHA-1 checksum of a buffer.
 268  *
 269  *                 The function allocates the context, performs the
 270  *                 calculation, and frees the context.
 271  *
 272  *                 The SHA-1 result is calculated as
 273  *                 output = SHA-1(input buffer).
 274  *
 275  * \warning        SHA-1 is considered a weak message digest and its use
 276  *                 constitutes a security risk. We recommend considering
 277  *                 stronger message digests instead.
 278  *
 279  * \param input    The buffer holding the input data.
 280  *                 This must be a readable buffer of length \p ilen Bytes.
 281  * \param ilen     The length of the input data \p input in Bytes.
 282  * \param output   The SHA-1 checksum result.
 283  *                 This must be a writable buffer of length \c 20 Bytes.
 284  *
 285  * \return         \c 0 on success.
 286  * \return         A negative error code on failure.
 287  *
 288  */
 289 int mbedtls_sha1_ret(const unsigned char *input,
 290                      size_t ilen,
 291                      unsigned char output[20]);
 292
 293 #if !defined(MBEDTLS_DEPRECATED_REMOVED)
 294 #if defined(MBEDTLS_DEPRECATED_WARNING)
 295 #define MBEDTLS_DEPRECATED      __attribute__((deprecated))
 296 #else
 297 #define MBEDTLS_DEPRECATED
 298 #endif
 299 /**
 300  * \brief          This function calculates the SHA-1 checksum of a buffer.
 301  *
 302  *                 The function allocates the context, performs the
 303  *                 calculation, and frees the context.
 304  *
 305  *                 The SHA-1 result is calculated as
 306  *                 output = SHA-1(input buffer).
 307  *
 308  * \warning        SHA-1 is considered a weak message digest and its use
 309  *                 constitutes a security risk. We recommend considering
 310  *                 stronger message digests instead.
 311  *
 312  * \deprecated     Superseded by mbedtls_sha1_ret() in 2.7.0
 313  *
 314  * \param input    The buffer holding the input data.
 315  *                 This must be a readable buffer of length \p ilen Bytes.
 316  * \param ilen     The length of the input data \p input in Bytes.
 317  * \param output   The SHA-1 checksum result. This must be a writable
 318  *                 buffer of size \c 20 Bytes.
 319  *
 320  */
 321 MBEDTLS_DEPRECATED void mbedtls_sha1(const unsigned char *input,
 322                                      size_t ilen,
 323                                      unsigned char output[20]);
 324
 325 #undef MBEDTLS_DEPRECATED
 326 #endif /* !MBEDTLS_DEPRECATED_REMOVED */
 327
 328 #if defined(MBEDTLS_SELF_TEST)
 329
 330 /**
 331  * \brief          The SHA-1 checkup routine.
 332  *
 333  * \warning        SHA-1 is considered a weak message digest and its use
 334  *                 constitutes a security risk. We recommend considering
 335  *                 stronger message digests instead.
 336  *
 337  * \return         \c 0 on success.
 338  * \return         \c 1 on failure.
 339  *
 340  */
 341 int mbedtls_sha1_self_test(int verbose);
 342
 343 #endif /* MBEDTLS_SELF_TEST */
 344
 345 #ifdef __cplusplus
 346 }
 347 #endif
 348
 349 #endif /* mbedtls_sha1.h */