# B-Wing
[](https://crates.io/crates/b-wing)
[](https://docs.rs/b-wing)
[](https://codeberg.org/hacer-bark/b-wing)
[](https://github.com/rust-secure-code/safety-dance/)
**B-Wing** is a high-assurance **hybrid post-quantum cryptography** library for Rust. It implements [NIST Level 5](https://csrc.nist.gov/projects/post-quantum-cryptography) security with paranoia-grade 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 (e.g., via a cryptanalytic breakthrough or a future quantum computer), the combined construction remains secure.
## Security Architecture
### KWing — Key Encapsulation Mechanism
Combines three independent KEMs into a single shared secret via HKDF-SHA3-512 transcript binding:
| 1 | **X25519** | Classical ECDH — Curve25519 discrete log |
| 2 | **ML-KEM-1024** (Kyber) | Module-lattice MLWE (NIST PQ Level 5) |
| 3 | **FrodoKEM-1344-SHAKE** | Unstructured LWE — conservative lattice |
### SWing — Digital Signatures
Combines three independent signature schemes into a single composite signature blob; **all three must pass** for verification to succeed:
| 1 | **Ed25519** | Classical ECDSA — Edwards-curve discrete log |
| 2 | **ML-DSA-87** (Dilithium) | Module-lattice MLWE (NIST PQ Level 5) |
| 3 | **SLH-DSA-SHAKE256f** (Sphincs+) | Hash-based — conservative PQ |
## Design Principles
* **Caller-Supplied Randomness:** All randomness is provided by the caller as typed seed arrays. The API is fully deterministic — no hidden global RNG state — and therefore compatible with `no_std`, WASM, and embedded targets.
* **Heap-Cached Keys:** Pre-computes and caches composite keys once on construction, amortising the cost of key-derivation across many operations.
* **Zeroize on Drop:** All secret material is wrapped in `zeroize::Zeroizing`, guaranteeing erasure from memory when the value goes out of scope.
* **Strict Size Validation:** Every public entry-point validates buffer sizes before performing any cryptographic work, failing fast on malformed inputs.
* **Domain-Separated Binding:** Signatures and shared secrets are bound to the specific public key, transcript, and caller-supplied context, preventing cross-protocol and cross-key confusion attacks.
## Quick Start
Add B-Wing to your `Cargo.toml`:
```toml
[dependencies]
b-wing = { version = "0.1", features = ["kem", "sign"] }
```
### Key Encapsulation (KWing)
```rust
use b_wing::{KWing, KemError};
// --- Key generation (recipient) -----------------------------------
// Derive a long-lived key pair from a 128-byte secret seed.
// In production, fill `seed` from a CSPRNG (e.g., `getrandom::fill`).
let secret_seed = [0u8; 128];
let recipient = KWing::from_seed(&secret_seed).unwrap();
let encapsulation_key = recipient.get_pub_key(); // share this with senders
// --- Encapsulation (sender) ---------------------------------------
// MUST be freshly generated for every encapsulation — never reuse!
let encaps_seed = [1u8; 128];
let (ciphertext, shared_secret_sender) = KWing::encapsulate(&encaps_seed, encapsulation_key).unwrap();
// --- Decapsulation (recipient) ------------------------------------
// Recover the same 64-byte Output Keying Material (OKM).
let shared_secret_recipient = recipient.decapsulate(&ciphertext).unwrap();
assert_eq!(shared_secret_sender, shared_secret_recipient);
```
### Digital Signatures (SWing)
```rust
use b_wing::{SWing, SignError};
// --- Key generation (signer) --------------------------------------
// Derive a long-lived key pair from a 160-byte master seed.
// In production, fill `master_seed` from a CSPRNG.
let master_seed = [0u8; 160];
let signer = SWing::from_seed(&master_seed).unwrap();
let verification_key = signer.get_pub_key(); // publish / distribute to verifiers
// --- Signing ------------------------------------------------------
let message = b"Authenticated payload";
let context = b"my-app-v1";
// MUST be freshly generated for every signature — never reuse!
let random_seed = [1u8; 64];
let signature = signer.sign(message, context, random_seed).unwrap();
// --- Verification -------------------------------------------------
// Succeeds only if all three sub-signatures are valid.
let ok = SWing::verify(verification_key, message, context, &signature).unwrap();
assert!(ok);
```
## Feature Flags
| `kem` | Compiles the `kem` module and the `KWing` / `KemError` re-exports. | Yes |
| `sign` | Compiles the `signing` module and the `SWing` / `SignError` re-exports. | Yes |
Both features can be enabled simultaneously, or selectively for binary-size-sensitive targets.
## License
Licensed under either of:
- Apache License, Version 2.0 ([LICENSE-APACHE](https://codeberg.org/hacer-bark/b-wing/src/branch/main/LICENSE-APACHE) or <http://www.apache.org/licenses/LICENSE-2.0>)
- MIT license ([LICENSE-MIT](https://codeberg.org/hacer-bark/b-wing/src/branch/main/LICENSE-MIT) or <http://opensource.org/licenses/MIT>)
at your option.