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 #include "mbedtls/private_access.h" 15 16 #include "mbedtls/build_info.h" 17 18 #include <stddef.h> 19 #include <stdint.h> 20 21 /** SHA-512 input data was malformed. */ 22 #define MBEDTLS_ERR_SHA512_BAD_INPUT_DATA -0x0075 23 24 #ifdef __cplusplus 25 extern "C" { 26 #endif 27 28 #if !defined(MBEDTLS_SHA512_ALT) 29 // Regular implementation 30 // 31 32 /** 33 * \brief The SHA-512 context structure. 34 * 35 * The structure is used both for SHA-384 and for SHA-512 36 * checksum calculations. The choice between these two is 37 * made in the call to mbedtls_sha512_starts(). 38 */ 39 typedef struct mbedtls_sha512_context { 40 uint64_t MBEDTLS_PRIVATE(total)[2]; /*!< The number of Bytes processed. */ 41 uint64_t MBEDTLS_PRIVATE(state)[8]; /*!< The intermediate digest state. */ 42 unsigned char MBEDTLS_PRIVATE(buffer)[128]; /*!< The data block being processed. */ 43 #if defined(MBEDTLS_SHA384_C) 44 int MBEDTLS_PRIVATE(is384); /*!< Determines which function to use: 45 0: Use SHA-512, or 1: Use SHA-384. */ 46 #endif 47 } 48 mbedtls_sha512_context; 49 50 #else /* MBEDTLS_SHA512_ALT */ 51 #include "sha512_alt.h" 52 #endif /* MBEDTLS_SHA512_ALT */ 53 54 /** 55 * \brief This function initializes a SHA-512 context. 56 * 57 * \param ctx The SHA-512 context to initialize. This must 58 * not be \c NULL. 59 */ 60 void mbedtls_sha512_init(mbedtls_sha512_context *ctx); 61 62 /** 63 * \brief This function clears a SHA-512 context. 64 * 65 * \param ctx The SHA-512 context to clear. This may be \c NULL, 66 * in which case this function does nothing. If it 67 * is not \c NULL, it must point to an initialized 68 * SHA-512 context. 69 */ 70 void mbedtls_sha512_free(mbedtls_sha512_context *ctx); 71 72 /** 73 * \brief This function clones the state of a SHA-512 context. 74 * 75 * \param dst The destination context. This must be initialized. 76 * \param src The context to clone. This must be initialized. 77 */ 78 void mbedtls_sha512_clone(mbedtls_sha512_context *dst, 79 const mbedtls_sha512_context *src); 80 81 /** 82 * \brief This function starts a SHA-384 or SHA-512 checksum 83 * calculation. 84 * 85 * \param ctx The SHA-512 context to use. This must be initialized. 86 * \param is384 Determines which function to use. This must be 87 * either \c 0 for SHA-512, or \c 1 for SHA-384. 88 * 89 * \note is384 must be defined accordingly to the enabled 90 * MBEDTLS_SHA384_C/MBEDTLS_SHA512_C symbols otherwise the 91 * function will return #MBEDTLS_ERR_SHA512_BAD_INPUT_DATA. 92 * 93 * \return \c 0 on success. 94 * \return A negative error code on failure. 95 */ 96 int mbedtls_sha512_starts(mbedtls_sha512_context *ctx, int is384); 97 98 /** 99 * \brief This function feeds an input buffer into an ongoing 100 * SHA-512 checksum calculation. 101 * 102 * \param ctx The SHA-512 context. This must be initialized 103 * and have a hash operation started. 104 * \param input The buffer holding the input data. This must 105 * be a readable buffer of length \p ilen Bytes. 106 * \param ilen The length of the input data in Bytes. 107 * 108 * \return \c 0 on success. 109 * \return A negative error code on failure. 110 */ 111 int mbedtls_sha512_update(mbedtls_sha512_context *ctx, 112 const unsigned char *input, 113 size_t ilen); 114 115 /** 116 * \brief This function finishes the SHA-512 operation, and writes 117 * the result to the output buffer. 118 * 119 * \param ctx The SHA-512 context. This must be initialized 120 * and have a hash operation started. 121 * \param output The SHA-384 or SHA-512 checksum result. 122 * This must be a writable buffer of length \c 64 bytes 123 * for SHA-512, \c 48 bytes for SHA-384. 124 * 125 * \return \c 0 on success. 126 * \return A negative error code on failure. 127 */ 128 int mbedtls_sha512_finish(mbedtls_sha512_context *ctx, 129 unsigned char *output); 130 131 /** 132 * \brief This function processes a single data block within 133 * the ongoing SHA-512 computation. 134 * This function is for internal use only. 135 * 136 * \param ctx The SHA-512 context. This must be initialized. 137 * \param data The buffer holding one block of data. This 138 * must be a readable buffer of length \c 128 Bytes. 139 * 140 * \return \c 0 on success. 141 * \return A negative error code on failure. 142 */ 143 int mbedtls_internal_sha512_process(mbedtls_sha512_context *ctx, 144 const unsigned char data[128]); 145 146 /** 147 * \brief This function calculates the SHA-512 or SHA-384 148 * checksum of a buffer. 149 * 150 * The function allocates the context, performs the 151 * calculation, and frees the context. 152 * 153 * The SHA-512 result is calculated as 154 * output = SHA-512(input buffer). 155 * 156 * \param input The buffer holding the input data. This must be 157 * a readable buffer of length \p ilen Bytes. 158 * \param ilen The length of the input data in Bytes. 159 * \param output The SHA-384 or SHA-512 checksum result. 160 * This must be a writable buffer of length \c 64 bytes 161 * for SHA-512, \c 48 bytes for SHA-384. 162 * \param is384 Determines which function to use. This must be either 163 * \c 0 for SHA-512, or \c 1 for SHA-384. 164 * 165 * \note is384 must be defined accordingly with the supported 166 * symbols in the config file. If: 167 * - is384 is 0, but \c MBEDTLS_SHA384_C is not defined, or 168 * - is384 is 1, but \c MBEDTLS_SHA512_C is not defined 169 * then the function will return 170 * #MBEDTLS_ERR_SHA512_BAD_INPUT_DATA. 171 * 172 * \return \c 0 on success. 173 * \return A negative error code on failure. 174 */ 175 int mbedtls_sha512(const unsigned char *input, 176 size_t ilen, 177 unsigned char *output, 178 int is384); 179 180 #if defined(MBEDTLS_SELF_TEST) 181 182 #if defined(MBEDTLS_SHA384_C) 183 /** 184 * \brief The SHA-384 checkup routine. 185 * 186 * \return \c 0 on success. 187 * \return \c 1 on failure. 188 */ 189 int mbedtls_sha384_self_test(int verbose); 190 #endif /* MBEDTLS_SHA384_C */ 191 192 #if defined(MBEDTLS_SHA512_C) 193 /** 194 * \brief The SHA-512 checkup routine. 195 * 196 * \return \c 0 on success. 197 * \return \c 1 on failure. 198 */ 199 int mbedtls_sha512_self_test(int verbose); 200 #endif /* MBEDTLS_SHA512_C */ 201 202 #endif /* MBEDTLS_SELF_TEST */ 203 204 #ifdef __cplusplus 205 } 206 #endif 207 208 #endif /* mbedtls_sha512.h */ 209
