PostQuantum.FileEncryption.Hybrid 1.6.0

PostQuantum.FileEncryption.Hybrid

The single recommended path for public-key file encryption in this suite. Encrypt files to a recipient's public key so that only their private key can open them — protected by X25519 + ML-KEM-768 together, so your data stays safe even if either primitive is later broken.

Fully managed (BouncyCastle) — no native ML-KEM / OpenSSL 3.5 requirement, so it runs anywhere .NET 8 or later runs (net8.0 and net10.0 targets). Produces standard .pqfe containers.

dotnet add package PostQuantum.FileEncryption.Hybrid --version 1.6.0

Versioning. This package is intentionally kept in lockstep with PostQuantum.FileEncryption: every release of one ships at the same version as the other, and Hybrid's pack pins the matching core version. The two packages are one cryptographic unit — the core owns the .pqfe container and the chunk/AEAD engine; Hybrid plugs into the core's KeyEstablishment seam to add the public-key path. A version mismatch would mean Hybrid is talking to a different format/engine than the one it was designed against. See docs/VERSIONING.md.

Migrating from the deprecated inline ML-KEM-only mode

If you previously used PqKeyPair / PqRecipientPublicKey / PqRecipientPrivateKey and the recipient overloads on PqFileEncryptor / PqFileDecryptor in the core PostQuantum.FileEncryption package, those are deprecated (PQFE002) as of 1.0.0-rc.2. They remain for source-compatibility but emit a deprecation warning; removal is targeted for a future major release.

// Before (deprecated PQFE001 + PQFE002 in the core package, platform-gated by ML-KEM):
using var keyPair = PqKeyPair.Generate();
await new PqFileEncryptor().EncryptFileAsync("plain.bin", "cipher.pqfe", keyPair.PublicKey);
await new PqFileDecryptor().DecryptFileAsync("cipher.pqfe", "out.bin", keyPair.PrivateKey);

// After (this package — hybrid combiner, runs everywhere, no platform gate):
using var keyPair = PqHybridKeyPair.Generate();
await new PqHybridEncryptor().EncryptFileAsync("plain.bin", "cipher.pqfe", keyPair.PublicKey);
await new PqHybridDecryptor().DecryptFileAsync("cipher.pqfe", "out.bin", keyPair.PrivateKey);

Usage

using PostQuantum.FileEncryption.Hybrid;

// Recipient: generate once, publish the public key, keep the private key safe.
using var keyPair = PqHybridKeyPair.Generate();
byte[] publish = keyPair.PublicKey.Export();

// Sender: encrypt to the public key.
var recipient = PqHybridPublicKey.Import(publish);
byte[] container = await new PqHybridEncryptor().EncryptBytesAsync(secretBytes, recipient);

// Recipient: decrypt with the private key.
byte[] plaintext = await new PqHybridDecryptor().DecryptBytesAsync(container, keyPair.PrivateKey);

Storing the private key

PrivateKey.Export() returns raw secret bytes; for storage, prefer the passphrase-encrypted form — an authenticated, Argon2id-hardened key file that fails closed on a wrong passphrase or any tampering:

byte[] keyFile = keyPair.PrivateKey.ExportEncrypted(passphrase);   // store this
using var privateKey = PqHybridPrivateKey.ImportEncrypted(keyFile, passphrase);

See docs/KEY-FILE-FORMAT.md for the byte-exact format (a standard .pqfe container behind a five-byte framing — no new cryptography).

Multiple recipients

var recipients = new[] { alice, bob, carol }; // PqHybridPublicKey[]
await new PqHybridEncryptor().EncryptFileToAsync("report.pdf", "report.pqfe", recipients);
// Any one of alice/bob/carol can decrypt with their own private key.

Up to 55 recipients per container. The limit is not arbitrary: each recipient entry is 1,186 bytes (the ML-KEM-768 ciphertext dominates it), and the frozen .pqfe v2 header carries all entries in a length field capped at 65,535 bytes — ⌊65,534 / 1,186⌋ = 55. The limit is enforced before any wrapping work, and widening the field is banked as a format-v3 candidate (KNOWN-GAPS.md). For genuinely larger audiences, wrap to a group key held in a KMS via IContentKeyProvider instead — access-group membership then lives where it can be revoked.

File and stream APIs (EncryptFileAsync, EncryptAsync, DecryptFileAsync, DecryptAsync) are also available, with atomic file output and progress reporting.

How it works

X25519 ECDH and ML-KEM-768 encapsulation each produce a shared secret; HKDF-SHA256 combines them (ss_pq ‖ ss_classical) into a key-wrapping key that AES-256-GCM uses to wrap a random content key. See the format spec (KeySource = 3 and 4), docs/HYBRID-COMBINER.md (design rationale — how this relates to X-Wing, HPKE, and RFC 9794 terminology), and docs/ROADMAP-v3.md.

To God be the glory — 1 Corinthians 10:31.