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