permutation_xoodoo/lib.rs
1//! [Xoodoo] permutation in the [`crypto-permutation`] framework.
2//!
3//! `Xoodoo: Permutation`
4//!
5//! # Example
6//! __Note__: The following example makes use of very low-level cryptographic APIs, which you
7//! shouldn't use unless you know very well what you are doing. The intended use of this crate
8//! is just to pass the [`XoodooP`] permutation as a parameter to some generic more high-level
9//! construction like Farfalle as implemented in [`deck-farfalle`].
10//!
11//! Suppose we want to apply the full 12-round Xoodoo permutation to the message
12//! `"hello world"` (and then padded with null-bytes to make it 42 bytes in length),
13//! and then get the first 3 bytes of output.
14//! ```rust
15//! use permutation_xoodoo::{XoodooState, XoodooP};
16//! use crypto_permutation::{Reader, Writer, Permutation, PermutationState};
17//!
18//! // create a state and a permutation to act on it
19//! let mut state = XoodooState::default();
20//! let xoodoo = XoodooP::<12>::default();
21//!
22//! // write input to the state
23//! state.copy_writer().write_bytes(b"hello world");
24//!
25//! // apply the xoodoo permutation to the state
26//! xoodoo.apply(&mut state);
27//!
28//! // and finally you can read the first 3 bytes of output
29//! let mut out = [0u8; 3];
30//! state.reader().write_to_slice(&mut out);
31//! assert_eq!(out, [241, 234, 156]);
32//! ```
33//!
34//! [`crypto-permutation`]: https://crates.io/crates/crypto-permutation
35//! [`deck-farfalle`]: https://crates.io/crates/deck-farfalle
36//! [Xoodoo]: https://keccak.team/xoodoo.html
37
38#![no_std]
39#![allow(clippy::needless_lifetimes)]
40
41use crypto_permutation::{Permutation, PermutationState};
42
43mod permutation;
44use permutation::{xoodoo, MAX_ROUNDS};
45mod state;
46pub use state::XoodooState;
47
48/// Xoodoo permutation with `ROUNDS` rounds. `ROUNDS` must be at most 12.
49#[derive(Clone, Copy, Debug, Default)]
50pub struct XoodooP<const ROUNDS: usize>;
51
52impl<const ROUNDS: usize> XoodooP<ROUNDS> {
53 const _ROUNDS_CHECK: () = {
54 assert!(ROUNDS > 0);
55 assert!(ROUNDS <= MAX_ROUNDS);
56 };
57}
58
59impl<const ROUNDS: usize> Permutation for XoodooP<ROUNDS> {
60 type State = XoodooState;
61
62 fn apply(self, state: &mut Self::State) {
63 xoodoo::<ROUNDS>(state.get_state_mut());
64 }
65}
66
67#[cfg(test)]
68mod tests;