common/mbedtls/sha256.h

   1 /**
   2  * \file sha256.h
   3  *
   4  * \brief This file contains SHA-224 and SHA-256 definitions and functions.
   5  *
   6  * The Secure Hash Algorithms 224 and 256 (SHA-224 and SHA-256) cryptographic
   7  * hash functions are defined in <em>FIPS 180-4: Secure Hash Standard (SHS)</em>.
   8  */
   9 /*
  10  *  Copyright The Mbed TLS Contributors
  11  *  SPDX-License-Identifier: Apache-2.0
  12  *
  13  *  Licensed under the Apache License, Version 2.0 (the "License"); you may
  14  *  not use this file except in compliance with the License.
  15  *  You may obtain a copy of the License at
  16  *
  17  *  http://www.apache.org/licenses/LICENSE-2.0
  18  *
  19  *  Unless required by applicable law or agreed to in writing, software
  20  *  distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
  21  *  WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  22  *  See the License for the specific language governing permissions and
  23  *  limitations under the License.
  24  */
  25 #ifndef MBEDTLS_SHA256_H
  26 #define MBEDTLS_SHA256_H
  27
  28 #if !defined(MBEDTLS_CONFIG_FILE)
  29 #include "mbedtls/config.h"
  30 #else
  31 #include MBEDTLS_CONFIG_FILE
  32 #endif
  33
  34 #include <stddef.h>
  35 #include <stdint.h>
  36
  37 /* MBEDTLS_ERR_SHA256_HW_ACCEL_FAILED is deprecated and should not be used. */
  38 #define MBEDTLS_ERR_SHA256_HW_ACCEL_FAILED                -0x0037  /**< SHA-256 hardware accelerator failed */
  39 #define MBEDTLS_ERR_SHA256_BAD_INPUT_DATA                 -0x0074  /**< SHA-256 input data was malformed. */
  40
  41 #ifdef __cplusplus
  42 extern "C" {
  43 #endif
  44
  45 #if !defined(MBEDTLS_SHA256_ALT)
  46 // Regular implementation
  47 //
  48
  49 /**
  50  * \brief          The SHA-256 context structure.
  51  *
  52  *                 The structure is used both for SHA-256 and for SHA-224
  53  *                 checksum calculations. The choice between these two is
  54  *                 made in the call to mbedtls_sha256_starts_ret().
  55  */
  56 typedef struct mbedtls_sha256_context {
  57     uint32_t total[2];          /*!< The number of Bytes processed.  */
  58     uint32_t state[8];          /*!< The intermediate digest state.  */
  59     unsigned char buffer[64];   /*!< The data block being processed. */
  60     int is224;                  /*!< Determines which function to use:
  61                                      0: Use SHA-256, or 1: Use SHA-224. */
  62 }
  63 mbedtls_sha256_context;
  64
  65 #else  /* MBEDTLS_SHA256_ALT */
  66 #include "sha256_alt.h"
  67 #endif /* MBEDTLS_SHA256_ALT */
  68
  69 /**
  70  * \brief          This function initializes a SHA-256 context.
  71  *
  72  * \param ctx      The SHA-256 context to initialize. This must not be \c NULL.
  73  */
  74 void mbedtls_sha256_init(mbedtls_sha256_context *ctx);
  75
  76 /**
  77  * \brief          This function clears a SHA-256 context.
  78  *
  79  * \param ctx      The SHA-256 context to clear. This may be \c NULL, in which
  80  *                 case this function returns immediately. If it is not \c NULL,
  81  *                 it must point to an initialized SHA-256 context.
  82  */
  83 void mbedtls_sha256_free(mbedtls_sha256_context *ctx);
  84
  85 /**
  86  * \brief          This function clones the state of a SHA-256 context.
  87  *
  88  * \param dst      The destination context. This must be initialized.
  89  * \param src      The context to clone. This must be initialized.
  90  */
  91 void mbedtls_sha256_clone(mbedtls_sha256_context *dst,
  92                           const mbedtls_sha256_context *src);
  93
  94 /**
  95  * \brief          This function starts a SHA-224 or SHA-256 checksum
  96  *                 calculation.
  97  *
  98  * \param ctx      The context to use. This must be initialized.
  99  * \param is224    This determines which function to use. This must be
 100  *                 either \c 0 for SHA-256, or \c 1 for SHA-224.
 101  *
 102  * \return         \c 0 on success.
 103  * \return         A negative error code on failure.
 104  */
 105 int mbedtls_sha256_starts_ret(mbedtls_sha256_context *ctx, int is224);
 106
 107 /**
 108  * \brief          This function feeds an input buffer into an ongoing
 109  *                 SHA-256 checksum calculation.
 110  *
 111  * \param ctx      The SHA-256 context. This must be initialized
 112  *                 and have a hash operation started.
 113  * \param input    The buffer holding the data. This must be a readable
 114  *                 buffer of length \p ilen Bytes.
 115  * \param ilen     The length of the input data in Bytes.
 116  *
 117  * \return         \c 0 on success.
 118  * \return         A negative error code on failure.
 119  */
 120 int mbedtls_sha256_update_ret(mbedtls_sha256_context *ctx,
 121                               const unsigned char *input,
 122                               size_t ilen);
 123
 124 /**
 125  * \brief          This function finishes the SHA-256 operation, and writes
 126  *                 the result to the output buffer.
 127  *
 128  * \param ctx      The SHA-256 context. This must be initialized
 129  *                 and have a hash operation started.
 130  * \param output   The SHA-224 or SHA-256 checksum result.
 131  *                 This must be a writable buffer of length \c 32 Bytes.
 132  *
 133  * \return         \c 0 on success.
 134  * \return         A negative error code on failure.
 135  */
 136 int mbedtls_sha256_finish_ret(mbedtls_sha256_context *ctx,
 137                               unsigned char output[32]);
 138
 139 /**
 140  * \brief          This function processes a single data block within
 141  *                 the ongoing SHA-256 computation. This function is for
 142  *                 internal use only.
 143  *
 144  * \param ctx      The SHA-256 context. This must be initialized.
 145  * \param data     The buffer holding one block of data. This must
 146  *                 be a readable buffer of length \c 64 Bytes.
 147  *
 148  * \return         \c 0 on success.
 149  * \return         A negative error code on failure.
 150  */
 151 int mbedtls_internal_sha256_process(mbedtls_sha256_context *ctx,
 152                                     const unsigned char data[64]);
 153
 154 #if !defined(MBEDTLS_DEPRECATED_REMOVED)
 155 #if defined(MBEDTLS_DEPRECATED_WARNING)
 156 #define MBEDTLS_DEPRECATED      __attribute__((deprecated))
 157 #else
 158 #define MBEDTLS_DEPRECATED
 159 #endif
 160 /**
 161  * \brief          This function starts a SHA-224 or SHA-256 checksum
 162  *                 calculation.
 163  *
 164  * \deprecated     Superseded by mbedtls_sha256_starts_ret() in 2.7.0.
 165  *
 166  * \param ctx      The context to use. This must be initialized.
 167  * \param is224    Determines which function to use. This must be
 168  *                 either \c 0 for SHA-256, or \c 1 for SHA-224.
 169  */
 170 MBEDTLS_DEPRECATED void mbedtls_sha256_starts(mbedtls_sha256_context *ctx,
 171                                               int is224);
 172
 173 /**
 174  * \brief          This function feeds an input buffer into an ongoing
 175  *                 SHA-256 checksum calculation.
 176  *
 177  * \deprecated     Superseded by mbedtls_sha256_update_ret() in 2.7.0.
 178  *
 179  * \param ctx      The SHA-256 context to use. This must be
 180  *                 initialized and have a hash operation started.
 181  * \param input    The buffer holding the data. This must be a readable
 182  *                 buffer of length \p ilen Bytes.
 183  * \param ilen     The length of the input data in Bytes.
 184  */
 185 MBEDTLS_DEPRECATED void mbedtls_sha256_update(mbedtls_sha256_context *ctx,
 186                                               const unsigned char *input,
 187                                               size_t ilen);
 188
 189 /**
 190  * \brief          This function finishes the SHA-256 operation, and writes
 191  *                 the result to the output buffer.
 192  *
 193  * \deprecated     Superseded by mbedtls_sha256_finish_ret() in 2.7.0.
 194  *
 195  * \param ctx      The SHA-256 context. This must be initialized and
 196  *                 have a hash operation started.
 197  * \param output   The SHA-224 or SHA-256 checksum result. This must be
 198  *                 a writable buffer of length \c 32 Bytes.
 199  */
 200 MBEDTLS_DEPRECATED void mbedtls_sha256_finish(mbedtls_sha256_context *ctx,
 201                                               unsigned char output[32]);
 202
 203 /**
 204  * \brief          This function processes a single data block within
 205  *                 the ongoing SHA-256 computation. This function is for
 206  *                 internal use only.
 207  *
 208  * \deprecated     Superseded by mbedtls_internal_sha256_process() in 2.7.0.
 209  *
 210  * \param ctx      The SHA-256 context. This must be initialized.
 211  * \param data     The buffer holding one block of data. This must be
 212  *                 a readable buffer of size \c 64 Bytes.
 213  */
 214 MBEDTLS_DEPRECATED void mbedtls_sha256_process(mbedtls_sha256_context *ctx,
 215                                                const unsigned char data[64]);
 216
 217 #undef MBEDTLS_DEPRECATED
 218 #endif /* !MBEDTLS_DEPRECATED_REMOVED */
 219
 220 /**
 221  * \brief          This function calculates the SHA-224 or SHA-256
 222  *                 checksum of a buffer.
 223  *
 224  *                 The function allocates the context, performs the
 225  *                 calculation, and frees the context.
 226  *
 227  *                 The SHA-256 result is calculated as
 228  *                 output = SHA-256(input buffer).
 229  *
 230  * \param input    The buffer holding the data. This must be a readable
 231  *                 buffer of length \p ilen Bytes.
 232  * \param ilen     The length of the input data in Bytes.
 233  * \param output   The SHA-224 or SHA-256 checksum result. This must
 234  *                 be a writable buffer of length \c 32 Bytes.
 235  * \param is224    Determines which function to use. This must be
 236  *                 either \c 0 for SHA-256, or \c 1 for SHA-224.
 237  */
 238 int mbedtls_sha256_ret(const unsigned char *input,
 239                        size_t ilen,
 240                        unsigned char output[32],
 241                        int is224);
 242
 243 #if !defined(MBEDTLS_DEPRECATED_REMOVED)
 244 #if defined(MBEDTLS_DEPRECATED_WARNING)
 245 #define MBEDTLS_DEPRECATED      __attribute__((deprecated))
 246 #else
 247 #define MBEDTLS_DEPRECATED
 248 #endif
 249
 250 /**
 251  * \brief          This function calculates the SHA-224 or SHA-256 checksum
 252  *                 of a buffer.
 253  *
 254  *                 The function allocates the context, performs the
 255  *                 calculation, and frees the context.
 256  *
 257  *                 The SHA-256 result is calculated as
 258  *                 output = SHA-256(input buffer).
 259  *
 260  * \deprecated     Superseded by mbedtls_sha256_ret() in 2.7.0.
 261  *
 262  * \param input    The buffer holding the data. This must be a readable
 263  *                 buffer of length \p ilen Bytes.
 264  * \param ilen     The length of the input data in Bytes.
 265  * \param output   The SHA-224 or SHA-256 checksum result. This must be
 266  *                 a writable buffer of length \c 32 Bytes.
 267  * \param is224    Determines which function to use. This must be either
 268  *                 \c 0 for SHA-256, or \c 1 for SHA-224.
 269  */
 270 MBEDTLS_DEPRECATED void mbedtls_sha256(const unsigned char *input,
 271                                        size_t ilen,
 272                                        unsigned char output[32],
 273                                        int is224);
 274
 275 #undef MBEDTLS_DEPRECATED
 276 #endif /* !MBEDTLS_DEPRECATED_REMOVED */
 277
 278 #if defined(MBEDTLS_SELF_TEST)
 279
 280 /**
 281  * \brief          The SHA-224 and SHA-256 checkup routine.
 282  *
 283  * \return         \c 0 on success.
 284  * \return         \c 1 on failure.
 285  */
 286 int mbedtls_sha256_self_test(int verbose);
 287
 288 #endif /* MBEDTLS_SELF_TEST */
 289
 290 #ifdef __cplusplus
 291 }
 292 #endif
 293
 294 #endif /* mbedtls_sha256.h */