blob: c43b9075e3d96730c1d3fdd28abf2267845f23cc [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
Manuel Pégourié-Gonnard37ff1402015-09-04 14:21:07 +020010 * 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.
Paul Bakker5121ce52009-01-03 21:22:43 +000023 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020024#ifndef MBEDTLS_SHA512_H
25#define MBEDTLS_SHA512_H
Mateusz Starzyk846f0212021-05-19 19:44:07 +020026#include "mbedtls/private_access.h"
Paul Bakker5121ce52009-01-03 21:22:43 +000027
Bence Szépkútic662b362021-05-27 11:25:03 +020028#include "mbedtls/build_info.h"
Paul Bakker90995b52013-06-24 19:20:35 +020029
Rich Evans00ab4702015-02-06 13:43:58 +000030#include <stddef.h>
Manuel Pégourié-Gonnardab229102015-04-15 11:53:16 +020031#include <stdint.h>
Paul Bakker5121ce52009-01-03 21:22:43 +000032
Andrzej Kurekc470b6b2019-01-31 08:20:20 -050033#define MBEDTLS_ERR_SHA512_BAD_INPUT_DATA -0x0075 /**< SHA-512 input data was malformed. */
Gilles Peskinea381fe82018-01-23 18:16:11 +010034
Paul Bakker407a0da2013-06-27 14:29:21 +020035#ifdef __cplusplus
36extern "C" {
37#endif
38
Ron Eldorb2aacec2017-05-18 16:53:08 +030039#if !defined(MBEDTLS_SHA512_ALT)
40// Regular implementation
41//
42
Paul Bakker5121ce52009-01-03 21:22:43 +000043/**
Rose Zadik27ff1202018-01-26 11:01:31 +000044 * \brief The SHA-512 context structure.
45 *
46 * The structure is used both for SHA-384 and for SHA-512
47 * checksum calculations. The choice between these two is
TRodziewicz26371e42021-06-08 16:45:41 +020048 * made in the call to mbedtls_sha512_starts().
Paul Bakker5121ce52009-01-03 21:22:43 +000049 */
Dawid Drozd428cc522018-07-24 10:02:47 +020050typedef struct mbedtls_sha512_context
Paul Bakker5121ce52009-01-03 21:22:43 +000051{
Mateusz Starzyk846f0212021-05-19 19:44:07 +020052 uint64_t MBEDTLS_PRIVATE(total)[2]; /*!< The number of Bytes processed. */
53 uint64_t MBEDTLS_PRIVATE(state)[8]; /*!< The intermediate digest state. */
54 unsigned char MBEDTLS_PRIVATE(buffer)[128]; /*!< The data block being processed. */
Mateusz Starzyk3352a532021-04-06 14:28:22 +020055#if defined(MBEDTLS_SHA384_C)
Mateusz Starzyk846f0212021-05-19 19:44:07 +020056 int MBEDTLS_PRIVATE(is384); /*!< Determines which function to use:
57 0: Use SHA-512, or 1: Use SHA-384. */
Manuel Pégourié-Gonnard3df4e602019-07-17 15:16:14 +020058#endif
Paul Bakker5121ce52009-01-03 21:22:43 +000059}
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020060mbedtls_sha512_context;
Paul Bakker5121ce52009-01-03 21:22:43 +000061
Ron Eldorb2aacec2017-05-18 16:53:08 +030062#else /* MBEDTLS_SHA512_ALT */
63#include "sha512_alt.h"
64#endif /* MBEDTLS_SHA512_ALT */
65
Paul Bakker5121ce52009-01-03 21:22:43 +000066/**
Rose Zadik27ff1202018-01-26 11:01:31 +000067 * \brief This function initializes a SHA-512 context.
Paul Bakker5b4af392014-06-26 12:09:34 +020068 *
Andrzej Kurekc470b6b2019-01-31 08:20:20 -050069 * \param ctx The SHA-512 context to initialize. This must
70 * not be \c NULL.
Paul Bakker5b4af392014-06-26 12:09:34 +020071 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020072void mbedtls_sha512_init( mbedtls_sha512_context *ctx );
Paul Bakker5b4af392014-06-26 12:09:34 +020073
74/**
Rose Zadik27ff1202018-01-26 11:01:31 +000075 * \brief This function clears a SHA-512 context.
Paul Bakker5b4af392014-06-26 12:09:34 +020076 *
Andrzej Kurekc470b6b2019-01-31 08:20:20 -050077 * \param ctx The SHA-512 context to clear. This may be \c NULL,
78 * in which case this function does nothing. If it
79 * is not \c NULL, it must point to an initialized
80 * SHA-512 context.
Paul Bakker5b4af392014-06-26 12:09:34 +020081 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020082void mbedtls_sha512_free( mbedtls_sha512_context *ctx );
Paul Bakker5b4af392014-06-26 12:09:34 +020083
84/**
Rose Zadik27ff1202018-01-26 11:01:31 +000085 * \brief This function clones the state of a SHA-512 context.
Manuel Pégourié-Gonnard16d412f2015-07-06 15:26:26 +020086 *
Andrzej Kurekc470b6b2019-01-31 08:20:20 -050087 * \param dst The destination context. This must be initialized.
88 * \param src The context to clone. This must be initialized.
Manuel Pégourié-Gonnard16d412f2015-07-06 15:26:26 +020089 */
90void mbedtls_sha512_clone( mbedtls_sha512_context *dst,
91 const mbedtls_sha512_context *src );
92
93/**
Rose Zadik27ff1202018-01-26 11:01:31 +000094 * \brief This function starts a SHA-384 or SHA-512 checksum
95 * calculation.
Paul Bakker5121ce52009-01-03 21:22:43 +000096 *
Andrzej Kurekc470b6b2019-01-31 08:20:20 -050097 * \param ctx The SHA-512 context to use. This must be initialized.
98 * \param is384 Determines which function to use. This must be
Manuel Pégourié-Gonnard663ee202020-01-07 10:11:22 +010099 * either \c 0 for SHA-512, or \c 1 for SHA-384.
100 *
Mateusz Starzyk425e23e2021-05-20 11:15:13 +0200101 * \note When \c MBEDTLS_SHA384_C is not defined,
102 * \p is384 must be \c 0, or the function will return
Manuel Pégourié-Gonnard3a3b5c72020-01-24 10:57:25 +0100103 * #MBEDTLS_ERR_SHA512_BAD_INPUT_DATA.
Andres Amaya Garcia614c6892017-05-02 12:07:26 +0100104 *
Rose Zadik27ff1202018-01-26 11:01:31 +0000105 * \return \c 0 on success.
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500106 * \return A negative error code on failure.
Paul Bakker5121ce52009-01-03 21:22:43 +0000107 */
TRodziewicz26371e42021-06-08 16:45:41 +0200108int mbedtls_sha512_starts( mbedtls_sha512_context *ctx, int is384 );
Paul Bakker5121ce52009-01-03 21:22:43 +0000109
110/**
Rose Zadik27ff1202018-01-26 11:01:31 +0000111 * \brief This function feeds an input buffer into an ongoing
112 * SHA-512 checksum calculation.
Paul Bakker5121ce52009-01-03 21:22:43 +0000113 *
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500114 * \param ctx The SHA-512 context. This must be initialized
115 * and have a hash operation started.
116 * \param input The buffer holding the input data. This must
117 * be a readable buffer of length \p ilen Bytes.
118 * \param ilen The length of the input data in Bytes.
Andres Amaya Garcia614c6892017-05-02 12:07:26 +0100119 *
Rose Zadik27ff1202018-01-26 11:01:31 +0000120 * \return \c 0 on success.
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500121 * \return A negative error code on failure.
Paul Bakker5121ce52009-01-03 21:22:43 +0000122 */
TRodziewicz26371e42021-06-08 16:45:41 +0200123int mbedtls_sha512_update( mbedtls_sha512_context *ctx,
124 const unsigned char *input,
125 size_t ilen );
Paul Bakker5121ce52009-01-03 21:22:43 +0000126
127/**
Rose Zadik27ff1202018-01-26 11:01:31 +0000128 * \brief This function finishes the SHA-512 operation, and writes
Gilles Peskine383c2452020-11-22 13:59:43 +0100129 * the result to the output buffer.
Paul Bakker5121ce52009-01-03 21:22:43 +0000130 *
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500131 * \param ctx The SHA-512 context. This must be initialized
132 * and have a hash operation started.
Rose Zadik27ff1202018-01-26 11:01:31 +0000133 * \param output The SHA-384 or SHA-512 checksum result.
Gilles Peskinee02e02f2021-05-13 00:22:35 +0200134 * This must be a writable buffer of length \c 64 bytes
Gilles Peskine96d6e082021-05-18 20:06:04 +0200135 * for SHA-512, \c 48 bytes for SHA-384.
Andres Amaya Garcia614c6892017-05-02 12:07:26 +0100136 *
Rose Zadik27ff1202018-01-26 11:01:31 +0000137 * \return \c 0 on success.
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500138 * \return A negative error code on failure.
Paul Bakker5121ce52009-01-03 21:22:43 +0000139 */
TRodziewicz26371e42021-06-08 16:45:41 +0200140int mbedtls_sha512_finish( mbedtls_sha512_context *ctx,
141 unsigned char *output );
Andres Amaya Garcia614c6892017-05-02 12:07:26 +0100142
143/**
Rose Zadik27ff1202018-01-26 11:01:31 +0000144 * \brief This function processes a single data block within
145 * the ongoing SHA-512 computation.
Gilles Peskine383c2452020-11-22 13:59:43 +0100146 * This function is for internal use only.
Andres Amaya Garcia614c6892017-05-02 12:07:26 +0100147 *
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500148 * \param ctx The SHA-512 context. This must be initialized.
149 * \param data The buffer holding one block of data. This
150 * must be a readable buffer of length \c 128 Bytes.
Andres Amaya Garcia614c6892017-05-02 12:07:26 +0100151 *
Rose Zadik27ff1202018-01-26 11:01:31 +0000152 * \return \c 0 on success.
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500153 * \return A negative error code on failure.
Andres Amaya Garcia614c6892017-05-02 12:07:26 +0100154 */
Andres Amaya Garciacccfe082017-06-28 10:36:39 +0100155int mbedtls_internal_sha512_process( mbedtls_sha512_context *ctx,
156 const unsigned char data[128] );
Paul Bakker5121ce52009-01-03 21:22:43 +0000157
158/**
Rose Zadik27ff1202018-01-26 11:01:31 +0000159 * \brief This function calculates the SHA-512 or SHA-384
160 * checksum of a buffer.
Paul Bakker5121ce52009-01-03 21:22:43 +0000161 *
Rose Zadik27ff1202018-01-26 11:01:31 +0000162 * The function allocates the context, performs the
163 * calculation, and frees the context.
Andres Amaya Garcia614c6892017-05-02 12:07:26 +0100164 *
Rose Zadik27ff1202018-01-26 11:01:31 +0000165 * The SHA-512 result is calculated as
166 * output = SHA-512(input buffer).
167 *
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500168 * \param input The buffer holding the input data. This must be
169 * a readable buffer of length \p ilen Bytes.
170 * \param ilen The length of the input data in Bytes.
Rose Zadik27ff1202018-01-26 11:01:31 +0000171 * \param output The SHA-384 or SHA-512 checksum result.
Gilles Peskinee02e02f2021-05-13 00:22:35 +0200172 * This must be a writable buffer of length \c 64 bytes
Gilles Peskine96d6e082021-05-18 20:06:04 +0200173 * for SHA-512, \c 48 bytes for SHA-384.
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500174 * \param is384 Determines which function to use. This must be either
175 * \c 0 for SHA-512, or \c 1 for SHA-384.
Rose Zadik27ff1202018-01-26 11:01:31 +0000176 *
Mateusz Starzyk425e23e2021-05-20 11:15:13 +0200177 * \note When \c MBEDTLS_SHA384_C is not defined, \p is384 must
178 * be \c 0, or the function will return
Manuel Pégourié-Gonnard3a3b5c72020-01-24 10:57:25 +0100179 * #MBEDTLS_ERR_SHA512_BAD_INPUT_DATA.
Manuel Pégourié-Gonnard663ee202020-01-07 10:11:22 +0100180 *
Rose Zadik27ff1202018-01-26 11:01:31 +0000181 * \return \c 0 on success.
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500182 * \return A negative error code on failure.
Paul Bakker5121ce52009-01-03 21:22:43 +0000183 */
TRodziewicz26371e42021-06-08 16:45:41 +0200184int mbedtls_sha512( const unsigned char *input,
185 size_t ilen,
186 unsigned char *output,
187 int is384 );
Andres Amaya Garcia614c6892017-05-02 12:07:26 +0100188
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500189#if defined(MBEDTLS_SELF_TEST)
190
Rose Zadik27ff1202018-01-26 11:01:31 +0000191 /**
192 * \brief The SHA-384 or SHA-512 checkup routine.
Paul Bakker5121ce52009-01-03 21:22:43 +0000193 *
Rose Zadik1a6275a2018-03-27 13:03:42 +0100194 * \return \c 0 on success.
195 * \return \c 1 on failure.
Paul Bakker5121ce52009-01-03 21:22:43 +0000196 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200197int mbedtls_sha512_self_test( int verbose );
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500198#endif /* MBEDTLS_SELF_TEST */
Paul Bakker5121ce52009-01-03 21:22:43 +0000199
Paul Bakker5121ce52009-01-03 21:22:43 +0000200#ifdef __cplusplus
201}
202#endif
203
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200204#endif /* mbedtls_sha512.h */