oqs_safe/lib.rs
1//! # oqs-safe
2//!
3//! A Post-Quantum Cryptography (PQC) toolkit in Rust built on top of libOQS.
4//!
5//! This crate provides safe, minimal abstractions for:
6//! - Post-quantum key exchange (ML-KEM)
7//! - Post-quantum signatures (ML-DSA)
8//! - Hybrid cryptography (X25519 + ML-KEM)
9//! - Secure session key derivation (HKDF)
10//!
11//! ## Features
12//!
13//! - ML-KEM (512 / 768 / 1024)
14//! - ML-DSA (44 / 65 / 87)
15//! - Hybrid cryptography (classical + PQC)
16//! - Zeroized secret handling
17//! - Mock backend (default) + liboqs backend
18//!
19//! ## Quick Example (KEM)
20//!
21//! ```rust
22//! use oqs_safe::kem::{Kem, KemAlgorithm, KemInstance};
23//!
24//! let kem = KemInstance::new(KemAlgorithm::MlKem768);
25//!
26//! let (pk, sk) = kem.keypair().unwrap();
27//! let (ct, ss1) = kem.encapsulate(&pk).unwrap();
28//! let ss2 = kem.decapsulate(&ct, &sk).unwrap();
29//!
30//! assert_eq!(ss1.len(), ss2.len());
31//! ```
32//!
33//! ## Signature Example (ML-DSA)
34//!
35//! ```rust
36//! use oqs_safe::sig::{SigAlgorithm, SigInstance, SignatureScheme};
37//!
38//! let sig = SigInstance::new(SigAlgorithm::MlDsa44);
39//!
40//! let (pk, sk) = sig.keypair().unwrap();
41//! let msg = b"hello pqc";
42//!
43//! let signature = sig.sign(&sk, msg).unwrap();
44//! sig.verify(&pk, msg, &signature).unwrap();
45//! ```
46//!
47//! ## Hybrid Example (Recommended for PQC Migration)
48//!
49//! ```no_run
50//! // Run the full example:
51//! // cargo run --example hybrid_x25519_mlkem
52//! ```
53//!
54//! ## Modules
55//!
56//! - [`kem`] - Post-quantum key exchange (ML-KEM)
57//! - [`sig`] - Post-quantum signatures (ML-DSA)
58//! - [`hybrid`] - Hybrid cryptography helpers
59//! - [`session`] - Secure session key derivation
60//! - [`error`] - Error types
61//!
62//! ## Backends
63//!
64//! - Default: mock backend (no native dependencies, for CI/dev)
65//! - Optional: `liboqs` feature for real PQC operations
66//!
67//! ## Security Notes
68//!
69//! - Always derive keys using HKDF before use
70//! - Use hybrid cryptography (X25519 + ML-KEM) for migration
71//! - Do not rely on PQC-only deployments yet
72//! - Avoid logging or serializing secret material
73//!
74//! This crate is not formally audited.
75#![deny(unsafe_op_in_unsafe_fn)]
76#![cfg_attr(docsrs, feature(doc_cfg))]
77
78pub mod error;
79pub mod hybrid;
80pub mod kem;
81pub mod sig;
82
83// NEW: expose session module publicly
84pub mod session;
85
86// NEW: expose classical crypto helpers (X25519)
87pub mod classical;
88
89#[cfg(feature = "liboqs")]
90pub(crate) mod ffi;
91
92pub use error::OqsError;