1#![doc = include_str!("../README.md")]
2#![doc(
3 html_logo_url = "https://avatars.githubusercontent.com/u/115088230",
4 html_favicon_url = "https://pqmayo.org/assets/favicon.ico"
5)]
6#![cfg_attr(not(any(feature = "std", test)), no_std)]
7
8extern crate alloc;
9
10mod errors;
11pub use errors::{Error, MayoError};
12
13mod batch_verify;
14pub use batch_verify::BatchVerifier;
15
16mod parameterization;
17pub use parameterization::{Mayo1, Mayo2, Mayo3, Mayo5, ParameterSet};
18
19mod public_key;
20pub use public_key::PublicKey;
21
22mod secret_key;
23pub use secret_key::SecretKey;
24
25mod signature;
26pub use signature::Signature;
27
28mod externs;
29
30#[cfg(test)]
31mod tests {
32 use super::*;
33 use core::fmt::Debug;
34 use rand_chacha::ChaCha20Rng;
35 use rand_core::SeedableRng;
36 use rstest::rstest;
37
38 #[rstest]
39 #[case::mayo_1(roundtrip::<Mayo1>)]
40 #[case::mayo_2(roundtrip::<Mayo2>)]
41 #[case::mayo_3(roundtrip::<Mayo3>)]
42 #[case::mayo_5(roundtrip::<Mayo5>)]
43 fn signs_and_verifies(#[case] test: fn()) {
44 run_on_large_stack(test);
45 }
46
47 fn roundtrip<P: ParameterSet>() {
48 let mut rng = ChaCha20Rng::from_seed([1; 32]);
49 let message = b"mayo signing test";
50 let (public_key, secret_key) = SecretKey::<P>::random(&mut rng).unwrap();
51 let signature = secret_key.sign(message).unwrap();
52
53 assert!(signature.verify(&public_key, message));
54 assert!(!signature.verify(&public_key, b"wrong message"));
55 }
56
57 #[rstest]
58 #[case::mayo_1(seeded_roundtrip::<Mayo1>)]
59 #[case::mayo_2(seeded_roundtrip::<Mayo2>)]
60 #[case::mayo_3(seeded_roundtrip::<Mayo3>)]
61 #[case::mayo_5(seeded_roundtrip::<Mayo5>)]
62 fn seeded_keygen_signs_and_verifies(#[case] test: fn()) {
63 run_on_large_stack(test);
64 }
65
66 fn seeded_roundtrip<P: ParameterSet>() {
67 let mut rng = ChaCha20Rng::from_seed([9; 32]);
68 let (public_key, secret_key) = SecretKey::<P>::random(&mut rng).unwrap();
69 let message = b"seeded keygen roundtrip";
70 let signature = secret_key.sign(message).unwrap();
71
72 assert!(signature.verify(&public_key, message));
73 }
74
75 #[rstest]
76 #[case::mayo_1(batch_roundtrip::<Mayo1>)]
77 #[case::mayo_2(batch_roundtrip::<Mayo2>)]
78 #[case::mayo_3(batch_roundtrip::<Mayo3>)]
79 #[case::mayo_5(batch_roundtrip::<Mayo5>)]
80 fn batch_verifies_duplicate_public_keys(#[case] test: fn()) {
81 run_on_large_stack(test);
82 }
83
84 fn batch_roundtrip<P: ParameterSet>() {
85 let mut rng = ChaCha20Rng::from_seed([2; 32]);
86 let (public_key, secret_key) = SecretKey::<P>::random(&mut rng).unwrap();
87 let first_message = b"first batch message";
88 let second_message = b"second batch message";
89 let first_signature = secret_key.sign(first_message).unwrap();
90 let second_signature = secret_key.sign(second_message).unwrap();
91
92 let mut batch = BatchVerifier::new();
93 batch
94 .add(&public_key, first_message, &first_signature)
95 .unwrap();
96 batch
97 .add(&public_key, second_message, &second_signature)
98 .unwrap();
99
100 assert_eq!(batch.len(), 1);
101 assert!(batch.verify());
102
103 let mut invalid_batch = BatchVerifier::new();
104 invalid_batch
105 .add(&public_key, b"wrong message", &first_signature)
106 .unwrap();
107
108 assert!(!invalid_batch.verify());
109 }
110
111 #[test]
112 fn rejects_wrong_lengths() {
113 assert!(matches!(
114 PublicKey::<Mayo1>::try_from(&[][..]),
115 Err(Error::InvalidLength {
116 expected: Mayo1::PUBLIC_KEY_BYTES,
117 actual: 0,
118 })
119 ));
120 assert!(matches!(
121 SecretKey::<Mayo1>::try_from(&[][..]),
122 Err(Error::InvalidLength {
123 expected: Mayo1::SECRET_KEY_BYTES,
124 actual: 0,
125 })
126 ));
127 assert!(matches!(
128 Signature::<Mayo1>::try_from(&[][..]),
129 Err(Error::InvalidLength {
130 expected: Mayo1::SIGNATURE_BYTES,
131 actual: 0,
132 })
133 ));
134 }
135
136 #[test]
137 fn empty_messages_can_be_signed() {
138 run_on_large_stack(|| {
139 let mut rng = ChaCha20Rng::from_seed([3; 32]);
140 let (public_key, secret_key) = SecretKey::<Mayo1>::random(&mut rng).unwrap();
141 let signature = secret_key.sign(&[]).unwrap();
142
143 assert!(signature.verify(&public_key, &[]));
144 });
145 }
146
147 #[test]
148 fn random_key_generation_uses_caller_rng() {
149 run_on_large_stack(|| {
150 let mut first_rng = ChaCha20Rng::from_seed([7; 32]);
151 let mut second_rng = ChaCha20Rng::from_seed([7; 32]);
152 let mut different_rng = ChaCha20Rng::from_seed([8; 32]);
153
154 let (first_public_key, first_secret_key) =
155 SecretKey::<Mayo3>::random(&mut first_rng).unwrap();
156 let (second_public_key, second_secret_key) =
157 SecretKey::<Mayo3>::random(&mut second_rng).unwrap();
158 let (different_public_key, different_secret_key) =
159 SecretKey::<Mayo3>::random(&mut different_rng).unwrap();
160
161 assert_eq!(first_public_key.as_ref(), second_public_key.as_ref());
162 assert_eq!(first_secret_key.as_ref(), second_secret_key.as_ref());
163 assert_ne!(first_public_key.as_ref(), different_public_key.as_ref());
164 assert_ne!(first_secret_key.as_ref(), different_secret_key.as_ref());
165
166 let message = b"seeded keygen test";
167 let signature = first_secret_key.sign(message).unwrap();
168 assert!(signature.verify(&first_public_key, message));
169 });
170 }
171
172 #[test]
173 fn keypairs_can_be_derived_from_secret_key_seeds() {
174 run_on_large_stack(|| {
175 let seed = [11; Mayo5::SECRET_KEY_BYTES];
176 let (public_key, secret_key) = SecretKey::<Mayo5>::from_seed(&seed).unwrap();
177 let (same_public_key, same_secret_key) = SecretKey::<Mayo5>::from_seed(&seed).unwrap();
178 let message = b"seeded constructor";
179 let signature = secret_key.sign(message).unwrap();
180
181 assert_eq!(secret_key.as_ref(), seed);
182 assert_eq!(same_secret_key.as_ref(), seed);
183 assert_eq!(public_key, same_public_key);
184 assert!(signature.verify(&public_key, message));
185 });
186 }
187
188 #[test]
189 fn seeded_keypair_derivation_rejects_wrong_lengths() {
190 assert!(matches!(
191 SecretKey::<Mayo1>::from_seed(&[]),
192 Err(Error::InvalidLength {
193 expected: Mayo1::SECRET_KEY_BYTES,
194 actual: 0,
195 })
196 ));
197 }
198
199 #[test]
200 fn binds_mayo_error_codes() {
201 assert_eq!(MayoError::MayoErr.code(), 1);
202 assert_eq!(MayoError::Unknown(7).code(), 7);
203 }
204
205 #[test]
206 fn concrete_public_types_expose_derived_traits() {
207 fn assert_public_traits<T: Debug + Eq + PartialEq>() {}
208 fn assert_secret_key_traits<T: Clone>() {}
209 fn assert_parameter_set<P: ParameterSet + Debug + Eq + PartialEq>() {
210 assert_public_traits::<P>();
211 assert_public_traits::<PublicKey<P>>();
212 assert_public_traits::<Signature<P>>();
213 assert_secret_key_traits::<SecretKey<P>>();
214 }
215
216 assert_parameter_set::<Mayo1>();
217 assert_parameter_set::<Mayo2>();
218 assert_parameter_set::<Mayo3>();
219 assert_parameter_set::<Mayo5>();
220 }
221
222 #[test]
223 fn cloned_secret_keys_keep_the_same_seed() {
224 run_on_large_stack(|| {
225 let mut rng = ChaCha20Rng::from_seed([12; 32]);
226 let (public_key, secret_key) = SecretKey::<Mayo3>::random(&mut rng).unwrap();
227 let cloned_secret_key = secret_key.clone();
228 let message = b"cloned signer";
229 let signature = cloned_secret_key.sign(message).unwrap();
230
231 assert_eq!(secret_key.as_ref(), cloned_secret_key.as_ref());
232 assert!(signature.verify(&public_key, message));
233 });
234 }
235
236 #[cfg(feature = "serde")]
237 #[test]
238 fn serde_impls_cover_all_parameter_sets() {
239 use serde::{Serialize, de::DeserializeOwned};
240
241 fn assert_serde<T: Serialize + DeserializeOwned>() {}
242 fn assert_parameter_set<P: ParameterSet>() {
243 assert_serde::<PublicKey<P>>();
244 assert_serde::<SecretKey<P>>();
245 assert_serde::<Signature<P>>();
246 }
247
248 assert_parameter_set::<Mayo1>();
249 assert_parameter_set::<Mayo2>();
250 assert_parameter_set::<Mayo3>();
251 assert_parameter_set::<Mayo5>();
252 }
253
254 fn run_on_large_stack(test: impl FnOnce() + Send + 'static) {
255 std::thread::Builder::new()
256 .stack_size(32 * 1024 * 1024)
257 .spawn(test)
258 .unwrap()
259 .join()
260 .unwrap();
261 }
262}