deck_farfalle/
lib.rs

1//! Generic Farfalle construction which is generic over the cryptographic
2//! permutation and Kravatte and Xoofff instantiations.
3//!
4//! `Farfalle: Permutation -> DeckFunction`
5//!
6//! This crate contains an implementation of the [Farfalle construction],
7//! [`Farfalle`]. It is generic over the permutations and rolling functions
8//! used, through the [`FarfalleConfig`] trait. The [`Farfalle`] struct is
9//! intended to be used through the [`crypto_permutation::DeckFunction`] trait
10//! that it implements.
11//!
12//! __Note__: No security audits of this crate have ever been performed. Use at
13//! your own risk!
14//!
15//! The `kravatte` and `xoofff` crate-features enable the Kravatte and Xoofff
16//! instantiations of Farfalle, in the [`kravatte`] and [`xoofff`] modules
17//! respectively. These also contain the rolling functions that are used by
18//! these instantiations, so it is easy create your own custom instantiation of
19//! Farfalle that differs from Kravatte or Xoofff in the round count for the
20//! permutation (in case you think the advised parameters are not conservative
21//! enough).
22//!
23//! # Features
24//! * `kravatte`: Enables the [`kravatte`] module.
25//! * `xoofff`: Enables the [`xoofff`] module.
26//! * `debug`: Used for tests. Don't use!
27//!
28//! # Testing
29//! The Kravatte instantiation has been tested against the [`kravatte` python
30//! package]. The Xoofff instantiation has been tested against the [`xoofff`
31//! crate].
32//!
33//! [Farfalle construction]: https://keccak.team/farfalle.html
34//! [`kravatte` python package]: https://pypi.org/project/kravatte
35//! [`xoofff` crate]: https://crates.io/crates/xoofff
36
37#![cfg_attr(not(test), no_std)]
38#![allow(clippy::needless_lifetimes)]
39
40use crypto_permutation::{DeckFunction, Permutation, PermutationState};
41
42mod input;
43mod output;
44pub use input::{Farfalle, InputWriter};
45pub use output::FarfalleOutputGenerator;
46
47/// A rolling function as used in the Farfalle construction.
48pub trait RollFunction: Copy + Default {
49    /// The state this rolling function acts upon.
50    type State: PermutationState;
51
52    /// Apply the rolling function to the state.
53    fn apply(self, state: &mut Self::State);
54}
55
56/// Parameters for the Farfalle construction.
57///
58/// The permutation state is expected to be at least 33 bytes long, i.e. 262
59/// bits.
60pub trait FarfalleConfig: Default + Clone {
61    type State: PermutationState;
62    type PermutationB: Permutation<State = Self::State>;
63    type PermutationC: Permutation<State = Self::State>;
64    type PermutationD: Permutation<State = Self::State>;
65    type PermutationE: Permutation<State = Self::State>;
66    type RollC: RollFunction<State = Self::State>;
67    type RollE: RollFunction<State = Self::State>;
68
69    fn perm_b(&self) -> Self::PermutationB;
70    fn perm_c(&self) -> Self::PermutationC;
71    fn perm_d(&self) -> Self::PermutationD;
72    fn perm_e(&self) -> Self::PermutationE;
73    fn roll_c(&self) -> Self::RollC;
74    fn roll_e(&self) -> Self::RollE;
75}
76
77impl<C: FarfalleConfig> DeckFunction for Farfalle<C> {
78    type InputWriter<'a> = InputWriter<'a, C> where Self: 'a;
79    type OutputGenerator = FarfalleOutputGenerator<C>;
80
81    fn init(key: &[u8; 32]) -> Self {
82        Self::init_default(key.as_ref())
83    }
84
85    /// Produce a writer to input an additional input string.
86    fn input_writer<'a>(&'a mut self) -> Self::InputWriter<'a> {
87        InputWriter::new(self)
88    }
89
90    fn output_reader(&self) -> Self::OutputGenerator {
91        let mut state = self.state.clone();
92        self.config.perm_d().apply(&mut state);
93        FarfalleOutputGenerator::new(self.key.clone(), state, self.config.clone())
94    }
95}
96
97#[cfg(feature = "kravatte")]
98pub mod kravatte;
99#[cfg(feature = "xoofff")]
100pub mod xoofff;
deck_farfalle/lib.rs

deck_farfalle/
lib.rs
