b_wing/

lib.rs

//! # B-Wing
//!
//! A high-assurance **hybrid post-quantum cryptography** library implementing
//! [NIST Level 5][nist-pqc] security with redundancy across multiple classical
//! and post-quantum algorithms.
//!
//! B-Wing follows a **redundancy-first** design: every operation is secured by
//! *at least* one classical elliptic-curve primitive **and** two structurally
//! distinct post-quantum primitives. Even if an adversary completely breaks two
//! out of three algorithms, the combined construction remains secure.
//!
//! ## Modules
//!
//! | Module | Feature flag | Description |
//! |--------|-------------|-------------|
//! | [`kem`] | `kem` | **KWing** — Hybrid Key Encapsulation Mechanism |
//! | [`signing`] | `sign` | **SWing** — Hybrid Digital Signature Scheme |
//!
//! ## Security Architecture
//!
//! ### KWing — Key Encapsulation Mechanism
//!
//! Combines three independent KEMs into a single shared secret via
//! HKDF-SHA3-512:
//!
//! | Layer | Algorithm | Assumption |
//! |-------|-----------|------------|
//! | 1 | X25519 | Classical (ECDH) |
//! | 2 | ML-KEM-1024 (Kyber) | Module-lattice (PQ) |
//! | 3 | FrodoKEM-1344-SHAKE | Unstructured LWE (PQ) |
//!
//! ### SWing — Digital Signatures
//!
//! Combines three independent signature schemes into a single composite
//! signature blob; **all three must pass** for verification to succeed:
//!
//! | Layer | Algorithm | Assumption |
//! |-------|-----------|------------|
//! | 1 | Ed25519 | Classical (EdDSA) |
//! | 2 | ML-DSA-87 (Dilithium) | Module-lattice (PQ) |
//! | 3 | SLH-DSA-SHAKE256f (Sphincs+) | Hash-based (PQ) |
//!
//! ## Quick Start
//!
//! Add B-Wing to `Cargo.toml`:
//!
//! ```toml
//! [dependencies]
//! b-wing = "0.1"
//! ```
//!
//! ### Key Encapsulation (KWing)
//!
//! ```rust,no_run
//! use b_wing::{KWing, KemError};
//!
//! # fn example() -> Result<(), KemError> {
//! // --- Recipient side ---
//! // Derive a long-lived key pair from a 128-byte secret seed.
//! // In production, fill `seed` from a CSPRNG (e.g. `getrandom::fill`).
//! let seed = [0u8; 128];
//! let recipient = KWing::from_seed(&seed)?;
//! let public_key = recipient.get_pub_key(); // share this with senders
//!
//! // --- Sender side ---
//! // Encapsulate a fresh shared secret.  The 128-byte encaps_seed MUST be
//! // generated freshly for every encapsulation (never reuse it).
//! let encaps_seed = [1u8; 128];
//! let (ciphertext, shared_secret_sender) = KWing::encapsulate(&encaps_seed, public_key)?;
//!
//! // --- Recipient side (again) ---
//! // Recover the same 64-byte OKM from the ciphertext.
//! let shared_secret_recipient = recipient.decapsulate(&ciphertext)?;
//!
//! assert_eq!(shared_secret_sender, shared_secret_recipient);
//! # Ok(())
//! # }
//! ```
//!
//! ### Digital Signatures (SWing)
//!
//! ```rust,no_run
//! use b_wing::{SWing, SignError};
//!
//! # fn example() -> Result<(), SignError> {
//! // --- Signer side ---
//! // Derive a long-lived key pair from a 160-byte master seed.
//! let master_seed = [0u8; 160];
//! let signer = SWing::from_seed(&master_seed)?;
//! let verification_key = signer.get_pub_key(); // publish / distribute this
//!
//! let message   = b"Authenticated payload";
//! let context   = b"my-application-v1";
//! // The random_seed MUST be generated freshly from a CSPRNG for every signature.
//! let random_seed = [2u8; 64];
//!
//! let signature = signer.sign(message, context, random_seed)?;
//!
//! // --- Verifier side ---
//! // Verification succeeds only when all three sub-signatures are valid.
//! let ok = SWing::verify(verification_key, message, context, &signature)?;
//! assert!(ok);
//! # Ok(())
//! # }
//! ```
//!
//! ## Feature Flags
//!
//! * **`kem`** *(enabled by default)* — Compiles the [`kem`] module and the
//!   [`KWing`] / [`KemError`] re-exports.
//! * **`sign`** — Compiles the [`signing`] module and the [`SWing`] /
//!   [`SignError`] re-exports.
//!
//! Both features can be enabled simultaneously, or selectively for
//! binary-size-sensitive targets.
//!
//! ## Design Invariants
//!
//! * **Caller-supplied randomness.** All randomness is provided by the caller
//!   as typed seed arrays, making the API fully deterministic and suitable for
//!   `no_std`, WASM, and embedded targets.
//! * **Heap-cached keys.** Pre-computed composite public keys are stored on the
//!   heap to amortise the cost of key derivation across many operations.
//! * **Zeroize on drop.** All secret material is wrapped in [`zeroize::Zeroizing`]
//!   and erased from memory when it goes out of scope.
//! * **Strict size validation.** Every public API validates buffer sizes before
//!   performing any cryptographic work, returning [`KemError::InvalidFormat`] or
//!   [`SignError::InvalidFormat`] on mismatch.
//!
//! [nist-pqc]: https://csrc.nist.gov/projects/post-quantum-cryptography

#![doc(issue_tracker_base_url = "https://codeberg.org/hacer-bark/b-wing/issues")]
#![forbid(unsafe_code)]
#![warn(missing_docs)]
#![warn(rust_2018_idioms)]
#![warn(unused_qualifications)]
#![cfg_attr(docsrs, feature(doc_cfg))]

#[cfg(feature = "sign")]
#[cfg_attr(docsrs, doc(cfg(feature = "sign")))]
/// Hybrid classical/PQ digital signature scheme (SWing).
///
/// See the [module-level docs](signing) for a full security breakdown and
/// usage examples.
pub mod signing;

#[cfg(feature = "sign")]
pub use signing::{Error as SignError, SWing};

#[cfg(feature = "kem")]
#[cfg_attr(docsrs, doc(cfg(feature = "kem")))]
/// Hybrid classical/PQ key encapsulation mechanism (KWing).
///
/// See the [module-level docs](kem) for a full security breakdown and
/// usage examples.
pub mod kem;

#[cfg(feature = "kem")]
pub use kem::{Error as KemError, KWing};