1 /** 2 * \file sha256.h 3 * 4 * \brief The SHA-224 and SHA-256 cryptographic hash function. 5 */ 6 /* 7 * Copyright (C) 2006-2018, Arm Limited (or its affiliates), All Rights Reserved 8 * SPDX-License-Identifier: GPL-2.0 9 * 10 * This program is free software; you can redistribute it and/or modify 11 * it under the terms of the GNU General Public License as published by 12 * the Free Software Foundation; either version 2 of the License, or 13 * (at your option) any later version. 14 * 15 * This program is distributed in the hope that it will be useful, 16 * but WITHOUT ANY WARRANTY; without even the implied warranty of 17 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 18 * GNU General Public License for more details. 19 * 20 * You should have received a copy of the GNU General Public License along 21 * with this program; if not, write to the Free Software Foundation, Inc., 22 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. 23 * 24 * This file is part of Mbed TLS (https://tls.mbed.org) 25 */ 26 #ifndef MBEDTLS_SHA256_H 27 #define MBEDTLS_SHA256_H 28 29 #if !defined(MBEDTLS_CONFIG_FILE) 30 #include "config.h" 31 #else 32 #include MBEDTLS_CONFIG_FILE 33 #endif 34 35 #include <stddef.h> 36 #include <stdint.h> 37 38 #define MBEDTLS_ERR_SHA256_HW_ACCEL_FAILED -0x0037 /**< SHA-256 hardware accelerator failed */ 39 40 #if !defined(MBEDTLS_SHA256_ALT) 41 // Regular implementation 42 // 43 44 #ifdef __cplusplus 45 extern "C" { 46 #endif 47 48 /** 49 * \brief The SHA-256 context structure. 50 * 51 * The structure is used both for SHA-256 and for SHA-224 52 * checksum calculations. The choice between these two is 53 * made in the call to mbedtls_sha256_starts_ret(). 54 */ 55 typedef struct 56 { 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 <ul><li>0: Use SHA-256.</li> 62 <li>1: Use SHA-224.</li></ul> */ 63 } 64 mbedtls_sha256_context; 65 66 /** 67 * \brief This function initializes a SHA-256 context. 68 * 69 * \param ctx The SHA-256 context to initialize. 70 */ 71 void mbedtls_sha256_init( mbedtls_sha256_context *ctx ); 72 73 /** 74 * \brief This function clears a SHA-256 context. 75 * 76 * \param ctx The SHA-256 context to clear. 77 */ 78 void mbedtls_sha256_free( mbedtls_sha256_context *ctx ); 79 80 /** 81 * \brief This function clones the state of a SHA-256 context. 82 * 83 * \param dst The destination context. 84 * \param src The context to clone. 85 */ 86 void mbedtls_sha256_clone( mbedtls_sha256_context *dst, 87 const mbedtls_sha256_context *src ); 88 89 /** 90 * \brief This function starts a SHA-224 or SHA-256 checksum 91 * calculation. 92 * 93 * \param ctx The context to initialize. 94 * \param is224 Determines which function to use. 95 * <ul><li>0: Use SHA-256.</li> 96 * <li>1: Use SHA-224.</li></ul> 97 * 98 * \return \c 0 on success. 99 */ 100 int mbedtls_sha256_starts_ret( mbedtls_sha256_context *ctx, int is224 ); 101 102 /** 103 * \brief This function feeds an input buffer into an ongoing 104 * SHA-256 checksum calculation. 105 * 106 * \param ctx SHA-256 context 107 * \param input buffer holding the data 108 * \param ilen length of the input data 109 * 110 * \return \c 0 on success. 111 */ 112 int mbedtls_sha256_update_ret( mbedtls_sha256_context *ctx, 113 const unsigned char *input, 114 size_t ilen ); 115 116 /** 117 * \brief This function finishes the SHA-256 operation, and writes 118 * the result to the output buffer. 119 * 120 * \param ctx The SHA-256 context. 121 * \param output The SHA-224 or SHA-256 checksum result. 122 * 123 * \return \c 0 on success. 124 */ 125 int mbedtls_sha256_finish_ret( mbedtls_sha256_context *ctx, 126 unsigned char output[32] ); 127 128 /** 129 * \brief This function processes a single data block within 130 * the ongoing SHA-256 computation. This function is for 131 * internal use only. 132 * 133 * \param ctx The SHA-256 context. 134 * \param data The buffer holding one block of data. 135 * 136 * \return \c 0 on success. 137 */ 138 int mbedtls_internal_sha256_process( mbedtls_sha256_context *ctx, 139 const unsigned char data[64] ); 140 141 #if !defined(MBEDTLS_DEPRECATED_REMOVED) 142 #if defined(MBEDTLS_DEPRECATED_WARNING) 143 #define MBEDTLS_DEPRECATED __attribute__((deprecated)) 144 #else 145 #define MBEDTLS_DEPRECATED 146 #endif 147 /** 148 * \brief This function starts a SHA-256 checksum calculation. 149 * 150 * \deprecated Superseded by mbedtls_sha256_starts_ret() in 2.7.0. 151 * 152 * \param ctx The SHA-256 context to initialize. 153 * \param is224 Determines which function to use. 154 * <ul><li>0: Use SHA-256.</li> 155 * <li>1: Use SHA-224.</li></ul> 156 */ 157 MBEDTLS_DEPRECATED void mbedtls_sha256_starts( mbedtls_sha256_context *ctx, 158 int is224 ); 159 160 /** 161 * \brief This function feeds an input buffer into an ongoing 162 * SHA-256 checksum calculation. 163 * 164 * \deprecated Superseded by mbedtls_sha256_update_ret() in 2.7.0. 165 * 166 * \param ctx The SHA-256 context to initialize. 167 * \param input The buffer holding the data. 168 * \param ilen The length of the input data. 169 */ 170 MBEDTLS_DEPRECATED void mbedtls_sha256_update( mbedtls_sha256_context *ctx, 171 const unsigned char *input, 172 size_t ilen ); 173 174 /** 175 * \brief This function finishes the SHA-256 operation, and writes 176 * the result to the output buffer. 177 * 178 * \deprecated Superseded by mbedtls_sha256_finish_ret() in 2.7.0. 179 * 180 * \param ctx The SHA-256 context. 181 * \param output The SHA-224or SHA-256 checksum result. 182 */ 183 MBEDTLS_DEPRECATED void mbedtls_sha256_finish( mbedtls_sha256_context *ctx, 184 unsigned char output[32] ); 185 186 /** 187 * \brief This function processes a single data block within 188 * the ongoing SHA-256 computation. This function is for 189 * internal use only. 190 * 191 * \deprecated Superseded by mbedtls_internal_sha256_process() in 2.7.0. 192 * 193 * \param ctx The SHA-256 context. 194 * \param data The buffer holding one block of data. 195 */ 196 MBEDTLS_DEPRECATED void mbedtls_sha256_process( mbedtls_sha256_context *ctx, 197 const unsigned char data[64] ); 198 199 #undef MBEDTLS_DEPRECATED 200 #endif /* !MBEDTLS_DEPRECATED_REMOVED */ 201 #ifdef __cplusplus 202 } 203 #endif 204 205 #else /* MBEDTLS_SHA256_ALT */ 206 #include "sha256_alt.h" 207 #endif /* MBEDTLS_SHA256_ALT */ 208 209 #ifdef __cplusplus 210 extern "C" { 211 #endif 212 213 /** 214 * \brief This function calculates the SHA-224 or SHA-256 215 * checksum of a buffer. 216 * 217 * The function allocates the context, performs the 218 * calculation, and frees the context. 219 * 220 * The SHA-256 result is calculated as 221 * output = SHA-256(input buffer). 222 * 223 * \param input The buffer holding the input data. 224 * \param ilen The length of the input data. 225 * \param output The SHA-224 or SHA-256 checksum result. 226 * \param is224 Determines which function to use. 227 * <ul><li>0: Use SHA-256.</li> 228 * <li>1: Use SHA-224.</li></ul> 229 */ 230 int mbedtls_sha256_ret( const unsigned char *input, 231 size_t ilen, 232 unsigned char output[32], 233 int is224 ); 234 235 #if !defined(MBEDTLS_DEPRECATED_REMOVED) 236 #if defined(MBEDTLS_DEPRECATED_WARNING) 237 #define MBEDTLS_DEPRECATED __attribute__((deprecated)) 238 #else 239 #define MBEDTLS_DEPRECATED 240 #endif 241 242 /** 243 * \brief This function calculates the SHA-224 or SHA-256 checksum 244 * of a buffer. 245 * 246 * The function allocates the context, performs the 247 * calculation, and frees the context. 248 * 249 * The SHA-256 result is calculated as 250 * output = SHA-256(input buffer). 251 * 252 * \deprecated Superseded by mbedtls_sha256_ret() in 2.7.0. 253 * 254 * \param input The buffer holding the data. 255 * \param ilen The length of the input data. 256 * \param output The SHA-224 or SHA-256 checksum result. 257 * \param is224 Determines which function to use. 258 * <ul><li>0: Use SHA-256.</li> 259 * <li>1: Use SHA-224.</li></ul> 260 */ 261 MBEDTLS_DEPRECATED void mbedtls_sha256( const unsigned char *input, 262 size_t ilen, 263 unsigned char output[32], 264 int is224 ); 265 266 #undef MBEDTLS_DEPRECATED 267 #endif /* !MBEDTLS_DEPRECATED_REMOVED */ 268 269 /** 270 * \brief The SHA-224 and SHA-256 checkup routine. 271 * 272 * \return \c 0 on success, or \c 1 on failure. 273 */ 274 int mbedtls_sha256_self_test( int verbose ); 275 276 #ifdef __cplusplus 277 } 278 #endif 279 280 #endif /* mbedtls_sha256.h */ 281