# B-Wing

[![Crates.io](https://img.shields.io/crates/v/b-wing.svg)](https://crates.io/crates/b-wing)
[![Documentation](https://docs.rs/b-wing/badge.svg)](https://docs.rs/b-wing)
[![License](https://img.shields.io/badge/license-MIT%2FApache--2.0-blue.svg)](https://codeberg.org/hacer-bark/b-wing)
[![unsafe forbidden](https://img.shields.io/badge/unsafe-forbidden-success.svg)](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:

| 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`:

```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

| 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:

- 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.
