pqxdh_zoa/lib.rs
1#![warn(missing_docs)]
2#![deny(non_ascii_idents)]
3#![deny(unnameable_types)]
4#![deny(unreachable_pub)]
5#![deny(unsafe_code)]
6#![deny(unstable_features)]
7#![warn(unused_qualifications)]
8#![allow(clippy::tabs_in_doc_comments)]
9#![allow(clippy::type_complexity)]
10#![no_std]
11
12//! This implementation is generic and can be used with different KEM, AEAD and hash crates.
13//!
14//! We propose the following dependencies:
15//!
16//! ```toml
17//! aes-gcm-siv = "0.12.0-rc.3"
18//! ed25519-dalek = { version = "3.0.0-pre.6", features = ["rand_core"] }
19//! ml-kem = "0.3.0-rc.0"
20//! rand = "0.10.0"
21//! sha2 = "0.11.0-rc.5"
22//! ```
23//!
24//! Example: Bob publishes a key bundle so Alice can use it to send Bob a message.
25//!
26//! ```rust
27//! use ml_kem::Kem;
28//! use pqxdh_zoa::{PQXDH, ParamString, PrekeyBundle, traits::PQXDH as _};
29//! use rand::{Rng, RngExt, rngs::ThreadRng};
30//!
31//! type MyPQXDH = PQXDH<
32//! aes_gcm_siv::Aes256GcmSiv,
33//! ml_kem::MlKem1024,
34//! sha2::Sha512,
35//! MyPQXDHParamString,
36//! std::vec::Vec<u8>,
37//! >;
38//!
39//! struct MyPQXDHParamString;
40//! impl ParamString for MyPQXDHParamString {
41//! fn param_string<'a>() -> &'a [u8] {
42//! b"TestPQXDH_CURVE25519_SHA-512_ML-KEM-1024"
43//! }
44//! }
45//!
46//! let mut rng = rand::rng();
47//!
48//! // Alice
49//! let alice_id = ed25519_dalek::SigningKey::generate(&mut rng);
50//!
51//! // Bob
52//! let bob_id = ed25519_dalek::SigningKey::generate(&mut rng);
53//! let curve_prekey = ed25519_dalek::SigningKey::generate(&mut rng);
54//! let curve_ot_prekey = ed25519_dalek::SigningKey::generate(&mut rng);
55//! let (pqsk, pqpk) = ml_kem::MlKem1024::generate_keypair_from_rng(&mut rng);
56//!
57//! let prekey_bundle = PrekeyBundle {
58//! curve_prekey: curve_prekey.verifying_key(),
59//! curve_ot_prekey: Some(curve_ot_prekey.verifying_key()),
60//! identity_key: bob_id.verifying_key(),
61//! pq_prekey: pqpk,
62//! pq_prekey_id: 42,
63//! };
64//!
65//! let mut cleartext = b"Regardez les canards attendre au quai de la gare.";
66//! let (sk, ad, mut ciphertext) =
67//! MyPQXDH::send::<ThreadRng>(&alice_id, &prekey_bundle, cleartext.to_vec(), &mut rng)
68//! .unwrap();
69//! let (rec_sk, rec_ad) = MyPQXDH::receive(
70//! &bob_id,
71//! &curve_prekey,
72//! Some(&curve_ot_prekey),
73//! &mut ciphertext,
74//! &pqsk,
75//! )
76//! .unwrap();
77//! assert_eq!(cleartext.as_slice(), ciphertext.message.as_slice());
78//! assert_eq!(sk, rec_sk);
79//! assert_eq!(ad, rec_ad);
80//! ```
81
82/// Basic implementations
83#[cfg(feature = "impls")]
84mod impls;
85/// Generic traits for PQXDH
86pub mod traits;
87
88#[cfg(feature = "impls")]
89pub use impls::{Message, PQXDH, PrekeyBundle};
90pub use traits::{ParamString, ReceiveError, SendError};