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