include/mbedtls/sha3.h

0001 /**
0002  * \file sha3.h
0003  *
0004  * \brief This file contains SHA-3 definitions and functions.
0005  *
0006  * The Secure Hash Algorithms cryptographic
0007  * hash functions are defined in <em>FIPS 202: SHA-3 Standard:
0008  * Permutation-Based Hash and Extendable-Output Functions </em>.
0009  */
0010 /*
0011  *  Copyright The Mbed TLS Contributors
0012  *  SPDX-License-Identifier: Apache-2.0 OR GPL-2.0-or-later
0013  */
0014
0015 #ifndef MBEDTLS_SHA3_H
0016 #define MBEDTLS_SHA3_H
0017 #include "mbedtls/private_access.h"
0018
0019 #include "mbedtls/build_info.h"
0020
0021 #include <stddef.h>
0022 #include <stdint.h>
0023
0024 #ifdef __cplusplus
0025 extern "C" {
0026 #endif
0027
0028 /** SHA-3 input data was malformed. */
0029 #define MBEDTLS_ERR_SHA3_BAD_INPUT_DATA                 -0x0076
0030
0031 /**
0032  * SHA-3 family id.
0033  *
0034  * It identifies the family (SHA3-256, SHA3-512, etc.)
0035  */
0036
0037 typedef enum {
0038     MBEDTLS_SHA3_NONE = 0, /*!< Operation not defined. */
0039     MBEDTLS_SHA3_224, /*!< SHA3-224 */
0040     MBEDTLS_SHA3_256, /*!< SHA3-256 */
0041     MBEDTLS_SHA3_384, /*!< SHA3-384 */
0042     MBEDTLS_SHA3_512, /*!< SHA3-512 */
0043 } mbedtls_sha3_id;
0044
0045 /**
0046  * \brief          The SHA-3 context structure.
0047  *
0048  *                 The structure is used SHA-3 checksum calculations.
0049  */
0050 typedef struct {
0051     uint64_t MBEDTLS_PRIVATE(state[25]);
0052     uint32_t MBEDTLS_PRIVATE(index);
0053     uint16_t MBEDTLS_PRIVATE(olen);
0054     uint16_t MBEDTLS_PRIVATE(max_block_size);
0055 }
0056 mbedtls_sha3_context;
0057
0058 /**
0059  * \brief          This function initializes a SHA-3 context.
0060  *
0061  * \param ctx      The SHA-3 context to initialize. This must not be \c NULL.
0062  */
0063 void mbedtls_sha3_init(mbedtls_sha3_context *ctx);
0064
0065 /**
0066  * \brief          This function clears a SHA-3 context.
0067  *
0068  * \param ctx      The SHA-3 context to clear. This may be \c NULL, in which
0069  *                 case this function returns immediately. If it is not \c NULL,
0070  *                 it must point to an initialized SHA-3 context.
0071  */
0072 void mbedtls_sha3_free(mbedtls_sha3_context *ctx);
0073
0074 /**
0075  * \brief          This function clones the state of a SHA-3 context.
0076  *
0077  * \param dst      The destination context. This must be initialized.
0078  * \param src      The context to clone. This must be initialized.
0079  */
0080 void mbedtls_sha3_clone(mbedtls_sha3_context *dst,
0081                         const mbedtls_sha3_context *src);
0082
0083 /**
0084  * \brief          This function starts a SHA-3 checksum
0085  *                 calculation.
0086  *
0087  * \param ctx      The context to use. This must be initialized.
0088  * \param id       The id of the SHA-3 family.
0089  *
0090  * \return         \c 0 on success.
0091  * \return         A negative error code on failure.
0092  */
0093 int mbedtls_sha3_starts(mbedtls_sha3_context *ctx, mbedtls_sha3_id id);
0094
0095 /**
0096  * \brief          This function feeds an input buffer into an ongoing
0097  *                 SHA-3 checksum calculation.
0098  *
0099  * \param ctx      The SHA-3 context. This must be initialized
0100  *                 and have a hash operation started.
0101  * \param input    The buffer holding the data. This must be a readable
0102  *                 buffer of length \p ilen Bytes.
0103  * \param ilen     The length of the input data in Bytes.
0104  *
0105  * \return         \c 0 on success.
0106  * \return         A negative error code on failure.
0107  */
0108 int mbedtls_sha3_update(mbedtls_sha3_context *ctx,
0109                         const uint8_t *input,
0110                         size_t ilen);
0111
0112 /**
0113  * \brief          This function finishes the SHA-3 operation, and writes
0114  *                 the result to the output buffer.
0115  *
0116  * \param ctx      The SHA-3 context. This must be initialized
0117  *                 and have a hash operation started.
0118  * \param output   The SHA-3 checksum result.
0119  *                 This must be a writable buffer of length \c olen bytes.
0120  * \param olen     Defines the length of output buffer (in bytes). For SHA-3 224, SHA-3 256,
0121  *                 SHA-3 384 and SHA-3 512 \c olen must equal to 28, 32, 48 and 64,
0122  *                 respectively.
0123  *
0124  * \return         \c 0 on success.
0125  * \return         A negative error code on failure.
0126  */
0127 int mbedtls_sha3_finish(mbedtls_sha3_context *ctx,
0128                         uint8_t *output, size_t olen);
0129
0130 /**
0131  * \brief          This function calculates the SHA-3
0132  *                 checksum of a buffer.
0133  *
0134  *                 The function allocates the context, performs the
0135  *                 calculation, and frees the context.
0136  *
0137  *                 The SHA-3 result is calculated as
0138  *                 output = SHA-3(id, input buffer, d).
0139  *
0140  * \param id       The id of the SHA-3 family.
0141  * \param input    The buffer holding the data. This must be a readable
0142  *                 buffer of length \p ilen Bytes.
0143  * \param ilen     The length of the input data in Bytes.
0144  * \param output   The SHA-3 checksum result.
0145  *                 This must be a writable buffer of length \c olen bytes.
0146  * \param olen     Defines the length of output buffer (in bytes). For SHA-3 224, SHA-3 256,
0147  *                 SHA-3 384 and SHA-3 512 \c olen must equal to 28, 32, 48 and 64,
0148  *                 respectively.
0149  *
0150  * \return         \c 0 on success.
0151  * \return         A negative error code on failure.
0152  */
0153 int mbedtls_sha3(mbedtls_sha3_id id, const uint8_t *input,
0154                  size_t ilen,
0155                  uint8_t *output,
0156                  size_t olen);
0157
0158 #if defined(MBEDTLS_SELF_TEST)
0159 /**
0160  * \brief          Checkup routine for the algorithms implemented
0161  *                 by this module: SHA3-224, SHA3-256, SHA3-384, SHA3-512.
0162  *
0163  * \return         0 if successful, or 1 if the test failed.
0164  */
0165 int mbedtls_sha3_self_test(int verbose);
0166 #endif /* MBEDTLS_SELF_TEST */
0167
0168 #ifdef __cplusplus
0169 }
0170 #endif
0171
0172 #endif /* mbedtls_sha3.h */