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 (C) 2006-2018, Arm Limited (or its affiliates), All Rights Reserved
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  *  This file is part of Mbed TLS (https://tls.mbed.org)
25  */
26 #ifndef MBEDTLS_SHA512_H
27 #define MBEDTLS_SHA512_H
28 
29 #if !defined(MBEDTLS_CONFIG_FILE)
30 #include "config.h"
31 #else
32 #include MBEDTLS_CONFIG_FILE
33 #endif
34 
35 #include <stddef.h>
36 #include <stdint.h>
37 
38 /* MBEDTLS_ERR_SHA512_HW_ACCEL_FAILED is deprecated and should not be used. */
39 #define MBEDTLS_ERR_SHA512_HW_ACCEL_FAILED                -0x0039  /**< SHA-512 hardware accelerator failed */
40 #define MBEDTLS_ERR_SHA512_BAD_INPUT_DATA                 -0x0075  /**< SHA-512 input data was malformed. */
41 
42 #ifdef __cplusplus
43 extern "C" {
44 #endif
45 
46 #if !defined(MBEDTLS_SHA512_ALT)
47 // Regular implementation
48 //
49 
50 /**
51  * \brief          The SHA-512 context structure.
52  *
53  *                 The structure is used both for SHA-384 and for SHA-512
54  *                 checksum calculations. The choice between these two is
55  *                 made in the call to mbedtls_sha512_starts_ret().
56  */
57 typedef struct mbedtls_sha512_context
58 {
59     uint64_t total[2];          /*!< The number of Bytes processed. */
60     uint64_t state[8];          /*!< The intermediate digest state. */
61     unsigned char buffer[128];  /*!< The data block being processed. */
62     int is384;                  /*!< Determines which function to use:
63                                      0: Use SHA-512, or 1: Use SHA-384. */
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 for SHA-512, or \c 1 for SHA-384.
105  *
106  * \return         \c 0 on success.
107  * \return         A negative error code on failure.
108  */
109 int mbedtls_sha512_starts_ret( mbedtls_sha512_context *ctx, int is384 );
110 
111 /**
112  * \brief          This function feeds an input buffer into an ongoing
113  *                 SHA-512 checksum calculation.
114  *
115  * \param ctx      The SHA-512 context. This must be initialized
116  *                 and have a hash operation started.
117  * \param input    The buffer holding the input data. This must
118  *                 be a readable buffer of length \p ilen Bytes.
119  * \param ilen     The length of the input data in Bytes.
120  *
121  * \return         \c 0 on success.
122  * \return         A negative error code on failure.
123  */
124 int mbedtls_sha512_update_ret( mbedtls_sha512_context *ctx,
125                     const unsigned char *input,
126                     size_t ilen );
127 
128 /**
129  * \brief          This function finishes the SHA-512 operation, and writes
130  *                 the result to the output buffer. This function is for
131  *                 internal use only.
132  *
133  * \param ctx      The SHA-512 context. This must be initialized
134  *                 and have a hash operation started.
135  * \param output   The SHA-384 or SHA-512 checksum result.
136  *                 This must be a writable buffer of length \c 64 Bytes.
137  *
138  * \return         \c 0 on success.
139  * \return         A negative error code on failure.
140  */
141 int mbedtls_sha512_finish_ret( mbedtls_sha512_context *ctx,
142                                unsigned char output[64] );
143 
144 /**
145  * \brief          This function processes a single data block within
146  *                 the ongoing SHA-512 computation.
147  *
148  * \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.
151  *
152  * \return         \c 0 on success.
153  * \return         A negative error code on failure.
154  */
155 int mbedtls_internal_sha512_process( mbedtls_sha512_context *ctx,
156                                      const unsigned char data[128] );
157 #if !defined(MBEDTLS_DEPRECATED_REMOVED)
158 #if defined(MBEDTLS_DEPRECATED_WARNING)
159 #define MBEDTLS_DEPRECATED      __attribute__((deprecated))
160 #else
161 #define MBEDTLS_DEPRECATED
162 #endif
163 /**
164  * \brief          This function starts a SHA-384 or SHA-512 checksum
165  *                 calculation.
166  *
167  * \deprecated     Superseded by mbedtls_sha512_starts_ret() in 2.7.0
168  *
169  * \param ctx      The SHA-512 context to use. This must be initialized.
170  * \param is384    Determines which function to use. This must be either
171  *                 \c 0 for SHA-512 or \c 1 for SHA-384.
172  */
173 MBEDTLS_DEPRECATED void mbedtls_sha512_starts( mbedtls_sha512_context *ctx,
174                                                int is384 );
175 
176 /**
177  * \brief          This function feeds an input buffer into an ongoing
178  *                 SHA-512 checksum calculation.
179  *
180  * \deprecated     Superseded by mbedtls_sha512_update_ret() in 2.7.0.
181  *
182  * \param ctx      The SHA-512 context. This must be initialized
183  *                 and have a hash operation started.
184  * \param input    The buffer holding the data. This must be a readable
185  *                 buffer of length \p ilen Bytes.
186  * \param ilen     The length of the input data in Bytes.
187  */
188 MBEDTLS_DEPRECATED void mbedtls_sha512_update( mbedtls_sha512_context *ctx,
189                                                const unsigned char *input,
190                                                size_t ilen );
191 
192 /**
193  * \brief          This function finishes the SHA-512 operation, and writes
194  *                 the result to the output buffer.
195  *
196  * \deprecated     Superseded by mbedtls_sha512_finish_ret() in 2.7.0.
197  *
198  * \param ctx      The SHA-512 context. This must be initialized
199  *                 and have a hash operation started.
200  * \param output   The SHA-384 or SHA-512 checksum result. This must
201  *                 be a writable buffer of size \c 64 Bytes.
202  */
203 MBEDTLS_DEPRECATED void mbedtls_sha512_finish( mbedtls_sha512_context *ctx,
204                                                unsigned char output[64] );
205 
206 /**
207  * \brief          This function processes a single data block within
208  *                 the ongoing SHA-512 computation. This function is for
209  *                 internal use only.
210  *
211  * \deprecated     Superseded by mbedtls_internal_sha512_process() in 2.7.0.
212  *
213  * \param ctx      The SHA-512 context. This must be initialized.
214  * \param data     The buffer holding one block of data. This must be
215  *                 a readable buffer of length \c 128 Bytes.
216  */
217 MBEDTLS_DEPRECATED void mbedtls_sha512_process(
218                                             mbedtls_sha512_context *ctx,
219                                             const unsigned char data[128] );
220 
221 #undef MBEDTLS_DEPRECATED
222 #endif /* !MBEDTLS_DEPRECATED_REMOVED */
223 
224 /**
225  * \brief          This function calculates the SHA-512 or SHA-384
226  *                 checksum of a buffer.
227  *
228  *                 The function allocates the context, performs the
229  *                 calculation, and frees the context.
230  *
231  *                 The SHA-512 result is calculated as
232  *                 output = SHA-512(input buffer).
233  *
234  * \param input    The buffer holding the input data. This must be
235  *                 a readable buffer of length \p ilen Bytes.
236  * \param ilen     The length of the input data in Bytes.
237  * \param output   The SHA-384 or SHA-512 checksum result.
238  *                 This must be a writable buffer of length \c 64 Bytes.
239  * \param is384    Determines which function to use. This must be either
240  *                 \c 0 for SHA-512, or \c 1 for SHA-384.
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  * \brief          This function calculates the SHA-512 or SHA-384
258  *                 checksum of a buffer.
259  *
260  *                 The function allocates the context, performs the
261  *                 calculation, and frees the context.
262  *
263  *                 The SHA-512 result is calculated as
264  *                 output = SHA-512(input buffer).
265  *
266  * \deprecated     Superseded by mbedtls_sha512_ret() in 2.7.0
267  *
268  * \param input    The buffer holding the data. This must be a
269  *                 readable buffer of length \p ilen Bytes.
270  * \param ilen     The length of the input data in Bytes.
271  * \param output   The SHA-384 or SHA-512 checksum result. This must
272  *                 be a writable buffer of length \c 64 Bytes.
273  * \param is384    Determines which function to use. This must be either
274  *                 \c 0 for SHA-512, or \c 1 for SHA-384.
275  */
276 MBEDTLS_DEPRECATED void mbedtls_sha512( const unsigned char *input,
277                                         size_t ilen,
278                                         unsigned char output[64],
279                                         int is384 );
280 
281 #undef MBEDTLS_DEPRECATED
282 #endif /* !MBEDTLS_DEPRECATED_REMOVED */
283  /**
284  * \brief          The SHA-384 or SHA-512 checkup routine.
285  *
286  * \return         \c 0 on success.
287  * \return         \c 1 on failure.
288  */
289 int mbedtls_sha512_self_test( int verbose );
290 
291 #ifdef __cplusplus
292 }
293 #endif
294 
295 #endif /* mbedtls_sha512.h */
296