hashx/
lib.rs

Help
1#![cfg_attr(docsrs, feature(doc_auto_cfg, doc_cfg))]
2#![doc = include_str!("../README.md")]
3// @@ begin lint list maintained by maint/add_warning @@
4#![allow(renamed_and_removed_lints)] // @@REMOVE_WHEN(ci_arti_stable)
5#![allow(unknown_lints)] // @@REMOVE_WHEN(ci_arti_nightly)
6#![warn(missing_docs)]
7#![warn(noop_method_call)]
8#![warn(unreachable_pub)]
9#![warn(clippy::all)]
10#![deny(clippy::await_holding_lock)]
11#![deny(clippy::cargo_common_metadata)]
12#![deny(clippy::cast_lossless)]
13#![deny(clippy::checked_conversions)]
14#![warn(clippy::cognitive_complexity)]
15#![deny(clippy::debug_assert_with_mut_call)]
16#![deny(clippy::exhaustive_enums)]
17#![deny(clippy::exhaustive_structs)]
18#![deny(clippy::expl_impl_clone_on_copy)]
19#![deny(clippy::fallible_impl_from)]
20#![deny(clippy::implicit_clone)]
21#![deny(clippy::large_stack_arrays)]
22#![warn(clippy::manual_ok_or)]
23#![deny(clippy::missing_docs_in_private_items)]
24#![warn(clippy::needless_borrow)]
25#![warn(clippy::needless_pass_by_value)]
26#![warn(clippy::option_option)]
27#![deny(clippy::print_stderr)]
28#![deny(clippy::print_stdout)]
29#![warn(clippy::rc_buffer)]
30#![deny(clippy::ref_option_ref)]
31#![warn(clippy::semicolon_if_nothing_returned)]
32#![warn(clippy::trait_duplication_in_bounds)]
33#![deny(clippy::unchecked_duration_subtraction)]
34#![deny(clippy::unnecessary_wraps)]
35#![warn(clippy::unseparated_literal_suffix)]
36#![deny(clippy::unwrap_used)]
37#![deny(clippy::mod_module_files)]
38#![allow(clippy::let_unit_value)] // This can reasonably be done for explicitness
39#![allow(clippy::uninlined_format_args)]
40#![allow(clippy::significant_drop_in_scrutinee)] // arti/-/merge_requests/588/#note_2812945
41#![allow(clippy::result_large_err)] // temporary workaround for arti#587
42#![allow(clippy::needless_raw_string_hashes)] // complained-about code is fine, often best
43#![allow(clippy::needless_lifetimes)] // See arti#1765
44//! <!-- @@ end lint list maintained by maint/add_warning @@ -->
45
46mod compiler;
47mod constraints;
48mod err;
49mod generator;
50mod program;
51mod rand;
52mod register;
53mod scheduler;
54mod siphash;
55
56use crate::compiler::{Architecture, Executable};
57use crate::program::Program;
58use rand_core::RngCore;
59
60pub use crate::err::{CompilerError, Error};
61pub use crate::rand::SipRand;
62pub use crate::siphash::SipState;
63
64/// Option for selecting a HashX runtime
65#[derive(Default, Debug, Copy, Clone, Eq, PartialEq)]
66#[non_exhaustive]
67pub enum RuntimeOption {
68    /// Choose the interpreted runtime, without trying the compiler at all.
69    InterpretOnly,
70    /// Choose the compiled runtime only, and fail if it experiences any errors.
71    CompileOnly,
72    /// Always try the compiler first but fall back to the interpreter on error.
73    /// (This is the default)
74    #[default]
75    TryCompile,
76}
77
78/// Effective HashX runtime for a constructed program
79#[derive(Debug, Copy, Clone, Eq, PartialEq)]
80#[non_exhaustive]
81pub enum Runtime {
82    /// The interpreted runtime is active.
83    Interpret,
84    /// The compiled runtime is active.
85    Compiled,
86}
87
88/// Pre-built hash program that can be rapidly computed with different inputs
89///
90/// The program and initial state representation are not specified in this
91/// public interface, but [`std::fmt::Debug`] can describe program internals.
92#[derive(Debug)]
93pub struct HashX {
94    /// Keys used to generate an initial register state from the hash input
95    ///
96    /// Half of the key material generated from seed bytes go into the random
97    /// program generator, and the other half are saved here for use in each
98    /// hash invocation.
99    register_key: SipState,
100
101    /// A prepared randomly generated hash program
102    ///
103    /// In compiled runtimes this will be executable code, and in the
104    /// interpreter it's a list of instructions. There is no stable API for
105    /// program information, but the Debug trait will list programs in either
106    /// format.
107    program: RuntimeProgram,
108}
109
110/// Combination of [`Runtime`] and the actual program info used by that runtime
111///
112/// All variants of [`RuntimeProgram`] use some kind of inner heap allocation
113/// to store the program data.
114#[derive(Debug)]
115enum RuntimeProgram {
116    /// Select the interpreted runtime, and hold a Program for it to run.
117    Interpret(Program),
118    /// Select the compiled runtime, and hold an executable code page.
119    Compiled(Executable),
120}
121
122impl HashX {
123    /// The maximum available output size for [`Self::hash_to_bytes()`]
124    pub const FULL_SIZE: usize = 32;
125
126    /// Generate a new hash function with the supplied seed.
127    pub fn new(seed: &[u8]) -> Result<Self, Error> {
128        HashXBuilder::new().build(seed)
129    }
130
131    /// Check which actual program runtime is in effect.
132    ///
133    /// By default we try to generate code at runtime to accelerate the hash
134    /// function, but we fall back to an interpreter if this fails. The compiler
135    /// can be disabled entirely using [`RuntimeOption::InterpretOnly`] and
136    /// [`HashXBuilder`].
137    pub fn runtime(&self) -> Runtime {
138        match &self.program {
139            RuntimeProgram::Interpret(_) => Runtime::Interpret,
140            RuntimeProgram::Compiled(_) => Runtime::Compiled,
141        }
142    }
143
144    /// Calculate the first 64-bit word of the hash, without converting to bytes.
145    pub fn hash_to_u64(&self, input: u64) -> u64 {
146        self.hash_to_regs(input).digest(self.register_key)[0]
147    }
148
149    /// Calculate the hash function at its full output width, returning a fixed
150    /// size byte array.
151    pub fn hash_to_bytes(&self, input: u64) -> [u8; Self::FULL_SIZE] {
152        let words = self.hash_to_regs(input).digest(self.register_key);
153        let mut bytes = [0_u8; Self::FULL_SIZE];
154        for word in 0..words.len() {
155            bytes[word * 8..(word + 1) * 8].copy_from_slice(&words[word].to_le_bytes());
156        }
157        bytes
158    }
159
160    /// Common setup for hashes with any output format
161    #[inline(always)]
162    fn hash_to_regs(&self, input: u64) -> register::RegisterFile {
163        let mut regs = register::RegisterFile::new(self.register_key, input);
164        match &self.program {
165            RuntimeProgram::Interpret(program) => program.interpret(&mut regs),
166            RuntimeProgram::Compiled(executable) => executable.invoke(&mut regs),
167        }
168        regs
169    }
170}
171
172/// Builder for creating [`HashX`] instances with custom settings
173#[derive(Default, Debug, Clone, Eq, PartialEq)]
174pub struct HashXBuilder {
175    /// Current runtime() setting for this builder
176    runtime: RuntimeOption,
177}
178
179impl HashXBuilder {
180    /// Create a new [`HashXBuilder`] with default settings.
181    ///
182    /// Immediately calling [`Self::build()`] would be equivalent to using
183    /// [`HashX::new()`].
184    pub fn new() -> Self {
185        Default::default()
186    }
187
188    /// Select a new [`RuntimeOption`].
189    pub fn runtime(&mut self, runtime: RuntimeOption) -> &mut Self {
190        self.runtime = runtime;
191        self
192    }
193
194    /// Build a [`HashX`] instance with a seed and the selected options.
195    pub fn build(&self, seed: &[u8]) -> Result<HashX, Error> {
196        let (key0, key1) = SipState::pair_from_seed(seed);
197        let mut rng = SipRand::new(key0);
198        self.build_from_rng(&mut rng, key1)
199    }
200
201    /// Build a [`HashX`] instance from an arbitrary [`RngCore`] and
202    /// a [`SipState`] key used for initializing the register file.
203    pub fn build_from_rng<R: RngCore>(
204        &self,
205        rng: &mut R,
206        register_key: SipState,
207    ) -> Result<HashX, Error> {
208        let program = Program::generate(rng)?;
209        self.build_from_program(program, register_key)
210    }
211
212    /// Build a [`HashX`] instance from an already-generated [`Program`] and
213    /// [`SipState`] key.
214    ///
215    /// The program is either stored as-is or compiled, depending on the current
216    /// [`RuntimeOption`]. Requires a program as well as a [`SipState`] to be
217    /// used for initializing the register file.
218    fn build_from_program(&self, program: Program, register_key: SipState) -> Result<HashX, Error> {
219        Ok(HashX {
220            register_key,
221            program: match self.runtime {
222                RuntimeOption::InterpretOnly => RuntimeProgram::Interpret(program),
223                RuntimeOption::CompileOnly => {
224                    RuntimeProgram::Compiled(Architecture::compile((&program).into())?)
225                }
226                RuntimeOption::TryCompile => match Architecture::compile((&program).into()) {
227                    Ok(exec) => RuntimeProgram::Compiled(exec),
228                    Err(_) => RuntimeProgram::Interpret(program),
229                },
230            },
231        })
232    }
233}
hashx/lib.rs

hashx/
lib.rs
