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