risc0_zkvm/
sha.rs

1// Copyright 2024 RISC Zero, Inc.
2//
3// Licensed under the Apache License, Version 2.0 (the "License");
4// you may not use this file except in compliance with the License.
5// You may obtain a copy of the License at
6//
7//     http://www.apache.org/licenses/LICENSE-2.0
8//
9// Unless required by applicable law or agreed to in writing, software
10// distributed under the License is distributed on an "AS IS" BASIS,
11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12// See the License for the specific language governing permissions and
13// limitations under the License.
14
15//! SHA-256 hashing services
16//!
17//! Support for SHA-256 hashing compatible with the on-circuit SHA acceleration
18//! available in the guest. This module can be used from both the host and the
19//! guest -- it will detect the build environment and select the appropriate
20//! implementation.
21//!
22//! # Usage
23//!
24//! We provide two interfaces for SHA hashing. The first interface is based on
25//! [Rust Crypto](https://github.com/RustCrypto) wrappers and can be found in
26//! the [rust_crypto] module, along with documentation and usage notes.
27//!
28//! The other interface is to directly use an implementation of the [Sha256]
29//! trait defined in this module:
30//! ```rust
31//! use risc0_zkvm::sha::{Impl, Sha256};
32//!
33//! // Hash a u8 array
34//! let data = [1_u8, 2, 5, 14];
35//! let hash = Impl::hash_bytes(&data);
36//!
37//! // Hash a String
38//! let abc = String::from("abc");
39//! let abc_hash = Impl::hash_bytes(&abc.as_bytes());
40//!
41//! // Hash a Digest
42//! let hash_hash = Impl::hash_bytes(&hash.as_bytes());
43//! // Hashing can also be done with 32-bit words (matching the zkVM word size)
44//! let hash_hash_words = Impl::hash_words(&hash.as_words());
45//! // Hashing with bytes or words should not change the result
46//! assert_eq!(hash_hash, hash_hash_words);
47//! ```
48
49pub use risc0_zkp::core::{
50    digest::{Digest, DIGEST_BYTES, DIGEST_SHORTS, DIGEST_WORDS},
51    hash::sha::{Block, Sha256, BLOCK_BYTES, BLOCK_WORDS, SHA256_INIT, WORD_SIZE},
52};
53
54// This Impl selects the appropriate implementation of SHA-256 depending on whether we are
55// in the zkVM guest. Users can simply `use risc0_zkvm::sha::Impl`.
56pub use risc0_zkp::core::hash::sha::Impl;
57
58/// Defines a collision resistant hash for the typed and structured data.
59pub trait Digestible {
60    /// Calculate a collision resistant hash for the typed and structured data.
61    fn digest(&self) -> Digest;
62}
63
64impl<D: ?Sized + risc0_binfmt::Digestible> Digestible for D {
65    /// Calculate a collision resistant hash for the typed and structured data.
66    fn digest(&self) -> Digest {
67        self.digest::<Impl>()
68    }
69}
70
71pub mod rust_crypto {
72    //! [Rust Crypto] wrappers for the RISC0 Sha256 trait.
73    //!
74    //! [Rust Crypto]: https://github.com/RustCrypto
75    //!
76    //! # Usage
77    //!
78    //! ```rust
79    //! use risc0_zkvm::sha::rust_crypto::{Sha256, Digest as _};
80    //!
81    //! // create a Sha256 object
82    //! let mut hasher = Sha256::new();
83    //!
84    //! // write input message
85    //! hasher.update(b"hello world");
86    //!
87    //! // read hash digest and consume hasher
88    //! let result = hasher.finalize();
89    //!
90    //! assert_eq!(hex::encode(result), "b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9");
91    //!
92    //! // more concise version of the code above.
93    //! assert_eq!(hex::encode(Sha256::digest(b"hello world")),
94    //!     "b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9"
95    //! );
96    //! ```
97    // NOTE: When used on the host, these functions are strictly less efficient,
98    // with the primary loss being passing blocks received through the
99    // RustCrypto interface as [u8] into blocks compatible with the RISC0
100    // interface of [u32] which has stricter alignment and therefore may require
101    // a copy. When on the host, this gets pass _back_ to the RustCrypto [sha2]
102    // crate meaning that copy was wasted. This is the result of prioritizing code
103    // factoring and guest performance over host performance.
104
105    use risc0_zkp::core::hash::sha::rust_crypto;
106    pub use rust_crypto::{Digest, Output};
107
108    /// Sha256 is a [Rust Crypto] wrapper on the RISC Zero SHA-256
109    /// implementations. This type will automatically select the correct
110    /// implementation for usage in the zkVM guest and on the host.
111    pub type Sha256 = rust_crypto::Sha256<super::Impl>;
112}
risc0_zkvm/sha.rs

risc0_zkvm/
sha.rs
