From 25651b3035a7b7933e6ed7d56ca44eab950b93eb Mon Sep 17 00:00:00 2001 From: Jonathan Wang <31040440+jonathanpwang@users.noreply.github.com> Date: Tue, 31 Dec 2024 14:35:32 -0500 Subject: [PATCH] book: add sha2 summary section --- book/src/SUMMARY.md | 1 + book/src/custom-extensions/algebra.md | 6 +++--- book/src/custom-extensions/bigint.md | 6 +++--- book/src/custom-extensions/ecc.md | 2 +- book/src/custom-extensions/keccak.md | 8 ++++---- book/src/custom-extensions/overview.md | 6 ++++-- book/src/custom-extensions/sha256.md | 16 ++++++++-------- 7 files changed, 24 insertions(+), 21 deletions(-) diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md index 0a0689e521..71d40b5535 100644 --- a/book/src/SUMMARY.md +++ b/book/src/SUMMARY.md @@ -20,6 +20,7 @@ - [Overview](./custom-extensions/overview.md) - [Keccak](./custom-extensions/keccak.md) +- [SHA-256](./custom-extensions/sha256.md) - [Big Integer](./custom-extensions/bigint.md) - [Algebra (Modular Arithmetic)](./custom-extensions/algebra.md) - [Elliptic Curve Cryptography](./custom-extensions/ecc.md) diff --git a/book/src/custom-extensions/algebra.md b/book/src/custom-extensions/algebra.md index 11eee7d389..d74b38b779 100644 --- a/book/src/custom-extensions/algebra.md +++ b/book/src/custom-extensions/algebra.md @@ -1,6 +1,6 @@ -# OpenVM Algebra +# Algebra (Modular Arithmetic) -The OpenVM Algebra extension provides tools to create and manipulate modular arithmetic structures and their complex extensions. For example, if \\(p\\) is prime, OpenVM Algebra can handle modular arithmetic in \\(\mathbb{F}_p\\)​ and its quadratic extension fields \\(\mathbb{F}_p[x]/(x^2 + 1)\\). +The OpenVM Algebra extension provides tools to create and manipulate modular arithmetic structures and their complex extensions. For example, if \\(p\\) is prime, OpenVM Algebra can handle modular arithmetic in \\(\mathbb{F}\_p\\)​ and its quadratic extension fields \\(\mathbb{F}\_p[x]/(x^2 + 1)\\). The functional part is provided by the `openvm-algebra-guest` crate, which is a guest library that can be used in any OpenVM program. The macros for creating corresponding structs are in the `openvm-algebra-moduli-setup` and `openvm-algebra-complex-macros` crates. @@ -53,7 +53,7 @@ This step enumerates the declared moduli (e.g., `0` for the first one, `1` for t ## Complex field extension -Complex extensions, such as \\(\mathbb{F}_p[x]/(x^2 + 1)\\), are defined similarly using `complex_declare!` and `complex_init!`: +Complex extensions, such as \\(\mathbb{F}\_p[x]/(x^2 + 1)\\), are defined similarly using `complex_declare!` and `complex_init!`: 1. **Declare**: diff --git a/book/src/custom-extensions/bigint.md b/book/src/custom-extensions/bigint.md index 96ee245b06..d1bdc2247c 100644 --- a/book/src/custom-extensions/bigint.md +++ b/book/src/custom-extensions/bigint.md @@ -1,10 +1,10 @@ -# OpenVM BigInt +# Big Integers The OpenVM BigInt extension (aka `Int256`) provides two structs: `U256` and `I256`. These structs can be used to perform 256 bit arithmetic operations. The functional part is provided by the `openvm-bigint-guest` crate, which is a guest library that can be used in any OpenVM program. ## `U256` -The `U256` struct is a 256-bit unsigned integer type. +The `U256` struct is a 256-bit unsigned integer type. ### Constants @@ -162,7 +162,7 @@ To be able to import the `I256` struct, add the following to your `Cargo.toml` f openvm-bigint-guest = { git = "https://github.com/openvm-org/openvm.git" } ``` -## External Functions +## External Linking The Bigint Guest extension provides another way to use the native implementation. It provides external functions that are meant to be linked to other external libraries. The external libraries can use these functions as a hook for the 256 bit integer native implementations. Enabled only when the `target_os = "zkvm"`. All of the functions are defined as `unsafe extern "C" fn`. Also, note that you must enable the feature `export-intrinsics` to make them globally linkable. diff --git a/book/src/custom-extensions/ecc.md b/book/src/custom-extensions/ecc.md index 13e0127b26..de2b2fbd9a 100644 --- a/book/src/custom-extensions/ecc.md +++ b/book/src/custom-extensions/ecc.md @@ -1,4 +1,4 @@ -# OpenVM ECC +# Elliptic Curve Cryptography The OpenVM Elliptic Curve Cryptography Extension provides support for elliptic curve operations through the `openvm-ecc-guest` crate. diff --git a/book/src/custom-extensions/keccak.md b/book/src/custom-extensions/keccak.md index 5d3b733eb7..111b81ae2a 100644 --- a/book/src/custom-extensions/keccak.md +++ b/book/src/custom-extensions/keccak.md @@ -1,6 +1,6 @@ -# OpenVM Keccak256 +# Keccak256 -The OpenVm Keccak256 extension provides tools for using the Keccak-256 hash function. +The OpenVM Keccak256 extension provides tools for using the Keccak-256 hash function. The functional part is provided by the `openvm-keccak-guest` crate, which is a guest library that can be used in any OpenVM program. ## Functions for guest code @@ -41,9 +41,9 @@ openvm-keccak256-guest = { git = "https://github.com/openvm-org/openvm.git" } hex = { version = "0.4.3", default-features = false, features = ["alloc"] } ``` -## Native Keccak256 +## External Linking -Keccak guest extension also provides another way to use the native Keccak-256 implementation. It provides a function that is meant to be linked to other external libraries. The external libraries can use this function as a hook for the Keccak-256 native implementation. Enabled only when the target is `zkvm`. +The keccak guest extension also provides another way to use the keccak-256 intrinsic implementation. It provides a function that is meant to be linked to other external libraries. The external libraries can use this function as a hook for the keccak-256 intrinsic. This is enabled only when the target is `zkvm`. - `native_keccak256(input: *const u8, len: usize, output: *mut u8)`: This function has `C` ABI. It takes in a pointer to the input, the length of the input, and a pointer to the output buffer. diff --git a/book/src/custom-extensions/overview.md b/book/src/custom-extensions/overview.md index 6f6a3f6052..5bfefb402d 100644 --- a/book/src/custom-extensions/overview.md +++ b/book/src/custom-extensions/overview.md @@ -5,12 +5,13 @@ You can seamlessly integrate certain performance-optimized extensions maintained In this chapter, we will explain how to use the following existing extensions: - [`openvm-keccak-guest`](./keccak.md) - Keccak256 hash function. +- [`openvm-sha256-guest`](./sha256.md) - SHA2-256 hash function. - [`openvm-bigint-guest`](./bigint.md) - Big integer arithmetic for 256-bit signed and unsigned integers. - [`openvm-algebra-guest`](./algebra.md) - Modular arithmetic and complex field extensions. - [`openvm-ecc-guest`](./ecc.md) - Elliptic curve cryptography. - [`openvm-pairing-guest`](./pairing.md) - Elliptic curve optimal Ate pairings. -Some extensions such as `openvm-keccak-guest` and `openvm-bigint-guest` can be enabled without specifying any additional configuration. +Some extensions such as `openvm-keccak-guest`, `openvm-sha256-guest`, and `openvm-bigint-guest` can be enabled without specifying any additional configuration. On the other hand certain arithmetic operations, particularly modular arithmetic, can be optimized significantly when the modulus is known at compile time. This approach requires a framework to inform the compiler about all the moduli and associated arithmetic structures we intend to use. To achieve this, three steps are involved: @@ -34,6 +35,7 @@ The template `openvm.toml` file is as follows: [app_vm_config.rv32m] [app_vm_config.io] [app_vm_config.keccak] +[app_vm_config.sha256] [app_vm_config.native] [app_vm_config.bigint] [app_vm_config.modular] @@ -55,4 +57,4 @@ b = "" ``` `rv32i`, `io`, and `rv32m` need to be always included if you make an `openvm.toml` file while the rest are optional and should be included if you want to use the corresponding extension. -All moduli and scalars must be provided in decimal format. Currently `pairing` supports only pre-defined `Bls12_381` and `Bn254` curves. To add more `ecc` curves you need to add more `[[app_vm_config.ecc.supported_curves]]` entries. +All moduli and scalars must be provided in decimal format. Currently `pairing` supports only pre-defined `Bls12_381` and `Bn254` curves. To add more `ecc` curves you need to add more `[[app_vm_config.ecc.supported_curves]]` entries. diff --git a/book/src/custom-extensions/sha256.md b/book/src/custom-extensions/sha256.md index d5478f5fb8..c2102da1b6 100644 --- a/book/src/custom-extensions/sha256.md +++ b/book/src/custom-extensions/sha256.md @@ -1,14 +1,14 @@ -# OpenVM Sha256 +# SHA-256 -The OpenVm Sha256 extension provides tools for using the Sha256 hash function. Refer [here][https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.180-4.pdf] for more details on the Sha256. +The OpenVM SHA-256 extension provides tools for using the SHA-256 hash function. Refer [here](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.180-4.pdf) for more details on SHA-256. The functional part is provided by the `openvm-sha256-guest` crate, which is a guest library that can be used in any OpenVM program. ## Functions for guest code -The OpenVM Sha256 Guest extension provides two functions for using in your guest code: +The OpenVM SHA-256Guest extension provides two functions for using in your guest code: -- `sha256(input: &[u8]) -> [u8; 32]`: Computes the Sha256 hash of the input data and returns it as an array of 32 bytes. -- `set_sha256(input: &[u8], output: &mut [u8; 32])`: Sets the output to the Sha256 hash of the input data into the provided output buffer. +- `sha256(input: &[u8]) -> [u8; 32]`: Computes the SHA-256 hash of the input data and returns it as an array of 32 bytes. +- `set_sha256(input: &[u8], output: &mut [u8; 32])`: Sets the output to the SHA-256 hash of the input data into the provided output buffer. See the full example [here](https://github.com/openvm-org/openvm/blob/main/examples/sha256). @@ -48,9 +48,9 @@ openvm-sha256-guest = { git = "https://github.com/openvm-org/openvm.git" } hex = { version = "0.4.3", default-features = false, features = ["alloc"] } ``` -## Native Sha256 +## External Linking -Keccak guest extension also provides another way to use the native Sha256 implementation. It provides a function that is meant to be linked to other external libraries. The external libraries can use this function as a hook for the Sha256 native implementation. Enabled only when the target is `zkvm`. +The SHA-256 guest extension also provides another way to use the intrinsic SHA-256 implementation. It provides a function that is meant to be linked to other external libraries. The external libraries can use this function as a hook for the SHA-256 intrinsic. This is enabled only when the target is `zkvm`. - `zkvm_sha256_impl(input: *const u8, len: usize, output: *mut u8)`: This function has `C` ABI. It takes in a pointer to the input, the length of the input, and a pointer to the output buffer. @@ -71,7 +71,7 @@ fn sha256(input: &[u8]) -> [u8; 32] { output } #[cfg(not(target_os = "zkvm"))] { - // Regular Sha256 implementation + // Regular SHA-256 implementation } } ```