sumhash/
lib.rs

1#![warn(missing_docs)]
2//! This repository contains a Rust implementation of subset-sum hash function designed by the Algorand project.
3//!
4//! The reference implementation is written in Go and can be found in the [`go-sumhash`] repository.
5//! You can also refer to the [`spec`] to see a formal description of the hash function.
6//!
7//! This implementation isn't a literal port of the Go repository since the official implementation wouldn't lead to idiomatic Rust. In this library, we implement a Sumhash512Core core that can be wrapped with CoreWrapper. If you're interested in an earlier version which was a direct port of the reference implementation, see the `legacyport` branch.
8//!
9//! To have confidence that the implementation is correct, all tests from [`go-sumhash`] where included in the repo.
10//! The tests rely on randomness generated with Shake256 using particular seeds that were honored such that we can
11//! expect each inputo to have an exact output result with the official implementation.
12//!
13//! This library has a `AlgorandSumhash512Core` type alias which facilitates a default configuration for Sumhash512Core that utilizes the official seed for the Algorand blockchain state proofs.
14//!
15//! This library **isn't** audited or ready for production use, nor is it an official implementation.
16//!
17//! [`go-sumhash`]: https://github.com/algorand/go-sumhash
18//! [`spec`]: https://github.com/algorand/go-sumhash/blob/master/spec/sumhash-spec.pdf
19//!
20//! # Examples
21//!
22//! Using the Algorand instance configuration:
23//! ```
24//! use sumhash::sumhash512core::AlgorandSumhash512Core;
25//! use digest::{core_api::CoreWrapper, FixedOutput, Update};
26//!
27//! let mut h = CoreWrapper::<AlgorandSumhash512Core>::default();
28//! h.update("hello world".as_bytes());
29//! let output = h.finalize_fixed();
30//! println!("Result: {}", hex::encode(&output));
31//! ```
32//!
33//! Generic flavor providing your own seed.
34//! ```
35//! use sumhash::sumhash512core::Sumhash512Core;
36//! use digest::{core_api::CoreWrapper, FixedOutput, Update};
37//!
38//! let mut salt = [0; 64];
39//! salt[0] = 0x13;
40//! salt[1] = 0x37;
41//! let mut h = CoreWrapper::from_core(Sumhash512Core::new_with_salt(salt));
42//! h.update("hello world".as_bytes());
43//! let output = h.finalize_fixed();
44//! println!("Result: {}", hex::encode(&output));
45//! ```
46//!
47/// compress represents the compression function which is performed on a message.
48pub mod compress;
49/// sumhash512core is a sumhash core implementation for 512 bit output.
50pub mod sumhash512core;