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