binius_circuits/sha3/
mod.rs

1// Copyright 2026 The Binius Developers
2
3//! FIPS 202 SHA-3 hash functions: SHA3-256, SHA3-384, and SHA3-512.
4//!
5//! SHA-3 is built from the same 1600-bit Keccak permutation and multi-rate padding rule as the
6//! Ethereum-style Keccak hash already in this crate.
7//!
8//! The only difference is a two-bit domain-separation suffix that FIPS 202 appends to the message
9//! before padding.
10//!
11//! For a byte-aligned message this changes the first padding byte from `0x01` to `0x06`.
12//!
13//! SHA3-224 is intentionally not provided.
14//!
15//! Its 224-bit digest does not divide evenly into 64-bit words.
16//!
17//! This crate represents every digest as a whole number of 64-bit words.
18//!
19//! Each hash function fixes its own rate and capacity.
20//!
21//! The capacity is twice the digest length.
22//!
23//! The rate is whatever remains of the 1600-bit permutation width.
24//!
25//! The digest never exceeds the rate for any of these three hash functions.
26//!
27//! That means the digest is always read directly out of the state after the last block's
28//! permutation, with no extra squeezing permutation ever needed.
29//!
30//! | Function  | Rate (bytes) | Capacity (bits) | Digest (words) |
31//! |-----------|--------------|------------------|-----------------|
32//! | SHA3-256  | 136          | 512              | 4               |
33//! | SHA3-384  | 104          | 768              | 6               |
34//! | SHA3-512  | 72           | 1024             | 8               |
35
36pub mod fixed_length;
37pub mod varlen;
38
39/// The two-bit domain-separation suffix FIPS 202 appends to the message before padding.
40///
41/// For a byte-aligned message this folds into the first padding byte as `0x06`.
42///
43/// The original Keccak padding would place `0x01` in that same position instead.
44const SHA3_DELIMITER_BYTE: u64 = 0x06;
45
46/// Rate of SHA3-256, in bytes.
47///
48/// The 1600-bit permutation width minus twice the digest length, converted to bytes.
49pub const SHA3_256_RATE_BYTES: usize = 136;
50
51/// Rate of SHA3-384, in bytes.
52///
53/// The 1600-bit permutation width minus twice the digest length, converted to bytes.
54pub const SHA3_384_RATE_BYTES: usize = 104;
55
56/// Rate of SHA3-512, in bytes.
57///
58/// The 1600-bit permutation width minus twice the digest length, converted to bytes.
59pub const SHA3_512_RATE_BYTES: usize = 72;
60
61/// SHA3-256 digest length, in 64-bit words.
62pub const SHA3_256_DIGEST_WORDS: usize = 4;
63
64/// SHA3-384 digest length, in 64-bit words.
65pub const SHA3_384_DIGEST_WORDS: usize = 6;
66
67/// SHA3-512 digest length, in 64-bit words.
68pub const SHA3_512_DIGEST_WORDS: usize = 8;
binius_circuits/sha3/mod.rs

binius_circuits/sha3/
mod.rs
