blob: c9e01690ac70decd0f267af224a0f68d70440203 [file] [log] [blame]
Paul Bakker5121ce52009-01-03 21:22:43 +00001/**
Simon Butcher5b331b92016-01-03 16:14:14 +00002 * \file sha512.h
Rose Zadik1a6275a2018-03-27 13:03:42 +01003 * \brief This file contains SHA-384 and SHA-512 definitions and functions.
Paul Bakkere0ccd0a2009-01-04 16:27:10 +00004 *
Rose Zadik1a6275a2018-03-27 13:03:42 +01005 * 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>.
Darryl Greena40a1012018-01-05 15:33:17 +00007 */
8/*
Bence Szépkúti1e148272020-08-07 13:07:28 +02009 * Copyright The Mbed TLS Contributors
Dave Rodgman7ff79652023-11-03 12:04:52 +000010 * SPDX-License-Identifier: Apache-2.0 OR GPL-2.0-or-later
Paul Bakker5121ce52009-01-03 21:22:43 +000011 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020012#ifndef MBEDTLS_SHA512_H
13#define MBEDTLS_SHA512_H
Paul Bakker5121ce52009-01-03 21:22:43 +000014
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020015#if !defined(MBEDTLS_CONFIG_FILE)
Jaeden Ameroc49fbbf2019-07-04 20:01:14 +010016#include "mbedtls/config.h"
Manuel Pégourié-Gonnardcef4ad22014-04-29 12:39:06 +020017#else
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020018#include MBEDTLS_CONFIG_FILE
Manuel Pégourié-Gonnardcef4ad22014-04-29 12:39:06 +020019#endif
Paul Bakker90995b52013-06-24 19:20:35 +020020
Rich Evans00ab4702015-02-06 13:43:58 +000021#include <stddef.h>
Manuel Pégourié-Gonnardab229102015-04-15 11:53:16 +020022#include <stdint.h>
Paul Bakker5121ce52009-01-03 21:22:43 +000023
Manuel Pégourié-Gonnard93c08472021-04-15 12:23:55 +020024/* MBEDTLS_ERR_SHA512_HW_ACCEL_FAILED is deprecated and should not be used. */
Gilles Peskinea3974432021-07-26 18:48:10 +020025/** 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
Gilles Peskinea381fe82018-01-23 18:16:11 +010029
Paul Bakker407a0da2013-06-27 14:29:21 +020030#ifdef __cplusplus
31extern "C" {
32#endif
33
Ron Eldorb2aacec2017-05-18 16:53:08 +030034#if !defined(MBEDTLS_SHA512_ALT)
35// Regular implementation
36//
37
Paul Bakker5121ce52009-01-03 21:22:43 +000038/**
Rose Zadik27ff1202018-01-26 11:01:31 +000039 * \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().
Paul Bakker5121ce52009-01-03 21:22:43 +000044 */
Gilles Peskine1b6c09a2023-01-11 14:52:35 +010045typedef struct mbedtls_sha512_context {
Rose Zadik27ff1202018-01-26 11:01:31 +000046 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. */
Manuel Pégourié-Gonnard3df4e602019-07-17 15:16:14 +020049#if !defined(MBEDTLS_SHA512_NO_SHA384)
Rose Zadik1a6275a2018-03-27 13:03:42 +010050 int is384; /*!< Determines which function to use:
51 0: Use SHA-512, or 1: Use SHA-384. */
Manuel Pégourié-Gonnard3df4e602019-07-17 15:16:14 +020052#endif
Paul Bakker5121ce52009-01-03 21:22:43 +000053}
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020054mbedtls_sha512_context;
Paul Bakker5121ce52009-01-03 21:22:43 +000055
Ron Eldorb2aacec2017-05-18 16:53:08 +030056#else /* MBEDTLS_SHA512_ALT */
57#include "sha512_alt.h"
58#endif /* MBEDTLS_SHA512_ALT */
59
Paul Bakker5121ce52009-01-03 21:22:43 +000060/**
Rose Zadik27ff1202018-01-26 11:01:31 +000061 * \brief This function initializes a SHA-512 context.
Paul Bakker5b4af392014-06-26 12:09:34 +020062 *
Andrzej Kurekc470b6b2019-01-31 08:20:20 -050063 * \param ctx The SHA-512 context to initialize. This must
64 * not be \c NULL.
Paul Bakker5b4af392014-06-26 12:09:34 +020065 */
Gilles Peskine1b6c09a2023-01-11 14:52:35 +010066void mbedtls_sha512_init(mbedtls_sha512_context *ctx);
Paul Bakker5b4af392014-06-26 12:09:34 +020067
68/**
Rose Zadik27ff1202018-01-26 11:01:31 +000069 * \brief This function clears a SHA-512 context.
Paul Bakker5b4af392014-06-26 12:09:34 +020070 *
Andrzej Kurekc470b6b2019-01-31 08:20:20 -050071 * \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.
Paul Bakker5b4af392014-06-26 12:09:34 +020075 */
Gilles Peskine1b6c09a2023-01-11 14:52:35 +010076void mbedtls_sha512_free(mbedtls_sha512_context *ctx);
Paul Bakker5b4af392014-06-26 12:09:34 +020077
78/**
Rose Zadik27ff1202018-01-26 11:01:31 +000079 * \brief This function clones the state of a SHA-512 context.
Manuel Pégourié-Gonnard16d412f2015-07-06 15:26:26 +020080 *
Andrzej Kurekc470b6b2019-01-31 08:20:20 -050081 * \param dst The destination context. This must be initialized.
82 * \param src The context to clone. This must be initialized.
Manuel Pégourié-Gonnard16d412f2015-07-06 15:26:26 +020083 */
Gilles Peskine1b6c09a2023-01-11 14:52:35 +010084void mbedtls_sha512_clone(mbedtls_sha512_context *dst,
85 const mbedtls_sha512_context *src);
Manuel Pégourié-Gonnard16d412f2015-07-06 15:26:26 +020086
87/**
Rose Zadik27ff1202018-01-26 11:01:31 +000088 * \brief This function starts a SHA-384 or SHA-512 checksum
89 * calculation.
Paul Bakker5121ce52009-01-03 21:22:43 +000090 *
Andrzej Kurekc470b6b2019-01-31 08:20:20 -050091 * \param ctx The SHA-512 context to use. This must be initialized.
92 * \param is384 Determines which function to use. This must be
Manuel Pégourié-Gonnard663ee202020-01-07 10:11:22 +010093 * either \c 0 for SHA-512, or \c 1 for SHA-384.
94 *
Manuel Pégourié-Gonnard3a3b5c72020-01-24 10:57:25 +010095 * \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.
Andres Amaya Garcia614c6892017-05-02 12:07:26 +010098 *
Rose Zadik27ff1202018-01-26 11:01:31 +000099 * \return \c 0 on success.
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500100 * \return A negative error code on failure.
Paul Bakker5121ce52009-01-03 21:22:43 +0000101 */
Gilles Peskine1b6c09a2023-01-11 14:52:35 +0100102int mbedtls_sha512_starts_ret(mbedtls_sha512_context *ctx, int is384);
Paul Bakker5121ce52009-01-03 21:22:43 +0000103
104/**
Rose Zadik27ff1202018-01-26 11:01:31 +0000105 * \brief This function feeds an input buffer into an ongoing
106 * SHA-512 checksum calculation.
Paul Bakker5121ce52009-01-03 21:22:43 +0000107 *
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500108 * \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.
Andres Amaya Garcia614c6892017-05-02 12:07:26 +0100113 *
Rose Zadik27ff1202018-01-26 11:01:31 +0000114 * \return \c 0 on success.
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500115 * \return A negative error code on failure.
Paul Bakker5121ce52009-01-03 21:22:43 +0000116 */
Gilles Peskine1b6c09a2023-01-11 14:52:35 +0100117int mbedtls_sha512_update_ret(mbedtls_sha512_context *ctx,
118 const unsigned char *input,
119 size_t ilen);
Paul Bakker5121ce52009-01-03 21:22:43 +0000120
121/**
Rose Zadik27ff1202018-01-26 11:01:31 +0000122 * \brief This function finishes the SHA-512 operation, and writes
Gilles Peskine383c2452020-11-22 13:59:43 +0100123 * the result to the output buffer.
Paul Bakker5121ce52009-01-03 21:22:43 +0000124 *
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500125 * \param ctx The SHA-512 context. This must be initialized
126 * and have a hash operation started.
Rose Zadik27ff1202018-01-26 11:01:31 +0000127 * \param output The SHA-384 or SHA-512 checksum result.
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500128 * This must be a writable buffer of length \c 64 Bytes.
Andres Amaya Garcia614c6892017-05-02 12:07:26 +0100129 *
Rose Zadik27ff1202018-01-26 11:01:31 +0000130 * \return \c 0 on success.
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500131 * \return A negative error code on failure.
Paul Bakker5121ce52009-01-03 21:22:43 +0000132 */
Gilles Peskine1b6c09a2023-01-11 14:52:35 +0100133int mbedtls_sha512_finish_ret(mbedtls_sha512_context *ctx,
134 unsigned char output[64]);
Andres Amaya Garcia614c6892017-05-02 12:07:26 +0100135
136/**
Rose Zadik27ff1202018-01-26 11:01:31 +0000137 * \brief This function processes a single data block within
138 * the ongoing SHA-512 computation.
Gilles Peskine383c2452020-11-22 13:59:43 +0100139 * This function is for internal use only.
Andres Amaya Garcia614c6892017-05-02 12:07:26 +0100140 *
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500141 * \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.
Andres Amaya Garcia614c6892017-05-02 12:07:26 +0100144 *
Rose Zadik27ff1202018-01-26 11:01:31 +0000145 * \return \c 0 on success.
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500146 * \return A negative error code on failure.
Andres Amaya Garcia614c6892017-05-02 12:07:26 +0100147 */
Gilles Peskine1b6c09a2023-01-11 14:52:35 +0100148int mbedtls_internal_sha512_process(mbedtls_sha512_context *ctx,
149 const unsigned char data[128]);
Manuel Pégourié-Gonnard93c08472021-04-15 12:23:55 +0200150#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 */
Gilles Peskine1b6c09a2023-01-11 14:52:35 +0100169MBEDTLS_DEPRECATED void mbedtls_sha512_starts(mbedtls_sha512_context *ctx,
170 int is384);
Manuel Pégourié-Gonnard93c08472021-04-15 12:23:55 +0200171
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 */
Gilles Peskine1b6c09a2023-01-11 14:52:35 +0100184MBEDTLS_DEPRECATED void mbedtls_sha512_update(mbedtls_sha512_context *ctx,
185 const unsigned char *input,
186 size_t ilen);
Manuel Pégourié-Gonnard93c08472021-04-15 12:23:55 +0200187
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 */
Gilles Peskine1b6c09a2023-01-11 14:52:35 +0100199MBEDTLS_DEPRECATED void mbedtls_sha512_finish(mbedtls_sha512_context *ctx,
200 unsigned char output[64]);
Manuel Pégourié-Gonnard93c08472021-04-15 12:23:55 +0200201
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 */
213MBEDTLS_DEPRECATED void mbedtls_sha512_process(
Gilles Peskine1b6c09a2023-01-11 14:52:35 +0100214 mbedtls_sha512_context *ctx,
215 const unsigned char data[128]);
Manuel Pégourié-Gonnard93c08472021-04-15 12:23:55 +0200216
217#undef MBEDTLS_DEPRECATED
218#endif /* !MBEDTLS_DEPRECATED_REMOVED */
Paul Bakker5121ce52009-01-03 21:22:43 +0000219
220/**
Rose Zadik27ff1202018-01-26 11:01:31 +0000221 * \brief This function calculates the SHA-512 or SHA-384
222 * checksum of a buffer.
Paul Bakker5121ce52009-01-03 21:22:43 +0000223 *
Rose Zadik27ff1202018-01-26 11:01:31 +0000224 * The function allocates the context, performs the
225 * calculation, and frees the context.
Andres Amaya Garcia614c6892017-05-02 12:07:26 +0100226 *
Rose Zadik27ff1202018-01-26 11:01:31 +0000227 * The SHA-512 result is calculated as
228 * output = SHA-512(input buffer).
229 *
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500230 * \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.
Rose Zadik27ff1202018-01-26 11:01:31 +0000233 * \param output The SHA-384 or SHA-512 checksum result.
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500234 * 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.
Rose Zadik27ff1202018-01-26 11:01:31 +0000237 *
Manuel Pégourié-Gonnard3a3b5c72020-01-24 10:57:25 +0100238 * \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.
Manuel Pégourié-Gonnard663ee202020-01-07 10:11:22 +0100241 *
Rose Zadik27ff1202018-01-26 11:01:31 +0000242 * \return \c 0 on success.
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500243 * \return A negative error code on failure.
Paul Bakker5121ce52009-01-03 21:22:43 +0000244 */
Gilles Peskine1b6c09a2023-01-11 14:52:35 +0100245int mbedtls_sha512_ret(const unsigned char *input,
246 size_t ilen,
247 unsigned char output[64],
248 int is384);
Andres Amaya Garcia614c6892017-05-02 12:07:26 +0100249
Manuel Pégourié-Gonnard93c08472021-04-15 12:23:55 +0200250#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 */
Gilles Peskine1b6c09a2023-01-11 14:52:35 +0100280MBEDTLS_DEPRECATED void mbedtls_sha512(const unsigned char *input,
281 size_t ilen,
282 unsigned char output[64],
283 int is384);
Manuel Pégourié-Gonnard93c08472021-04-15 12:23:55 +0200284
285#undef MBEDTLS_DEPRECATED
286#endif /* !MBEDTLS_DEPRECATED_REMOVED */
287
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500288#if defined(MBEDTLS_SELF_TEST)
289
Gilles Peskine1b6c09a2023-01-11 14:52:35 +0100290/**
Rose Zadik27ff1202018-01-26 11:01:31 +0000291 * \brief The SHA-384 or SHA-512 checkup routine.
Paul Bakker5121ce52009-01-03 21:22:43 +0000292 *
Rose Zadik1a6275a2018-03-27 13:03:42 +0100293 * \return \c 0 on success.
294 * \return \c 1 on failure.
Paul Bakker5121ce52009-01-03 21:22:43 +0000295 */
Gilles Peskine1b6c09a2023-01-11 14:52:35 +0100296int mbedtls_sha512_self_test(int verbose);
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500297#endif /* MBEDTLS_SELF_TEST */
Paul Bakker5121ce52009-01-03 21:22:43 +0000298
Paul Bakker5121ce52009-01-03 21:22:43 +0000299#ifdef __cplusplus
300}
301#endif
302
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200303#endif /* mbedtls_sha512.h */