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