SHA-3 support

ChangeLog.d/sha3.txt

@@ -0,0 +1,3 @@
+Features
+    * Add SHA3 family hash functions.
+

include/mbedtls/error.h

@@ -73,6 +73,7 @@
  * SHA1      1                  0x0035-0x0035 0x0073-0x0073
  * SHA256    1                  0x0037-0x0037 0x0074-0x0074
  * SHA512    1                  0x0039-0x0039 0x0075-0x0075
+ * SHA-3     1                  0x0076-0x0076
  * CHACHA20  3                  0x0051-0x0055
  * POLY1305  3                  0x0057-0x005B
  * CHACHAPOLY 2 0x0054-0x0056

include/mbedtls/mbedtls_config.h

@@ -3164,6 +3164,17 @@
  */
 #define MBEDTLS_SHA512_C
 
+/**
+ * \def MBEDTLS_SHA3_C
+ *
+ * Enable the SHA3 cryptographic hash algorithm.
+ *
+ * Module:  library/sha3.c
+ *
+ * This module adds support for SHA3.
+ */
+#define MBEDTLS_SHA3_C
+
 /**
  * \def MBEDTLS_SHA512_USE_A64_CRYPTO_IF_PRESENT
  *

include/mbedtls/md.h

@@ -149,9 +149,13 @@ typedef enum {
     MBEDTLS_MD_SHA384,    /**< The SHA-384 message digest. */
     MBEDTLS_MD_SHA512,    /**< The SHA-512 message digest. */
     MBEDTLS_MD_RIPEMD160, /**< The RIPEMD-160 message digest. */
+    MBEDTLS_MD_SHA3_224,    /**< The SHA3-224 message digest. */
+    MBEDTLS_MD_SHA3_256,    /**< The SHA3-256 message digest. */
+    MBEDTLS_MD_SHA3_384,    /**< The SHA3-384 message digest. */
+    MBEDTLS_MD_SHA3_512,    /**< The SHA3-512 message digest. */
 } mbedtls_md_type_t;
 
-#if defined(MBEDTLS_MD_CAN_SHA512)
+#if defined(MBEDTLS_MD_CAN_SHA512) || defined(MBEDTLS_SHA3_C)
 #define MBEDTLS_MD_MAX_SIZE         64  /* longest known is SHA512 */
 #elif defined(MBEDTLS_MD_CAN_SHA384)
 #define MBEDTLS_MD_MAX_SIZE         48  /* longest known is SHA384 */
@@ -164,7 +168,9 @@ typedef enum {
                                            or smaller (MD5 and earlier) */
 #endif
 
-#if defined(MBEDTLS_MD_CAN_SHA512)
+#if defined(MBEDTLS_SHA3_C)
+#define MBEDTLS_MD_MAX_BLOCK_SIZE         144 /* the longest known is SHA3-224 */
+#elif defined(MBEDTLS_MD_CAN_SHA512)
 #define MBEDTLS_MD_MAX_BLOCK_SIZE         128
 #else
 #define MBEDTLS_MD_MAX_BLOCK_SIZE         64

include/mbedtls/sha3.h

@@ -0,0 +1,199 @@
+/**
+ * \file sha3.h
+ *
+ * \brief This file contains SHA3 definitions and functions.
+ *
+ * The Secure Hash Algorithms cryptographic
+ * hash functions are defined in <em>FIPS 202: SHA-3 Standard:
+ * Permutation-Based Hash and Extendable-Output Functions </em>.
+ */
+/*
+ *  Copyright The Mbed TLS Contributors
+ *  SPDX-License-Identifier: Apache-2.0
+ *
+ *  Licensed under the Apache License, Version 2.0 (the "License"); you may
+ *  not use this file except in compliance with the License.
+ *  You may obtain a copy of the License at
+ *
+ *  http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  Unless required by applicable law or agreed to in writing, software
+ *  distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ *  WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *  See the License for the specific language governing permissions and
+ *  limitations under the License.
+ */
+
+#ifndef MBEDTLS_SHA3_H
+#define MBEDTLS_SHA3_H
+#include "mbedtls/private_access.h"
+
+#include "mbedtls/build_info.h"
+
+#include <stddef.h>
+#include <stdint.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/** SHA3 input data was malformed. */
+#define MBEDTLS_ERR_SHA3_BAD_INPUT_DATA                 -0x0076
+
+/**
+ * SHA-3 family id.
+ *
+ * It identifies the family (SHA3-256, SHA3-512, etc.)
+ */
+
+typedef enum {
+    MBEDTLS_SHA3_NONE = 0, /*!< Operation not defined. */
+    MBEDTLS_SHA3_224, /*!< SHA3-224 */
+    MBEDTLS_SHA3_256, /*!< SHA3-256 */
+    MBEDTLS_SHA3_384, /*!< SHA3-384 */
+    MBEDTLS_SHA3_512, /*!< SHA3-512 */
+} mbedtls_sha3_id;
+
+struct mbedtls_sha3_context;
+typedef struct mbedtls_sha3_family_functions {
+    mbedtls_sha3_id id;
+
+    uint16_t r;
+    uint16_t olen;
+    uint8_t xor_byte;
+}
+mbedtls_sha3_family_functions;
+
+/**
+ * \brief          The SHA-3 context structure.
+ *
+ *                 The structure is used SHA-3 checksum calculations.
+ */
+typedef struct mbedtls_sha3_context {
+    uint64_t state[25];
+    uint8_t index;
+    uint8_t id;
+
+    uint16_t r;
+    uint16_t olen;
+    uint8_t xor_byte;
+    uint16_t max_block_size;
+}
+mbedtls_sha3_context;
+
+/**
+ * \brief          This function initializes a SHA-3 context.
+ *
+ * \param ctx      The SHA-3 context to initialize. This must not be \c NULL.
+ */
+void mbedtls_sha3_init(mbedtls_sha3_context *ctx);
+
+/**
+ * \brief          This function clears a SHA-3 context.
+ *
+ * \param ctx      The SHA-3 context to clear. This may be \c NULL, in which
+ *                 case this function returns immediately. If it is not \c NULL,
+ *                 it must point to an initialized SHA-3 context.
+ */
+void mbedtls_sha3_free(mbedtls_sha3_context *ctx);
+
+/**
+ * \brief          This function clones the state of a SHA-3 context.
+ *
+ * \param dst      The destination context. This must be initialized.
+ * \param src      The context to clone. This must be initialized.
+ */
+void mbedtls_sha3_clone(mbedtls_sha3_context *dst,
+                        const mbedtls_sha3_context *src);
+
+/**
+ * \brief          This function starts a SHA-3 checksum
+ *                 calculation.
+ *
+ * \param ctx      The context to use. This must be initialized.
+ * \param id       The id of the SHA-3 family.
+ *
+ * \return         \c 0 on success.
+ * \return         A negative error code on failure.
+ */
+int mbedtls_sha3_starts(mbedtls_sha3_context *ctx, mbedtls_sha3_id id);
+
+/**
+ * \brief          This function feeds an input buffer into an ongoing
+ *                 SHA-3 checksum calculation.
+ *
+ * \param ctx      The SHA-3 context. This must be initialized
+ *                 and have a hash operation started.
+ * \param input    The buffer holding the data. This must be a readable
+ *                 buffer of length \p ilen Bytes.
+ * \param ilen     The length of the input data in Bytes.
+ *
+ * \return         \c 0 on success.
+ * \return         A negative error code on failure.
+ */
+int mbedtls_sha3_update(mbedtls_sha3_context *ctx,
+                        const uint8_t *input,
+                        size_t ilen);
+
+/**
+ * \brief          This function finishes the SHA-3 operation, and writes
+ *                 the result to the output buffer.
+ *
+ * \param ctx      The SHA-3 context. This must be initialized
+ *                 and have a hash operation started.
+ * \param output   The SHA-3 checksum result.
+ *                 This must be a writable buffer of length \c olen bytes.
+ * \param olen     Defines the length of output buffer (in bytes). For SHA-3 224, SHA-3 256,
+ *                 SHA-3 384 and SHA-3 512 \c olen must equal to 28, 32, 48 and 64,
+ *                 respectively.
+ *
+ * \return         \c 0 on success.
+ * \return         A negative error code on failure.
+ */
+int mbedtls_sha3_finish(mbedtls_sha3_context *ctx,
+                        uint8_t *output, size_t olen);
+
+/**
+ * \brief          This function calculates the SHA-3
+ *                 checksum of a buffer.
+ *
+ *                 The function allocates the context, performs the
+ *                 calculation, and frees the context.
+ *
+ *                 The SHA-3 result is calculated as
+ *                 output = SHA-3(id, input buffer, d).
+ *
+ * \param id       The id of the SHA-3 family.
+ * \param input    The buffer holding the data. This must be a readable
+ *                 buffer of length \p ilen Bytes.
+ * \param ilen     The length of the input data in Bytes.
+ * \param output   The SHA-3 checksum result.
+ *                 This must be a writable buffer of length \c olen bytes.
+ * \param olen     Defines the length of output buffer (in bytes). For SHA-3 224, SHA-3 256,
+ *                 SHA-3 384 and SHA-3 512 \c olen must equal to 28, 32, 48 and 64,
+ *                 respectively.
+ *
+ * \return         \c 0 on success.
+ * \return         A negative error code on failure.
+ */
+int mbedtls_sha3(mbedtls_sha3_id id, const uint8_t *input,
+                 size_t ilen,
+                 uint8_t *output,
+                 size_t olen);
+
+#if defined(MBEDTLS_SELF_TEST)
+/**
+ * \brief          Checkup routine for the algorithms implemented
+ *                 by this module: SHA3-224, SHA3-256, SHA3-384, SHA3-512,
+ *                 SHAKE128, SHAKE256, cSHAKE128 and cSHAKE256.
+ *
+ * \return         0 if successful, or 1 if the test failed.
+ */
+int mbedtls_sha3_self_test(int verbose);
+#endif /* MBEDTLS_SELF_TEST */
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* mbedtls_sha3.h */

library/CMakeLists.txt

@@ -84,6 +84,7 @@ set(src_crypto
     sha1.c
     sha256.c
     sha512.c
+    sha3.c
     threading.c
     timing.c
     version.c

library/Makefile

@@ -149,6 +149,7 @@ OBJS_CRYPTO= \
 	     sha1.o \
 	     sha256.o \
 	     sha512.o \
+	     sha3.o \
 	     threading.o \
 	     timing.o \
 	     version.o \