git.sur5r.net Git - freertos/blob - FreeRTOS-Labs/Source/mbedtls/include/mbedtls/sha256.h

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