feat: add keccak guest lib (#1070)

lightsing · web-flow · commit db3c67498500 · 2025-09-26T02:30:27.000Z
diff --git a/Cargo.lock b/Cargo.lock
diff --git a/Cargo.toml b/Cargo.toml
@@ -7,6 +7,7 @@ members = [
   "ceno_zkvm",
   "examples-builder",
   "examples",
+  "guest_libs/*",
 ]
 resolver = "2"
 
@@ -30,6 +31,7 @@ transcript = { git = "https://github.com/scroll-tech/gkr-backend.git", package =
 whir = { git = "https://github.com/scroll-tech/gkr-backend.git", package = "whir", rev = "v1.0.0-alpha.6" }
 witness = { git = "https://github.com/scroll-tech/gkr-backend.git", package = "witness", rev = "v1.0.0-alpha.6" }
 
+alloy-primitives = "1.3"
 anyhow = { version = "1.0", default-features = false }
 bincode = "1"
 clap = { version = "4.5", features = ["derive"] }
diff --git a/ceno_host/tests/test_elf.rs b/ceno_host/tests/test_elf.rs
@@ -622,6 +622,24 @@ fn test_keccak_no_syscall() -> Result<()> {
     Ok(())
 }
 
+#[test]
+fn test_keccak_guest() -> Result<()> {
+    let _ = ceno_host::run(
+        CENO_PLATFORM,
+        ceno_examples::keccak_lib,
+        &CenoStdin::default(),
+        None,
+    );
+
+    let _ = ceno_host::run(
+        CENO_PLATFORM,
+        ceno_examples::keccak_native,
+        &CenoStdin::default(),
+        None,
+    );
+    Ok(())
+}
+
 fn unsafe_platform() -> Platform {
     let mut platform = CENO_PLATFORM;
     platform.unsafe_ecall_nop = true;
diff --git a/ceno_rt/src/syscalls.rs b/ceno_rt/src/syscalls.rs
@@ -13,6 +13,8 @@ pub const BN254_FP_MUL: u32 = 0x00_01_01_28;
 pub const BN254_FP2_ADD: u32 = 0x00_01_01_29;
 pub const BN254_FP2_MUL: u32 = 0x00_01_01_2B;
 
+pub const KECCAK_STATE_WORDS: usize = 25;
+
 /// Based on https://github.com/succinctlabs/sp1/blob/013c24ea2fa15a0e7ed94f7d11a7ada4baa39ab9/crates/zkvm/entrypoint/src/syscalls/keccak_permute.rs
 /// Executes the Keccak256 permutation on the given state.
 ///
@@ -21,7 +23,7 @@ pub const BN254_FP2_MUL: u32 = 0x00_01_01_2B;
 /// - The caller must ensure that `state` is valid pointer to data that is aligned along a four
 ///   byte boundary.
 #[allow(unused_variables)]
-pub fn syscall_keccak_permute(state: &mut [u64; 25]) {
+pub fn syscall_keccak_permute(state: &mut [u64; KECCAK_STATE_WORDS]) {
     #[cfg(target_os = "zkvm")]
     unsafe {
         asm!(
diff --git a/examples/Cargo.toml b/examples/Cargo.toml
@@ -10,6 +10,8 @@ repository = "https://github.com/scroll-tech/ceno"
 version = "0.1.0"
 
 [dependencies]
+alloy-primitives = { version = "1.3", features = ["native-keccak"] }
+ceno_keccak = { path = "../guest_libs/keccak" }
 ceno_rt = { path = "../ceno_rt" }
 rand.workspace = true
 tiny-keccak.workspace = true
diff --git a/examples/examples/keccak_lib.rs b/examples/examples/keccak_lib.rs
@@ -0,0 +1,30 @@
+//! Compute the Keccak-256.
+
+extern crate ceno_rt;
+
+use ceno_keccak::{Hasher, Keccak};
+
+fn main() {
+    let keccak = Keccak::v256();
+    let mut output = [0; 32];
+    let expected = b"\
+        \xc5\xd2\x46\x01\x86\xf7\x23\x3c\x92\x7e\x7d\xb2\xdc\xc7\x03\xc0\
+        \xe5\x00\xb6\x53\xca\x82\x27\x3b\x7b\xfa\xd8\x04\x5d\x85\xa4\x70\
+    ";
+
+    keccak.finalize(&mut output);
+    assert_eq!(expected, &output);
+
+    let mut keccak = Keccak::v256();
+    let mut in_and_out: [u8; 32] = [0; 32];
+    for i in 1..6 {
+        in_and_out[i as usize - 1] = i
+    }
+    let expected = b"\
+        \x7d\x87\xc5\xea\x75\xf7\x37\x8b\xb7\x01\xe4\x04\xc5\x06\x39\x16\
+        \x1a\xf3\xef\xf6\x62\x93\xe9\xf3\x75\xb5\xf1\x7e\xb5\x04\x76\xf4\
+    ";
+    keccak.update(&in_and_out[0..5]);
+    keccak.finalize(&mut in_and_out);
+    assert_eq!(expected, &in_and_out);
+}
diff --git a/examples/examples/keccak_native.rs b/examples/examples/keccak_native.rs
@@ -0,0 +1,26 @@
+//! Compute the Keccak-256 using alloy-primitives with native-keccak hook.
+
+extern crate ceno_keccak;
+extern crate ceno_rt; // Make sure the native keccak hook is linked in.
+
+use alloy_primitives::keccak256;
+
+fn main() {
+    let output = keccak256(b"");
+    let expected = b"\
+        \xc5\xd2\x46\x01\x86\xf7\x23\x3c\x92\x7e\x7d\xb2\xdc\xc7\x03\xc0\
+        \xe5\x00\xb6\x53\xca\x82\x27\x3b\x7b\xfa\xd8\x04\x5d\x85\xa4\x70\
+    ";
+    assert_eq!(expected, &output);
+
+    let mut input: [u8; 5] = [0; 5];
+    for i in 1..6 {
+        input[i as usize - 1] = i;
+    }
+    let output = keccak256(input);
+    let expected = b"\
+        \x7d\x87\xc5\xea\x75\xf7\x37\x8b\xb7\x01\xe4\x04\xc5\x06\x39\x16\
+        \x1a\xf3\xef\xf6\x62\x93\xe9\xf3\x75\xb5\xf1\x7e\xb5\x04\x76\xf4\
+    ";
+    assert_eq!(expected, &output);
+}
diff --git a/guest_libs/keccak/Cargo.toml b/guest_libs/keccak/Cargo.toml
@@ -0,0 +1,14 @@
+[package]
+categories = ["cryptography", "zk", "blockchain", "ceno"]
+description = "Ceno zkVM Keccak Guest Library"
+edition = "2021"
+keywords = ["cryptography", "zk", "blockchain", "ceno"]
+license = "MIT OR Apache-2.0"
+name = "ceno_keccak"
+readme = "README.md"
+repository = "https://github.com/scroll-tech/ceno"
+version = "0.1.0"
+
+[dependencies]
+ceno_rt = { path = "../../ceno_rt" }
+tiny-keccak = { workspace = true }
diff --git a/guest_libs/keccak/README.md b/guest_libs/keccak/README.md
@@ -0,0 +1,4 @@
+# Ceno Keccak zkVM Guest Library
+
+Copied and modified from [tiny-keccak](https://github.com/debris/tiny-keccak)
+under CC0 license.
diff --git a/guest_libs/keccak/src/lib.rs b/guest_libs/keccak/src/lib.rs
@@ -0,0 +1,54 @@
+//! Ceno Keccak zkVM Guest Library
+
+#![no_std]
+#![deny(missing_docs)]
+extern crate alloc;
+
+/// Re-export the `tiny_keccak` crate's `Hasher` trait.
+pub use tiny_keccak::{self, Hasher};
+
+mod vendor;
+pub use vendor::keccak::Keccak;
+
+pub use ceno_rt::syscalls::syscall_keccak_permute as keccakf;
+
+mod keccakf {
+    use crate::{
+        keccakf,
+        vendor::{Buffer, Permutation},
+    };
+
+    pub struct KeccakF;
+
+    impl Permutation for KeccakF {
+        fn execute(buffer: &mut Buffer) {
+            keccakf(buffer.words());
+        }
+    }
+}
+
+/// Native hook for keccak256 for use with `alloy-primitives` "native-keccak" feature.
+///
+/// # Safety
+///
+/// The VM accepts the preimage by pointer and length, and writes the
+/// 32-byte hash.
+/// - `bytes` must point to an input buffer at least `len` long.
+/// - `output` must point to a buffer that is at least 32-bytes long.
+///
+/// [`keccak256`]: https://en.wikipedia.org/wiki/SHA-3
+/// [`sha3`]: https://docs.rs/sha3/latest/sha3/
+/// [`tiny_keccak`]: https://docs.rs/tiny-keccak/latest/tiny_keccak/
+#[inline(always)]
+#[no_mangle]
+pub unsafe extern "C" fn native_keccak256(bytes: *const u8, len: usize, output: *mut u8) {
+    use crate::{Hasher, Keccak};
+
+    unsafe {
+        let input = core::slice::from_raw_parts(bytes, len);
+        let out = core::slice::from_raw_parts_mut(output, 32);
+        let mut hasher = Keccak::v256();
+        hasher.update(input);
+        hasher.finalize(out);
+    }
+}
diff --git a/guest_libs/keccak/src/vendor.rs b/guest_libs/keccak/src/vendor.rs
@@ -0,0 +1,163 @@
+//! Private types and traits copied from the `tiny-keccak`.
+
+use ceno_rt::syscalls::KECCAK_STATE_WORDS;
+
+pub mod keccak;
+
+#[derive(Default, Clone)]
+pub struct Buffer([u64; KECCAK_STATE_WORDS]);
+
+impl Buffer {
+    pub fn words(&mut self) -> &mut [u64; KECCAK_STATE_WORDS] {
+        &mut self.0
+    }
+
+    #[inline]
+    pub fn execute<F: FnOnce(&mut [u8])>(&mut self, offset: usize, len: usize, f: F) {
+        // # Safety: little-endian target
+        let buffer: &mut [u8; KECCAK_STATE_WORDS * 8] =
+            unsafe { core::mem::transmute(&mut self.0) };
+        f(&mut buffer[offset..][..len]);
+    }
+
+    pub fn setout(&mut self, dst: &mut [u8], offset: usize, len: usize) {
+        self.execute(offset, len, |buffer| dst[..len].copy_from_slice(buffer));
+    }
+
+    pub fn xorin(&mut self, src: &[u8], offset: usize, len: usize) {
+        self.execute(offset, len, |dst| {
+            assert!(dst.len() <= src.len());
+            let len = dst.len();
+            let mut dst_ptr = dst.as_mut_ptr();
+            let mut src_ptr = src.as_ptr();
+            for _ in 0..len {
+                unsafe {
+                    *dst_ptr ^= *src_ptr;
+                    src_ptr = src_ptr.offset(1);
+                    dst_ptr = dst_ptr.offset(1);
+                }
+            }
+        });
+    }
+
+    pub fn pad(&mut self, offset: usize, delim: u8, rate: usize) {
+        self.execute(offset, 1, |buff| buff[0] ^= delim);
+        self.execute(rate - 1, 1, |buff| buff[0] ^= 0x80);
+    }
+}
+
+pub trait Permutation {
+    fn execute(a: &mut Buffer);
+}
+
+#[derive(Clone, Copy)]
+pub enum Mode {
+    Absorbing,
+    Squeezing,
+}
+
+pub struct KeccakState<P> {
+    buffer: Buffer,
+    offset: usize,
+    rate: usize,
+    delim: u8,
+    mode: Mode,
+    permutation: core::marker::PhantomData<P>,
+}
+
+impl<P> Clone for KeccakState<P> {
+    fn clone(&self) -> Self {
+        KeccakState {
+            buffer: self.buffer.clone(),
+            offset: self.offset,
+            rate: self.rate,
+            delim: self.delim,
+            mode: self.mode,
+            permutation: core::marker::PhantomData,
+        }
+    }
+}
+
+impl<P: Permutation> KeccakState<P> {
+    fn new(rate: usize, delim: u8) -> Self {
+        assert!(rate != 0, "rate cannot be equal 0");
+        KeccakState {
+            buffer: Buffer::default(),
+            offset: 0,
+            rate,
+            delim,
+            mode: Mode::Absorbing,
+            permutation: core::marker::PhantomData,
+        }
+    }
+
+    fn keccak(&mut self) {
+        P::execute(&mut self.buffer);
+    }
+
+    fn update(&mut self, input: &[u8]) {
+        if let Mode::Squeezing = self.mode {
+            self.mode = Mode::Absorbing;
+            self.fill_block();
+        }
+
+        // first foldp
+        let mut ip = 0;
+        let mut l = input.len();
+        let mut rate = self.rate - self.offset;
+        let mut offset = self.offset;
+        while l >= rate {
+            self.buffer.xorin(&input[ip..], offset, rate);
+            self.keccak();
+            ip += rate;
+            l -= rate;
+            rate = self.rate;
+            offset = 0;
+        }
+
+        self.buffer.xorin(&input[ip..], offset, l);
+        self.offset = offset + l;
+    }
+
+    fn pad(&mut self) {
+        self.buffer.pad(self.offset, self.delim, self.rate);
+    }
+
+    fn squeeze(&mut self, output: &mut [u8]) {
+        if let Mode::Absorbing = self.mode {
+            self.mode = Mode::Squeezing;
+            self.pad();
+            self.fill_block();
+        }
+
+        // second foldp
+        let mut op = 0;
+        let mut l = output.len();
+        let mut rate = self.rate - self.offset;
+        let mut offset = self.offset;
+        while l >= rate {
+            self.buffer.setout(&mut output[op..], offset, rate);
+            self.keccak();
+            op += rate;
+            l -= rate;
+            rate = self.rate;
+            offset = 0;
+        }
+
+        self.buffer.setout(&mut output[op..], offset, l);
+        self.offset = offset + l;
+    }
+
+    fn finalize(mut self, output: &mut [u8]) {
+        self.squeeze(output);
+    }
+
+    fn fill_block(&mut self) {
+        self.keccak();
+        self.offset = 0;
+    }
+}
+
+pub const fn bits_to_rate(bits: usize) -> usize {
+    200 - bits / 4
+}
diff --git a/guest_libs/keccak/src/vendor/keccak.rs b/guest_libs/keccak/src/vendor/keccak.rs
