b-wing 0.1.1

High-assurance hybrid post-quantum cryptography library. Implements NIST Level 5 PQ security with redundant classical+PQ KEM (KWing) and Signatures (SWing).
Documentation

B-Wing

Crates.io Documentation License unsafe forbidden

B-Wing is a high-assurance hybrid post-quantum cryptography library for Rust. It implements NIST Level 5 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:

Layer Algorithm Security Assumption
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:

Layer Algorithm Security Assumption
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:

[dependencies]
b-wing = { version = "0.1", features = ["kem", "sign"] }

Key Encapsulation (KWing)

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)

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

Feature Description Default
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:

at your option.