mbedtls/private/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 "tf-psa-crypto/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                 PSA_ERROR_INVALID_ARGUMENT
0030
0031 #if defined(MBEDTLS_DECLARE_PRIVATE_IDENTIFIERS)
0032 /**
0033  * SHA-3 family id.
0034  *
0035  * It identifies the family (SHA3-256, SHA3-512, etc.)
0036  */
0037
0038 typedef enum {
0039     MBEDTLS_SHA3_NONE = 0, /*!< Operation not defined. */
0040     MBEDTLS_SHA3_224, /*!< SHA3-224 */
0041     MBEDTLS_SHA3_256, /*!< SHA3-256 */
0042     MBEDTLS_SHA3_384, /*!< SHA3-384 */
0043     MBEDTLS_SHA3_512, /*!< SHA3-512 */
0044 } mbedtls_sha3_id;
0045 #endif /* MBEDTLS_DECLARE_PRIVATE_IDENTIFIERS */
0046
0047 /**
0048  * \brief          The SHA-3 context structure.
0049  *
0050  *                 The structure is used SHA-3 checksum calculations.
0051  */
0052 typedef struct {
0053     uint64_t MBEDTLS_PRIVATE(state[25]);
0054     uint32_t MBEDTLS_PRIVATE(index);
0055     uint16_t MBEDTLS_PRIVATE(olen);
0056     uint16_t MBEDTLS_PRIVATE(max_block_size);
0057 }
0058 mbedtls_sha3_context;
0059
0060 #if defined(MBEDTLS_DECLARE_PRIVATE_IDENTIFIERS)
0061 /**
0062  * \brief          This function initializes a SHA-3 context.
0063  *
0064  * \param ctx      The SHA-3 context to initialize. This must not be \c NULL.
0065  */
0066 void mbedtls_sha3_init(mbedtls_sha3_context *ctx);
0067
0068 /**
0069  * \brief          This function clears a SHA-3 context.
0070  *
0071  * \param ctx      The SHA-3 context to clear. This may be \c NULL, in which
0072  *                 case this function returns immediately. If it is not \c NULL,
0073  *                 it must point to an initialized SHA-3 context.
0074  */
0075 void mbedtls_sha3_free(mbedtls_sha3_context *ctx);
0076
0077 /**
0078  * \brief          This function clones the state of a SHA-3 context.
0079  *
0080  * \param dst      The destination context. This must be initialized.
0081  * \param src      The context to clone. This must be initialized.
0082  */
0083 void mbedtls_sha3_clone(mbedtls_sha3_context *dst,
0084                         const mbedtls_sha3_context *src);
0085
0086 /**
0087  * \brief          This function starts a SHA-3 checksum
0088  *                 calculation.
0089  *
0090  * \param ctx      The context to use. This must be initialized.
0091  * \param id       The id of the SHA-3 family.
0092  *
0093  * \return         \c 0 on success.
0094  * \return         A negative error code on failure.
0095  */
0096 int mbedtls_sha3_starts(mbedtls_sha3_context *ctx, mbedtls_sha3_id id);
0097
0098 /**
0099  * \brief          This function feeds an input buffer into an ongoing
0100  *                 SHA-3 checksum calculation.
0101  *
0102  * \param ctx      The SHA-3 context. This must be initialized
0103  *                 and have a hash operation started.
0104  * \param input    The buffer holding the data. This must be a readable
0105  *                 buffer of length \p ilen Bytes.
0106  * \param ilen     The length of the input data in Bytes.
0107  *
0108  * \return         \c 0 on success.
0109  * \return         A negative error code on failure.
0110  */
0111 int mbedtls_sha3_update(mbedtls_sha3_context *ctx,
0112                         const uint8_t *input,
0113                         size_t ilen);
0114
0115 /**
0116  * \brief          This function finishes the SHA-3 operation, and writes
0117  *                 the result to the output buffer.
0118  *
0119  * \param ctx      The SHA-3 context. This must be initialized
0120  *                 and have a hash operation started.
0121  * \param output   The SHA-3 checksum result.
0122  *                 This must be a writable buffer of length \c olen bytes.
0123  * \param olen     Defines the length of output buffer (in bytes). For SHA-3 224, SHA-3 256,
0124  *                 SHA-3 384 and SHA-3 512 \c olen must equal to 28, 32, 48 and 64,
0125  *                 respectively.
0126  *
0127  * \return         \c 0 on success.
0128  * \return         A negative error code on failure.
0129  */
0130 int mbedtls_sha3_finish(mbedtls_sha3_context *ctx,
0131                         uint8_t *output, size_t olen);
0132
0133 /**
0134  * \brief          This function calculates the SHA-3
0135  *                 checksum of a buffer.
0136  *
0137  *                 The function allocates the context, performs the
0138  *                 calculation, and frees the context.
0139  *
0140  *                 The SHA-3 result is calculated as
0141  *                 output = SHA-3(id, input buffer, d).
0142  *
0143  * \param id       The id of the SHA-3 family.
0144  * \param input    The buffer holding the data. This must be a readable
0145  *                 buffer of length \p ilen Bytes.
0146  * \param ilen     The length of the input data in Bytes.
0147  * \param output   The SHA-3 checksum result.
0148  *                 This must be a writable buffer of length \c olen bytes.
0149  * \param olen     Defines the length of output buffer (in bytes). For SHA-3 224, SHA-3 256,
0150  *                 SHA-3 384 and SHA-3 512 \c olen must equal to 28, 32, 48 and 64,
0151  *                 respectively.
0152  *
0153  * \return         \c 0 on success.
0154  * \return         A negative error code on failure.
0155  */
0156 int mbedtls_sha3(mbedtls_sha3_id id, const uint8_t *input,
0157                  size_t ilen,
0158                  uint8_t *output,
0159                  size_t olen);
0160
0161 #if defined(MBEDTLS_SELF_TEST)
0162 /**
0163  * \brief          Checkup routine for the algorithms implemented
0164  *                 by this module: SHA3-224, SHA3-256, SHA3-384, SHA3-512.
0165  *
0166  * \return         0 if successful, or 1 if the test failed.
0167  */
0168 int mbedtls_sha3_self_test(int verbose);
0169 #endif /* MBEDTLS_SELF_TEST */
0170
0171 #endif /* MBEDTLS_DECLARE_PRIVATE_IDENTIFIERS */
0172
0173 #ifdef __cplusplus
0174 }
0175 #endif
0176
0177 #endif /* mbedtls_sha3.h */