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