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 { 58 uint32_t total[2]; /*!< The number of Bytes processed. */ 59 uint32_t state[8]; /*!< The intermediate digest state. */ 60 unsigned char buffer[64]; /*!< The data block being processed. */ 61 int is224; /*!< Determines which function to use: 62 0: Use SHA-256, or 1: Use SHA-224. */ 63 } 64 mbedtls_sha256_context; 65 66 #else /* MBEDTLS_SHA256_ALT */ 67 #include "sha256_alt.h" 68 #endif /* MBEDTLS_SHA256_ALT */ 69 70 /** 71 * \brief This function initializes a SHA-256 context. 72 * 73 * \param ctx The SHA-256 context to initialize. This must not be \c NULL. 74 */ 75 void mbedtls_sha256_init( mbedtls_sha256_context *ctx ); 76 77 /** 78 * \brief This function clears a SHA-256 context. 79 * 80 * \param ctx The SHA-256 context to clear. This may be \c NULL, in which 81 * case this function returns immediately. If it is not \c NULL, 82 * it must point to an initialized SHA-256 context. 83 */ 84 void mbedtls_sha256_free( mbedtls_sha256_context *ctx ); 85 86 /** 87 * \brief This function clones the state of a SHA-256 context. 88 * 89 * \param dst The destination context. This must be initialized. 90 * \param src The context to clone. This must be initialized. 91 */ 92 void mbedtls_sha256_clone( mbedtls_sha256_context *dst, 93 const mbedtls_sha256_context *src ); 94 95 /** 96 * \brief This function starts a SHA-224 or SHA-256 checksum 97 * calculation. 98 * 99 * \param ctx The context to use. This must be initialized. 100 * \param is224 This determines which function to use. This must be 101 * either \c 0 for SHA-256, or \c 1 for SHA-224. 102 * 103 * \return \c 0 on success. 104 * \return A negative error code on failure. 105 */ 106 int mbedtls_sha256_starts_ret( mbedtls_sha256_context *ctx, int is224 ); 107 108 /** 109 * \brief This function feeds an input buffer into an ongoing 110 * SHA-256 checksum calculation. 111 * 112 * \param ctx The SHA-256 context. This must be initialized 113 * and have a hash operation started. 114 * \param input The buffer holding the data. This must be a readable 115 * buffer of length \p ilen Bytes. 116 * \param ilen The length of the input data in Bytes. 117 * 118 * \return \c 0 on success. 119 * \return A negative error code on failure. 120 */ 121 int mbedtls_sha256_update_ret( mbedtls_sha256_context *ctx, 122 const unsigned char *input, 123 size_t ilen ); 124 125 /** 126 * \brief This function finishes the SHA-256 operation, and writes 127 * the result to the output buffer. 128 * 129 * \param ctx The SHA-256 context. This must be initialized 130 * and have a hash operation started. 131 * \param output The SHA-224 or SHA-256 checksum result. 132 * This must be a writable buffer of length \c 32 Bytes. 133 * 134 * \return \c 0 on success. 135 * \return A negative error code on failure. 136 */ 137 int mbedtls_sha256_finish_ret( mbedtls_sha256_context *ctx, 138 unsigned char output[32] ); 139 140 /** 141 * \brief This function processes a single data block within 142 * the ongoing SHA-256 computation. This function is for 143 * internal use only. 144 * 145 * \param ctx The SHA-256 context. This must be initialized. 146 * \param data The buffer holding one block of data. This must 147 * be a readable buffer of length \c 64 Bytes. 148 * 149 * \return \c 0 on success. 150 * \return A negative error code on failure. 151 */ 152 int mbedtls_internal_sha256_process( mbedtls_sha256_context *ctx, 153 const unsigned char data[64] ); 154 155 #if !defined(MBEDTLS_DEPRECATED_REMOVED) 156 #if defined(MBEDTLS_DEPRECATED_WARNING) 157 #define MBEDTLS_DEPRECATED __attribute__((deprecated)) 158 #else 159 #define MBEDTLS_DEPRECATED 160 #endif 161 /** 162 * \brief This function starts a SHA-224 or SHA-256 checksum 163 * calculation. 164 * 165 * \deprecated Superseded by mbedtls_sha256_starts_ret() in 2.7.0. 166 * 167 * \param ctx The context to use. This must be initialized. 168 * \param is224 Determines which function to use. This must be 169 * either \c 0 for SHA-256, or \c 1 for SHA-224. 170 */ 171 MBEDTLS_DEPRECATED void mbedtls_sha256_starts( mbedtls_sha256_context *ctx, 172 int is224 ); 173 174 /** 175 * \brief This function feeds an input buffer into an ongoing 176 * SHA-256 checksum calculation. 177 * 178 * \deprecated Superseded by mbedtls_sha256_update_ret() in 2.7.0. 179 * 180 * \param ctx The SHA-256 context to use. This must be 181 * initialized and have a hash operation started. 182 * \param input The buffer holding the data. This must be a readable 183 * buffer of length \p ilen Bytes. 184 * \param ilen The length of the input data in Bytes. 185 */ 186 MBEDTLS_DEPRECATED void mbedtls_sha256_update( mbedtls_sha256_context *ctx, 187 const unsigned char *input, 188 size_t ilen ); 189 190 /** 191 * \brief This function finishes the SHA-256 operation, and writes 192 * the result to the output buffer. 193 * 194 * \deprecated Superseded by mbedtls_sha256_finish_ret() in 2.7.0. 195 * 196 * \param ctx The SHA-256 context. This must be initialized and 197 * have a hash operation started. 198 * \param output The SHA-224 or SHA-256 checksum result. This must be 199 * a writable buffer of length \c 32 Bytes. 200 */ 201 MBEDTLS_DEPRECATED void mbedtls_sha256_finish( mbedtls_sha256_context *ctx, 202 unsigned char output[32] ); 203 204 /** 205 * \brief This function processes a single data block within 206 * the ongoing SHA-256 computation. This function is for 207 * internal use only. 208 * 209 * \deprecated Superseded by mbedtls_internal_sha256_process() in 2.7.0. 210 * 211 * \param ctx The SHA-256 context. This must be initialized. 212 * \param data The buffer holding one block of data. This must be 213 * a readable buffer of size \c 64 Bytes. 214 */ 215 MBEDTLS_DEPRECATED void mbedtls_sha256_process( mbedtls_sha256_context *ctx, 216 const unsigned char data[64] ); 217 218 #undef MBEDTLS_DEPRECATED 219 #endif /* !MBEDTLS_DEPRECATED_REMOVED */ 220 221 /** 222 * \brief This function calculates the SHA-224 or SHA-256 223 * checksum of a buffer. 224 * 225 * The function allocates the context, performs the 226 * calculation, and frees the context. 227 * 228 * The SHA-256 result is calculated as 229 * output = SHA-256(input buffer). 230 * 231 * \param input The buffer holding the data. This must be a readable 232 * buffer of length \p ilen Bytes. 233 * \param ilen The length of the input data in Bytes. 234 * \param output The SHA-224 or SHA-256 checksum result. This must 235 * be a writable buffer of length \c 32 Bytes. 236 * \param is224 Determines which function to use. This must be 237 * either \c 0 for SHA-256, or \c 1 for SHA-224. 238 */ 239 int mbedtls_sha256_ret( const unsigned char *input, 240 size_t ilen, 241 unsigned char output[32], 242 int is224 ); 243 244 #if !defined(MBEDTLS_DEPRECATED_REMOVED) 245 #if defined(MBEDTLS_DEPRECATED_WARNING) 246 #define MBEDTLS_DEPRECATED __attribute__((deprecated)) 247 #else 248 #define MBEDTLS_DEPRECATED 249 #endif 250 251 /** 252 * \brief This function calculates the SHA-224 or SHA-256 checksum 253 * of a buffer. 254 * 255 * The function allocates the context, performs the 256 * calculation, and frees the context. 257 * 258 * The SHA-256 result is calculated as 259 * output = SHA-256(input buffer). 260 * 261 * \deprecated Superseded by mbedtls_sha256_ret() in 2.7.0. 262 * 263 * \param input The buffer holding the data. This must be a readable 264 * buffer of length \p ilen Bytes. 265 * \param ilen The length of the input data in Bytes. 266 * \param output The SHA-224 or SHA-256 checksum result. This must be 267 * a writable buffer of length \c 32 Bytes. 268 * \param is224 Determines which function to use. This must be either 269 * \c 0 for SHA-256, or \c 1 for SHA-224. 270 */ 271 MBEDTLS_DEPRECATED void mbedtls_sha256( const unsigned char *input, 272 size_t ilen, 273 unsigned char output[32], 274 int is224 ); 275 276 #undef MBEDTLS_DEPRECATED 277 #endif /* !MBEDTLS_DEPRECATED_REMOVED */ 278 279 #if defined(MBEDTLS_SELF_TEST) 280 281 /** 282 * \brief The SHA-224 and SHA-256 checkup routine. 283 * 284 * \return \c 0 on success. 285 * \return \c 1 on failure. 286 */ 287 int mbedtls_sha256_self_test( int verbose ); 288 289 #endif /* MBEDTLS_SELF_TEST */ 290 291 #ifdef __cplusplus 292 } 293 #endif 294 295 #endif /* mbedtls_sha256.h */ 296