1 /** 2 * \file sha3.h 3 * 4 * \brief This file contains SHA-3 definitions and functions. 5 * 6 * The Secure Hash Algorithms cryptographic 7 * hash functions are defined in <em>FIPS 202: SHA-3 Standard: 8 * Permutation-Based Hash and Extendable-Output Functions </em>. 9 */ 10 /* 11 * Copyright The Mbed TLS Contributors 12 * SPDX-License-Identifier: Apache-2.0 OR GPL-2.0-or-later 13 */ 14 15 #ifndef MBEDTLS_SHA3_H 16 #define MBEDTLS_SHA3_H 17 #include "mbedtls/private_access.h" 18 19 #include "mbedtls/build_info.h" 20 21 #include <stddef.h> 22 #include <stdint.h> 23 24 #ifdef __cplusplus 25 extern "C" { 26 #endif 27 28 /** SHA-3 input data was malformed. */ 29 #define MBEDTLS_ERR_SHA3_BAD_INPUT_DATA -0x0076 30 31 /** 32 * SHA-3 family id. 33 * 34 * It identifies the family (SHA3-256, SHA3-512, etc.) 35 */ 36 37 typedef enum { 38 MBEDTLS_SHA3_NONE = 0, /*!< Operation not defined. */ 39 MBEDTLS_SHA3_224, /*!< SHA3-224 */ 40 MBEDTLS_SHA3_256, /*!< SHA3-256 */ 41 MBEDTLS_SHA3_384, /*!< SHA3-384 */ 42 MBEDTLS_SHA3_512, /*!< SHA3-512 */ 43 } mbedtls_sha3_id; 44 45 /** 46 * \brief The SHA-3 context structure. 47 * 48 * The structure is used SHA-3 checksum calculations. 49 */ 50 typedef struct { 51 uint64_t MBEDTLS_PRIVATE(state[25]); 52 uint32_t MBEDTLS_PRIVATE(index); 53 uint16_t MBEDTLS_PRIVATE(olen); 54 uint16_t MBEDTLS_PRIVATE(max_block_size); 55 } 56 mbedtls_sha3_context; 57 58 /** 59 * \brief This function initializes a SHA-3 context. 60 * 61 * \param ctx The SHA-3 context to initialize. This must not be \c NULL. 62 */ 63 void mbedtls_sha3_init(mbedtls_sha3_context *ctx); 64 65 /** 66 * \brief This function clears a SHA-3 context. 67 * 68 * \param ctx The SHA-3 context to clear. This may be \c NULL, in which 69 * case this function returns immediately. If it is not \c NULL, 70 * it must point to an initialized SHA-3 context. 71 */ 72 void mbedtls_sha3_free(mbedtls_sha3_context *ctx); 73 74 /** 75 * \brief This function clones the state of a SHA-3 context. 76 * 77 * \param dst The destination context. This must be initialized. 78 * \param src The context to clone. This must be initialized. 79 */ 80 void mbedtls_sha3_clone(mbedtls_sha3_context *dst, 81 const mbedtls_sha3_context *src); 82 83 /** 84 * \brief This function starts a SHA-3 checksum 85 * calculation. 86 * 87 * \param ctx The context to use. This must be initialized. 88 * \param id The id of the SHA-3 family. 89 * 90 * \return \c 0 on success. 91 * \return A negative error code on failure. 92 */ 93 int mbedtls_sha3_starts(mbedtls_sha3_context *ctx, mbedtls_sha3_id id); 94 95 /** 96 * \brief This function feeds an input buffer into an ongoing 97 * SHA-3 checksum calculation. 98 * 99 * \param ctx The SHA-3 context. This must be initialized 100 * and have a hash operation started. 101 * \param input The buffer holding the data. This must be a readable 102 * buffer of length \p ilen Bytes. 103 * \param ilen The length of the input data in Bytes. 104 * 105 * \return \c 0 on success. 106 * \return A negative error code on failure. 107 */ 108 int mbedtls_sha3_update(mbedtls_sha3_context *ctx, 109 const uint8_t *input, 110 size_t ilen); 111 112 /** 113 * \brief This function finishes the SHA-3 operation, and writes 114 * the result to the output buffer. 115 * 116 * \param ctx The SHA-3 context. This must be initialized 117 * and have a hash operation started. 118 * \param output The SHA-3 checksum result. 119 * This must be a writable buffer of length \c olen bytes. 120 * \param olen Defines the length of output buffer (in bytes). For SHA-3 224, SHA-3 256, 121 * SHA-3 384 and SHA-3 512 \c olen must equal to 28, 32, 48 and 64, 122 * respectively. 123 * 124 * \return \c 0 on success. 125 * \return A negative error code on failure. 126 */ 127 int mbedtls_sha3_finish(mbedtls_sha3_context *ctx, 128 uint8_t *output, size_t olen); 129 130 /** 131 * \brief This function calculates the SHA-3 132 * checksum of a buffer. 133 * 134 * The function allocates the context, performs the 135 * calculation, and frees the context. 136 * 137 * The SHA-3 result is calculated as 138 * output = SHA-3(id, input buffer, d). 139 * 140 * \param id The id of the SHA-3 family. 141 * \param input The buffer holding the data. This must be a readable 142 * buffer of length \p ilen Bytes. 143 * \param ilen The length of the input data in Bytes. 144 * \param output The SHA-3 checksum result. 145 * This must be a writable buffer of length \c olen bytes. 146 * \param olen Defines the length of output buffer (in bytes). For SHA-3 224, SHA-3 256, 147 * SHA-3 384 and SHA-3 512 \c olen must equal to 28, 32, 48 and 64, 148 * respectively. 149 * 150 * \return \c 0 on success. 151 * \return A negative error code on failure. 152 */ 153 int mbedtls_sha3(mbedtls_sha3_id id, const uint8_t *input, 154 size_t ilen, 155 uint8_t *output, 156 size_t olen); 157 158 #if defined(MBEDTLS_SELF_TEST) 159 /** 160 * \brief Checkup routine for the algorithms implemented 161 * by this module: SHA3-224, SHA3-256, SHA3-384, SHA3-512. 162 * 163 * \return 0 if successful, or 1 if the test failed. 164 */ 165 int mbedtls_sha3_self_test(int verbose); 166 #endif /* MBEDTLS_SELF_TEST */ 167 168 #ifdef __cplusplus 169 } 170 #endif 171 172 #endif /* mbedtls_sha3.h */ 173
