crypto/evp: Add SHA3-256 and SHA3-512

Bug: 462683293
Signed-off-by: Xiangfei Ding <xfding@google.com>
Change-Id: Ibfb5587ab010f7d9e7ca2f42bad2e2c36a6a6964
Reviewed-on: https://boringssl-review.googlesource.com/c/boringssl/+/103687
Reviewed-by: David Benjamin <davidben@google.com>

build.json

@@ -378,6 +378,7 @@
             "crypto/evp/p_ec.cc",
             "crypto/evp/p_ed25519.cc",
             "crypto/evp/p_hkdf.cc",
+            "crypto/evp/p_keccak.cc",
             "crypto/evp/p_mldsa.cc",
             "crypto/evp/p_mlkem.cc",
             "crypto/evp/p_rsa.cc",

crypto/digest/digest_test.cc

@@ -60,6 +60,8 @@ static const MD sha512 = {"SHA512", &EVP_sha512, &SHA512};
 static const MD sha512_256 = {"SHA512-256", &EVP_sha512_256, &SHA512_256};
 static const MD md5_sha1 = {"MD5-SHA1", &EVP_md5_sha1, nullptr};
 static const MD blake2b256 = {"BLAKE2b-256", &EVP_blake2b256, nullptr};
+static const MD sha3_256 = {"SHA3-256", &EVP_sha3_256, nullptr};
+static const MD sha3_512 = {"SHA3-512", &EVP_sha3_512, nullptr};
 
 struct DigestTestVector {
   // md is the digest to test.
@@ -155,6 +157,24 @@ static const DigestTestVector kTestVectors[] = {
     // BLAKE2b-256 tests.
     {blake2b256, "abc", 1,
      "bddd813c634239723171ef3fee98579b94964e3bb1cb3e427262c8c068d52319"},
+
+    // SHA3-256 tests, from
+    // https://csrc.nist.gov/CSRC/media/Projects/Cryptographic-Standards-and-Guidelines/documents/examples/SHA3-256_Msg0.pdf
+    // https://csrc.nist.gov/CSRC/media/Projects/Cryptographic-Standards-and-Guidelines/documents/examples/SHA3-256_1600.pdf
+    {sha3_256, "", 1,
+     "a7ffc6f8bf1ed76651c14756a061d662f580ff4de43b49fa82d80a4b80f8434a"},
+    {sha3_256, "\xa3", 200,
+     "79f38adec5c20307a98ef76e8324afbfd46cfd81b22e3973c65fa1bd9de31787"},
+
+    // SHA3-512 tests, from
+    // https://csrc.nist.gov/CSRC/media/Projects/Cryptographic-Standards-and-Guidelines/documents/examples/SHA3-512_Msg0.pdf
+    // https://csrc.nist.gov/CSRC/media/Projects/Cryptographic-Standards-and-Guidelines/documents/examples/SHA3-512_1600.pdf
+    {sha3_512, "", 1,
+     "a69f73cca23a9ac5c8b567dc185a756e97c982164fe25859e0d1dcc1475c80a6"
+     "15b2123af1f5f94c11e3e9402c3ac558f500199d95b6d3e301758586281dcd26"},
+    {sha3_512, "\xa3", 200,
+     "e76dfad22084a8b1467fcf2ffa58361bec7628edf5f3fdc0e4805dc48caeeca8"
+     "1b7c13c30adf52a3659584739a2df46be589c51ca1a4a8416df6545a1ce8ba00"},
 };
 
 static void CompareDigest(const DigestTestVector *test, const uint8_t *digest,

crypto/evp/p_keccak.cc

@@ -0,0 +1,72 @@
+// Copyright 2026 The BoringSSL Authors
+//
+// 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
+//
+//     https://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.
+
+// Family of Keccak-derived hash functions including:
+// - SHA3-256
+// - SHA3-512
+
+#include <openssl/evp.h>
+
+#include "../fipsmodule/digest/internal.h"  // IWYU pragma: keep
+#include "../fipsmodule/keccak/internal.h"
+
+BSSL_NAMESPACE_BEGIN
+namespace {
+template <boringssl_keccak_config_t Config>
+void keccak_init(EVP_MD_CTX *ctx) {
+  BORINGSSL_keccak_init(reinterpret_cast<BORINGSSL_keccak_st *>(ctx->md_data),
+                        Config);
+}
+
+void keccak_update(EVP_MD_CTX *ctx, const void *data, size_t count) {
+  BORINGSSL_keccak_absorb(reinterpret_cast<BORINGSSL_keccak_st *>(ctx->md_data),
+                          static_cast<const uint8_t *>(data), count);
+}
+
+template <size_t Size>
+void keccak_final(EVP_MD_CTX *ctx, uint8_t *out) {
+  BORINGSSL_keccak_squeeze(
+      reinterpret_cast<BORINGSSL_keccak_st *>(ctx->md_data),
+      static_cast<uint8_t *>(out), Size);
+}
+
+constexpr EVP_MD evp_md_sha3_256 = {
+    /*type=*/NID_undef,
+    /*md_size=*/SHA3_256_DIGEST_LENGTH,
+    /*flags=*/0,
+    /*init=*/keccak_init<boringssl_sha3_256>,
+    /*update=*/keccak_update,
+    /*final=*/keccak_final<SHA3_256_DIGEST_LENGTH>,
+    /*block_size=*/SHA3_256_CBLOCK,
+    /*ctx_size=*/sizeof(BORINGSSL_keccak_st),
+};
+
+constexpr EVP_MD evp_md_sha3_512 = {
+    /*type=*/NID_undef,
+    /*md_size=*/SHA3_512_DIGEST_LENGTH,
+    /*flags=*/0,
+    /*init=*/keccak_init<boringssl_sha3_512>,
+    /*update=*/keccak_update,
+    /*final=*/keccak_final<SHA3_512_DIGEST_LENGTH>,
+    /*block_size=*/SHA3_512_CBLOCK,
+    /*ctx_size=*/sizeof(BORINGSSL_keccak_st),
+};
+
+static_assert(sizeof(BORINGSSL_keccak_st) <= EVP_MAX_MD_DATA_SIZE);
+static_assert(SHA3_256_CBLOCK <= EVP_MAX_MD_BLOCK_SIZE);
+}  // namespace
+BSSL_NAMESPACE_END
+
+const EVP_MD *EVP_sha3_256() { return &bssl::evp_md_sha3_256; }
+const EVP_MD *EVP_sha3_512() { return &bssl::evp_md_sha3_512; }

crypto/fipsmodule/keccak/internal.h

@@ -22,6 +22,15 @@
 
 BSSL_NAMESPACE_BEGIN
 
+#define BITS_TO_BYTES(BITS) ((BITS) / 8)
+#define SHA3_256_DIGEST_LENGTH BITS_TO_BYTES(256)
+#define SHA3_384_DIGEST_LENGTH BITS_TO_BYTES(384)
+#define SHA3_512_DIGEST_LENGTH BITS_TO_BYTES(512)
+#define SHA3_BLOCK_SIZE(BITS) BITS_TO_BYTES(1600 - 2 * (BITS))
+#define SHA3_256_CBLOCK SHA3_BLOCK_SIZE(256)
+#define SHA3_384_CBLOCK SHA3_BLOCK_SIZE(384)
+#define SHA3_512_CBLOCK SHA3_BLOCK_SIZE(512)
+
 enum boringssl_keccak_config_t : int32_t {
   boringssl_sha3_256,
   boringssl_sha3_512,

gen/sources.bzl

@@ -393,6 +393,7 @@ crypto_sources = [
     "crypto/evp/p_ec.cc",
     "crypto/evp/p_ed25519.cc",
     "crypto/evp/p_hkdf.cc",
+    "crypto/evp/p_keccak.cc",
     "crypto/evp/p_mldsa.cc",
     "crypto/evp/p_mlkem.cc",
     "crypto/evp/p_rsa.cc",

gen/sources.cmake

@@ -411,6 +411,7 @@ set(
   crypto/evp/p_ec.cc
   crypto/evp/p_ed25519.cc
   crypto/evp/p_hkdf.cc
+  crypto/evp/p_keccak.cc
   crypto/evp/p_mldsa.cc
   crypto/evp/p_mlkem.cc
   crypto/evp/p_rsa.cc

gen/sources.gni

@@ -393,6 +393,7 @@ crypto_sources = [
   "crypto/evp/p_ec.cc",
   "crypto/evp/p_ed25519.cc",
   "crypto/evp/p_hkdf.cc",
+  "crypto/evp/p_keccak.cc",
   "crypto/evp/p_mldsa.cc",
   "crypto/evp/p_mlkem.cc",
   "crypto/evp/p_rsa.cc",

gen/sources.json

@@ -377,6 +377,7 @@
       "crypto/evp/p_ec.cc",
       "crypto/evp/p_ed25519.cc",
       "crypto/evp/p_hkdf.cc",
+      "crypto/evp/p_keccak.cc",
       "crypto/evp/p_mldsa.cc",
       "crypto/evp/p_mlkem.cc",
       "crypto/evp/p_rsa.cc",

gen/sources.mk

@@ -385,6 +385,7 @@ boringssl_crypto_sources := \
   crypto/evp/p_ec.cc \
   crypto/evp/p_ed25519.cc \
   crypto/evp/p_hkdf.cc \
+  crypto/evp/p_keccak.cc \
   crypto/evp/p_mldsa.cc \
   crypto/evp/p_mlkem.cc \
   crypto/evp/p_rsa.cc \

include/openssl/digest.h

@@ -44,6 +44,15 @@ OPENSSL_EXPORT const EVP_MD *EVP_sha512(void);
 OPENSSL_EXPORT const EVP_MD *EVP_sha512_256(void);
 OPENSSL_EXPORT const EVP_MD *EVP_blake2b256(void);
 
+// SHA-3 family of digest functions.
+//
+// WARNING: Prefer to use SHA-2 (e.g. `EVP_sha256`) over SHA-3. Despite being a
+// newer hash function, SHA-3 performs poorly and should only be used when
+// necessary for interoperability with existing systems.
+
+OPENSSL_EXPORT const EVP_MD *EVP_sha3_256(void);
+OPENSSL_EXPORT const EVP_MD *EVP_sha3_512(void);
+
 // EVP_md5_sha1 is a TLS-specific `EVP_MD` which computes the concatenation of
 // MD5 and SHA-1, as used in TLS 1.1 and below.
 OPENSSL_EXPORT const EVP_MD *EVP_md5_sha1(void);
@@ -127,7 +136,7 @@ OPENSSL_EXPORT int EVP_DigestUpdate(EVP_MD_CTX *ctx, const void *data,
 
 // EVP_MAX_MD_BLOCK_SIZE is the largest digest block size supported, in
 // bytes.
-#define EVP_MAX_MD_BLOCK_SIZE 128  // SHA-512 is the longest so far.
+#define EVP_MAX_MD_BLOCK_SIZE 136  // SHA3-256 is the longest so far.
 
 // EVP_DigestFinal_ex finishes the digest in `ctx` and writes the output to
 // `md_out`. `EVP_MD_CTX_size` bytes are written, which is at most
@@ -344,9 +353,9 @@ OPENSSL_EXPORT int EVP_Q_digest(OSSL_LIB_CTX *libctx, const char *name,
 struct evp_md_pctx_ops;
 
 // EVP_MAX_MD_DATA_SIZE is a private constant which specifies the size of the
-// largest digest state. SHA-512 and BLAKE2b are joint-largest. Consuming code
-// only uses this via the `EVP_MD_CTX` type.
-#define EVP_MAX_MD_DATA_SIZE 208
+// largest digest state. SHA3-256 is the largest. Consuming code only uses this
+// via the `EVP_MD_CTX` type.
+#define EVP_MAX_MD_DATA_SIZE 240
 
 // env_md_ctx_st is typoed ("evp" -> "env"), but the typo comes from OpenSSL
 // and some consumers forward-declare these structures so we're leaving it

include/openssl/prefix_symbols.h

@@ -1381,6 +1381,8 @@
 #pragma redefine_extname EVP_sha224 BORINGSSL_ADD_USER_LABEL_AND_PREFIX(EVP_sha224)
 #pragma redefine_extname EVP_sha256 BORINGSSL_ADD_USER_LABEL_AND_PREFIX(EVP_sha256)
 #pragma redefine_extname EVP_sha384 BORINGSSL_ADD_USER_LABEL_AND_PREFIX(EVP_sha384)
+#pragma redefine_extname EVP_sha3_256 BORINGSSL_ADD_USER_LABEL_AND_PREFIX(EVP_sha3_256)
+#pragma redefine_extname EVP_sha3_512 BORINGSSL_ADD_USER_LABEL_AND_PREFIX(EVP_sha3_512)
 #pragma redefine_extname EVP_sha512 BORINGSSL_ADD_USER_LABEL_AND_PREFIX(EVP_sha512)
 #pragma redefine_extname EVP_sha512_256 BORINGSSL_ADD_USER_LABEL_AND_PREFIX(EVP_sha512_256)
 #pragma redefine_extname EXTENDED_KEY_USAGE_free BORINGSSL_ADD_USER_LABEL_AND_PREFIX(EXTENDED_KEY_USAGE_free)
@@ -4548,6 +4550,8 @@
 #define EVP_sha224 BORINGSSL_ADD_PREFIX(EVP_sha224)
 #define EVP_sha256 BORINGSSL_ADD_PREFIX(EVP_sha256)
 #define EVP_sha384 BORINGSSL_ADD_PREFIX(EVP_sha384)
+#define EVP_sha3_256 BORINGSSL_ADD_PREFIX(EVP_sha3_256)
+#define EVP_sha3_512 BORINGSSL_ADD_PREFIX(EVP_sha3_512)
 #define EVP_sha512 BORINGSSL_ADD_PREFIX(EVP_sha512)
 #define EVP_sha512_256 BORINGSSL_ADD_PREFIX(EVP_sha512_256)
 #define EXTENDED_KEY_USAGE_free BORINGSSL_ADD_PREFIX(EXTENDED_KEY_USAGE_free)