lib_q_types/
lib.rs

1//! Shared algorithm identifiers and categories for lib-Q.
2//!
3//! This crate is the lowest dependency layer: implementation crates can depend on
4//! `lib-q-types` for `Algorithm` / `AlgorithmCategory` without pulling in `lib-q-core`.
5#![no_std]
6#![deny(unsafe_code)]
7#![deny(unused_qualifications)]
8
9pub mod hqc;
10
11#[cfg(feature = "wasm")]
12use wasm_bindgen::prelude::*;
13
14/// Algorithm identifiers for cryptographic operations
15#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord)]
16#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
17#[cfg_attr(feature = "wasm", wasm_bindgen)]
18pub enum Algorithm {
19    // KEM algorithms
20    MlKem512,
21    MlKem768,
22    MlKem1024,
23    CbKem348864,
24    CbKem460896,
25    CbKem6688128,
26    CbKem6960119,
27    CbKem8192128,
28    Hqc128,
29    Hqc192,
30    Hqc256,
31
32    // Signature algorithms
33    MlDsa44,
34    MlDsa65,
35    MlDsa87,
36    FnDsa,
37    FnDsa512,
38    FnDsa1024,
39    SlhDsaSha256128fRobust,
40    SlhDsaSha256192fRobust,
41    SlhDsaSha256256fRobust,
42    SlhDsaShake256128fRobust,
43    SlhDsaShake256192fRobust,
44    SlhDsaShake256256fRobust,
45
46    // Hash algorithms
47    Shake128,
48    Shake256,
49    CShake128,
50    CShake256,
51    Sha3_224,
52    Sha3_256,
53    Sha3_384,
54    Sha3_512,
55    Keccak224,
56    Keccak256,
57    Keccak384,
58    Keccak512,
59    Kt128,
60    Kt256,
61    TurboShake128,
62    TurboShake256,
63    Kmac128,
64    Kmac256,
65    TupleHash128,
66    TupleHash256,
67    ParallelHash128,
68    ParallelHash256,
69
70    // SHA-2 algorithms
71    Sha224,
72    Sha256,
73    Sha384,
74    Sha512,
75    Sha512_224,
76    Sha512_256,
77
78    // AEAD algorithms
79    Saturnin,
80    Shake256Aead,
81    DuplexSpongeAead,
82    TweakAead,
83    RomulusN,
84    RomulusM,
85    RoccaS,
86
87    /// Privacy-protocol identifiers (not standalone KEM/sig/hash providers).
88    LatticeRingSignature,
89    LatticeBlindIssuance,
90    LatticeAnonymousToken,
91    LatticeNullifierRegistry,
92    /// Witness-derived nullifier mode (SHAKE256 over opening witness wire; see `lib-q-lattice-zkp`).
93    LatticeWitnessNullifier,
94    /// DualRing-LB (CCS 2021 Alg. 3 aggregated verify on Ajtai openings, `lib-q-ring-sig`).
95    LatticeDualRingLb,
96    /// ML-KEM-768 layered encapsulation with Saturnin AEAD per hop (mix-layer transport).
97    MixOnionRouting,
98    /// SHAKE256 session token and stateless retry-cookie derivation for resumption handshakes.
99    SessionResumptionBinding,
100
101    // Reserved diversity signatures (registered DISABLED; not implemented)
102    /// **Reserved** FAEST / VOLE-in-the-Head signature (symmetric-only / AES assumptions).
103    ///
104    /// An assumption-diversity hedge against a structured-lattice break of the default ML-DSA: FAEST
105    /// rests on symmetric-primitive hardness alone, with no Module-LWE/Module-SIS structure. It is
106    /// large and slow relative to ML-DSA, so it is **never a default** — it is registered with
107    /// `enabled = false` and is intended to be activated only on a lattice-cryptanalysis event.
108    /// Supersedes Picnic (deprecated). Identifier only — no signing/verification is implemented.
109    /// See `lib-q-sig/docs/FAEST_EVALUATION.md`.
110    FaestReserved,
111}
112
113impl Algorithm {
114    /// Get the security level for this algorithm
115    pub fn security_level(&self) -> u32 {
116        match self {
117            // Level 1 (128-bit security)
118            Algorithm::MlKem512 => 1,
119            Algorithm::CbKem348864 => 1,
120            Algorithm::Hqc128 => 1,
121            Algorithm::MlDsa44 => 1,
122            Algorithm::FnDsa => 1,
123            Algorithm::FnDsa512 => 1,
124            Algorithm::SlhDsaSha256128fRobust => 1,
125            Algorithm::SlhDsaShake256128fRobust => 1,
126
127            // Level 3 (192-bit security)
128            Algorithm::MlKem768 => 3,
129            Algorithm::CbKem460896 => 3,
130            Algorithm::Hqc192 => 3,
131            Algorithm::MlDsa65 => 3,
132            Algorithm::SlhDsaSha256192fRobust => 3,
133            Algorithm::SlhDsaShake256192fRobust => 3,
134
135            // Level 4 (256-bit security)
136            Algorithm::MlKem1024 => 4,
137            Algorithm::CbKem6688128 => 4,
138            Algorithm::CbKem6960119 => 4,
139            Algorithm::Hqc256 => 4,
140            Algorithm::MlDsa87 => 4,
141            Algorithm::SlhDsaSha256256fRobust => 5,
142            Algorithm::SlhDsaShake256256fRobust => 5,
143
144            // Level 5 (256-bit security)
145            Algorithm::FnDsa1024 => 5,
146
147            // Level 5 (256-bit security, higher performance)
148            Algorithm::CbKem8192128 => 5,
149
150            // Hash algorithms don't have security levels
151            Algorithm::Shake128 |
152            Algorithm::Shake256 |
153            Algorithm::CShake128 |
154            Algorithm::CShake256 |
155            Algorithm::Sha3_224 |
156            Algorithm::Sha3_256 |
157            Algorithm::Sha3_384 |
158            Algorithm::Sha3_512 |
159            Algorithm::Keccak224 |
160            Algorithm::Keccak256 |
161            Algorithm::Keccak384 |
162            Algorithm::Keccak512 |
163            Algorithm::Kt128 |
164            Algorithm::Kt256 |
165            Algorithm::TurboShake128 |
166            Algorithm::TurboShake256 |
167            Algorithm::Kmac128 |
168            Algorithm::Kmac256 |
169            Algorithm::TupleHash128 |
170            Algorithm::TupleHash256 |
171            Algorithm::ParallelHash128 |
172            Algorithm::ParallelHash256 |
173            Algorithm::Sha224 |
174            Algorithm::Sha256 |
175            Algorithm::Sha384 |
176            Algorithm::Sha512 |
177            Algorithm::Sha512_224 |
178            Algorithm::Sha512_256 => 0,
179
180            // AEAD algorithms
181            Algorithm::Saturnin => 1,
182            Algorithm::Shake256Aead => 1,
183            Algorithm::DuplexSpongeAead => 4,
184            Algorithm::TweakAead => 4,
185            Algorithm::RomulusN => 1,
186            Algorithm::RomulusM => 1,
187            Algorithm::RoccaS => 1,
188
189            Algorithm::LatticeRingSignature |
190            Algorithm::LatticeBlindIssuance |
191            Algorithm::LatticeAnonymousToken |
192            Algorithm::LatticeNullifierRegistry |
193            Algorithm::LatticeWitnessNullifier |
194            Algorithm::LatticeDualRingLb |
195            Algorithm::MixOnionRouting |
196            Algorithm::SessionResumptionBinding => 3,
197
198            // Reserved diversity signature (Level 3 ≈ ML-DSA-65 class)
199            Algorithm::FaestReserved => 3,
200        }
201    }
202
203    /// Get the algorithm category
204    pub fn category(&self) -> AlgorithmCategory {
205        match self {
206            Algorithm::MlKem512 |
207            Algorithm::MlKem768 |
208            Algorithm::MlKem1024 |
209            Algorithm::CbKem348864 |
210            Algorithm::CbKem460896 |
211            Algorithm::CbKem6688128 |
212            Algorithm::CbKem6960119 |
213            Algorithm::CbKem8192128 |
214            Algorithm::Hqc128 |
215            Algorithm::Hqc192 |
216            Algorithm::Hqc256 => AlgorithmCategory::Kem,
217
218            Algorithm::MlDsa44 |
219            Algorithm::MlDsa65 |
220            Algorithm::MlDsa87 |
221            Algorithm::FnDsa |
222            Algorithm::FnDsa512 |
223            Algorithm::FnDsa1024 |
224            Algorithm::SlhDsaSha256128fRobust |
225            Algorithm::SlhDsaSha256192fRobust |
226            Algorithm::SlhDsaSha256256fRobust |
227            Algorithm::SlhDsaShake256128fRobust |
228            Algorithm::SlhDsaShake256192fRobust |
229            Algorithm::SlhDsaShake256256fRobust => AlgorithmCategory::Signature,
230
231            Algorithm::Shake128 |
232            Algorithm::Shake256 |
233            Algorithm::CShake128 |
234            Algorithm::CShake256 |
235            Algorithm::Sha3_224 |
236            Algorithm::Sha3_256 |
237            Algorithm::Sha3_384 |
238            Algorithm::Sha3_512 |
239            Algorithm::Keccak224 |
240            Algorithm::Keccak256 |
241            Algorithm::Keccak384 |
242            Algorithm::Keccak512 |
243            Algorithm::Kt128 |
244            Algorithm::Kt256 |
245            Algorithm::TurboShake128 |
246            Algorithm::TurboShake256 |
247            Algorithm::Kmac128 |
248            Algorithm::Kmac256 |
249            Algorithm::TupleHash128 |
250            Algorithm::TupleHash256 |
251            Algorithm::ParallelHash128 |
252            Algorithm::ParallelHash256 |
253            Algorithm::Sha224 |
254            Algorithm::Sha256 |
255            Algorithm::Sha384 |
256            Algorithm::Sha512 |
257            Algorithm::Sha512_224 |
258            Algorithm::Sha512_256 => AlgorithmCategory::Hash,
259
260            // AEAD algorithms
261            Algorithm::Saturnin |
262            Algorithm::Shake256Aead |
263            Algorithm::DuplexSpongeAead |
264            Algorithm::TweakAead |
265            Algorithm::RomulusN |
266            Algorithm::RomulusM |
267            Algorithm::RoccaS => AlgorithmCategory::Aead,
268
269            Algorithm::LatticeRingSignature |
270            Algorithm::LatticeBlindIssuance |
271            Algorithm::LatticeAnonymousToken |
272            Algorithm::LatticeNullifierRegistry |
273            Algorithm::LatticeWitnessNullifier |
274            Algorithm::LatticeDualRingLb |
275            Algorithm::MixOnionRouting |
276            Algorithm::SessionResumptionBinding => AlgorithmCategory::PrivacyProtocol,
277
278            // Reserved diversity signature
279            Algorithm::FaestReserved => AlgorithmCategory::Signature,
280        }
281    }
282
283    /// Check if an algorithm supports a specific category
284    pub fn supports_category(&self, category: AlgorithmCategory) -> bool {
285        match self {
286            // Pure KEM algorithms
287            Algorithm::MlKem512 |
288            Algorithm::MlKem768 |
289            Algorithm::MlKem1024 |
290            Algorithm::CbKem348864 |
291            Algorithm::CbKem460896 |
292            Algorithm::CbKem6688128 |
293            Algorithm::CbKem6960119 |
294            Algorithm::CbKem8192128 |
295            Algorithm::Hqc128 |
296            Algorithm::Hqc192 |
297            Algorithm::Hqc256 => category == AlgorithmCategory::Kem,
298
299            // Pure signature algorithms
300            Algorithm::MlDsa44 |
301            Algorithm::MlDsa65 |
302            Algorithm::MlDsa87 |
303            Algorithm::FnDsa |
304            Algorithm::FnDsa512 |
305            Algorithm::FnDsa1024 |
306            Algorithm::SlhDsaSha256128fRobust |
307            Algorithm::SlhDsaSha256192fRobust |
308            Algorithm::SlhDsaSha256256fRobust |
309            Algorithm::SlhDsaShake256128fRobust |
310            Algorithm::SlhDsaShake256192fRobust |
311            Algorithm::SlhDsaShake256256fRobust => category == AlgorithmCategory::Signature,
312
313            // Pure hash algorithms
314            Algorithm::Shake128 |
315            Algorithm::Shake256 |
316            Algorithm::CShake128 |
317            Algorithm::CShake256 |
318            Algorithm::Sha3_224 |
319            Algorithm::Sha3_256 |
320            Algorithm::Sha3_384 |
321            Algorithm::Sha3_512 |
322            Algorithm::Keccak224 |
323            Algorithm::Keccak256 |
324            Algorithm::Keccak384 |
325            Algorithm::Keccak512 |
326            Algorithm::Kt128 |
327            Algorithm::Kt256 |
328            Algorithm::TurboShake128 |
329            Algorithm::TurboShake256 |
330            Algorithm::Kmac128 |
331            Algorithm::Kmac256 |
332            Algorithm::TupleHash128 |
333            Algorithm::TupleHash256 |
334            Algorithm::ParallelHash128 |
335            Algorithm::ParallelHash256 |
336            Algorithm::Sha224 |
337            Algorithm::Sha256 |
338            Algorithm::Sha384 |
339            Algorithm::Sha512 |
340            Algorithm::Sha512_224 |
341            Algorithm::Sha512_256 => category == AlgorithmCategory::Hash,
342
343            // Pure AEAD algorithms
344            Algorithm::Saturnin |
345            Algorithm::Shake256Aead |
346            Algorithm::DuplexSpongeAead |
347            Algorithm::TweakAead |
348            Algorithm::RomulusN |
349            Algorithm::RomulusM |
350            Algorithm::RoccaS => category == AlgorithmCategory::Aead,
351
352            Algorithm::LatticeRingSignature |
353            Algorithm::LatticeBlindIssuance |
354            Algorithm::LatticeAnonymousToken |
355            Algorithm::LatticeNullifierRegistry |
356            Algorithm::LatticeWitnessNullifier |
357            Algorithm::LatticeDualRingLb |
358            Algorithm::MixOnionRouting |
359            Algorithm::SessionResumptionBinding => category == AlgorithmCategory::PrivacyProtocol,
360
361            // Reserved diversity signature
362            Algorithm::FaestReserved => category == AlgorithmCategory::Signature,
363        }
364    }
365}
366
367/// Algorithm categories
368#[derive(Debug, Clone, Copy, PartialEq, Eq)]
369#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
370#[cfg_attr(feature = "wasm", wasm_bindgen)]
371pub enum AlgorithmCategory {
372    Kem,
373    Signature,
374    Hash,
375    Aead,
376    /// Anonymous credentials, mix-layer transport helpers, and related ZKP-adjacent protocols.
377    PrivacyProtocol,
378}
379
380/// Security levels for cryptographic algorithms
381#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
382#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
383#[cfg_attr(feature = "wasm", wasm_bindgen)]
384pub enum SecurityLevel {
385    Level1 = 1, // 128-bit security
386    Level3 = 3, // 192-bit security
387    Level4 = 4, // 256-bit security
388    Level5 = 5, // 256-bit security (higher performance)
389}
390
391impl SecurityLevel {
392    /// Convert from u32 to SecurityLevel
393    pub fn from_u32(level: u32) -> Option<Self> {
394        match level {
395            1 => Some(SecurityLevel::Level1),
396            3 => Some(SecurityLevel::Level3),
397            4 => Some(SecurityLevel::Level4),
398            5 => Some(SecurityLevel::Level5),
399            _ => None,
400        }
401    }
402
403    /// Convert to u32
404    pub fn as_u32(self) -> u32 {
405        self as u32
406    }
407}
408
409impl core::fmt::Display for Algorithm {
410    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
411        match self {
412            // KEM algorithms
413            Algorithm::MlKem512 => write!(f, "ML-KEM-512"),
414            Algorithm::MlKem768 => write!(f, "ML-KEM-768"),
415            Algorithm::MlKem1024 => write!(f, "ML-KEM-1024"),
416            Algorithm::CbKem348864 => write!(f, "CB-KEM-348864"),
417            Algorithm::CbKem460896 => write!(f, "CB-KEM-460896"),
418            Algorithm::CbKem6688128 => write!(f, "CB-KEM-6688128"),
419            Algorithm::CbKem6960119 => write!(f, "CB-KEM-6960119"),
420            Algorithm::CbKem8192128 => write!(f, "CB-KEM-8192128"),
421            Algorithm::Hqc128 => write!(f, "HQC-128"),
422            Algorithm::Hqc192 => write!(f, "HQC-192"),
423            Algorithm::Hqc256 => write!(f, "HQC-256"),
424
425            // Signature algorithms
426            Algorithm::MlDsa44 => write!(f, "ML-DSA-44"),
427            Algorithm::MlDsa65 => write!(f, "ML-DSA-65"),
428            Algorithm::MlDsa87 => write!(f, "ML-DSA-87"),
429            Algorithm::FnDsa => write!(f, "FN-DSA"),
430            Algorithm::FnDsa512 => write!(f, "FN-DSA-512"),
431            Algorithm::FnDsa1024 => write!(f, "FN-DSA-1024"),
432            Algorithm::SlhDsaSha256128fRobust => write!(f, "SLH-DSA-SHA256-128f-Robust"),
433            Algorithm::SlhDsaSha256192fRobust => write!(f, "SLH-DSA-SHA256-192f-Robust"),
434            Algorithm::SlhDsaSha256256fRobust => write!(f, "SLH-DSA-SHA256-256f-Robust"),
435            Algorithm::SlhDsaShake256128fRobust => write!(f, "SLH-DSA-SHAKE256-128f-Robust"),
436            Algorithm::SlhDsaShake256192fRobust => write!(f, "SLH-DSA-SHAKE256-192f-Robust"),
437            Algorithm::SlhDsaShake256256fRobust => write!(f, "SLH-DSA-SHAKE256-256f-Robust"),
438
439            // Hash algorithms
440            Algorithm::Shake128 => write!(f, "SHAKE128"),
441            Algorithm::Shake256 => write!(f, "SHAKE256"),
442            Algorithm::CShake128 => write!(f, "cSHAKE128"),
443            Algorithm::CShake256 => write!(f, "cSHAKE256"),
444            Algorithm::Sha3_224 => write!(f, "SHA3-224"),
445            Algorithm::Sha3_256 => write!(f, "SHA3-256"),
446            Algorithm::Sha3_384 => write!(f, "SHA3-384"),
447            Algorithm::Sha3_512 => write!(f, "SHA3-512"),
448            Algorithm::Keccak224 => write!(f, "Keccak-224"),
449            Algorithm::Keccak256 => write!(f, "Keccak-256"),
450            Algorithm::Keccak384 => write!(f, "Keccak-384"),
451            Algorithm::Keccak512 => write!(f, "Keccak-512"),
452            Algorithm::Sha224 => write!(f, "SHA-224"),
453            Algorithm::Sha256 => write!(f, "SHA-256"),
454            Algorithm::Sha384 => write!(f, "SHA-384"),
455            Algorithm::Sha512 => write!(f, "SHA-512"),
456            Algorithm::Sha512_224 => write!(f, "SHA-512/224"),
457            Algorithm::Sha512_256 => write!(f, "SHA-512/256"),
458
459            // AEAD algorithms
460            Algorithm::Saturnin => write!(f, "Saturnin"),
461            Algorithm::Shake256Aead => write!(f, "SHAKE256-AEAD"),
462            Algorithm::DuplexSpongeAead => write!(f, "Duplex-Sponge-AEAD"),
463            Algorithm::TweakAead => write!(f, "Tweak-AEAD"),
464            Algorithm::RomulusN => write!(f, "Romulus-N"),
465            Algorithm::RomulusM => write!(f, "Romulus-M"),
466            Algorithm::RoccaS => write!(f, "Rocca-S"),
467
468            // Additional algorithms
469            Algorithm::Kt128 => write!(f, "KT128"),
470            Algorithm::Kt256 => write!(f, "KT256"),
471            Algorithm::TurboShake128 => write!(f, "TurboShake128"),
472            Algorithm::TurboShake256 => write!(f, "TurboShake256"),
473            Algorithm::Kmac128 => write!(f, "KMAC128"),
474            Algorithm::Kmac256 => write!(f, "KMAC256"),
475            Algorithm::TupleHash128 => write!(f, "TupleHash128"),
476            Algorithm::TupleHash256 => write!(f, "TupleHash256"),
477            Algorithm::ParallelHash128 => write!(f, "ParallelHash128"),
478            Algorithm::ParallelHash256 => write!(f, "ParallelHash256"),
479
480            Algorithm::LatticeRingSignature => write!(f, "Lattice-Ring-Signature"),
481            Algorithm::LatticeBlindIssuance => write!(f, "Lattice-Blind-Issuance"),
482            Algorithm::LatticeAnonymousToken => write!(f, "Lattice-Anonymous-Token"),
483            Algorithm::LatticeNullifierRegistry => write!(f, "Lattice-Nullifier-Registry"),
484            Algorithm::LatticeWitnessNullifier => write!(f, "Lattice-Witness-Nullifier"),
485            Algorithm::LatticeDualRingLb => write!(f, "Lattice-DualRing-LB"),
486            Algorithm::MixOnionRouting => write!(f, "Mix-Onion-Routing"),
487            Algorithm::SessionResumptionBinding => write!(f, "Session-Resumption-Binding"),
488
489            // Reserved diversity signature
490            Algorithm::FaestReserved => write!(f, "FAEST-Reserved"),
491        }
492    }
493}
494
495impl core::fmt::Display for AlgorithmCategory {
496    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
497        match self {
498            AlgorithmCategory::Kem => write!(f, "KEM"),
499            AlgorithmCategory::Signature => write!(f, "Signature"),
500            AlgorithmCategory::Hash => write!(f, "Hash"),
501            AlgorithmCategory::Aead => write!(f, "AEAD"),
502            AlgorithmCategory::PrivacyProtocol => write!(f, "Privacy protocol"),
503        }
504    }
505}
506
507#[cfg(test)]
508mod tests {
509    use super::*;
510
511    #[test]
512    fn test_algorithm_categories() {
513        assert_eq!(Algorithm::MlKem512.category(), AlgorithmCategory::Kem);
514        assert_eq!(Algorithm::Shake256Aead.category(), AlgorithmCategory::Aead);
515        assert_eq!(
516            Algorithm::LatticeAnonymousToken.category(),
517            AlgorithmCategory::PrivacyProtocol
518        );
519    }
520}
lib_q_types/lib.rs

lib_q_types/
lib.rs
