Standardized binary format for post-quantum cryptography encrypted data interchange
npm install pqc-binary-format



A standardized, self-describing binary format for post-quantum cryptography encrypted data interchange.
Post-quantum cryptography (PQC) implementations suffer from the "Babel Tower problem": different implementations cannot interoperate because there is no standardized format for encrypted data. Each library uses its own proprietary format, making cross-platform and cross-language encryption impossible.
PQC Binary Format provides a universal, algorithm-agnostic format that:
- โ
Works across 47 cryptographic algorithms
- โ
Self-describing metadata enables seamless decryption
- โ
Integrity verification with SHA-256 checksums
- โ
Cross-platform compatible (Rust, Python, JavaScript, Go, etc.)
- โ
Future-proof design allows algorithm migration
- โ
Zero dependencies except serde and sha2
Add to your Cargo.toml:
``toml`
[dependencies]
pqc-binary-format = "1.0"
`rust
use pqc_binary_format::{PqcBinaryFormat, Algorithm, PqcMetadata, EncParameters};
use std::collections::HashMap;
// Create metadata with encryption parameters
let metadata = PqcMetadata {
enc_params: EncParameters {
iv: vec![1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12], // 12-byte nonce
tag: vec![0; 16], // 16-byte auth tag
params: HashMap::new(),
},
..Default::default()
};
// Create encrypted data container
let encrypted_data = vec![1, 2, 3, 4, 5]; // Your encrypted bytes
let format = PqcBinaryFormat::new(Algorithm::Hybrid, metadata, encrypted_data);
// Serialize to bytes (for transmission or storage)
let bytes = format.to_bytes().unwrap();
// Deserialize from bytes (includes automatic checksum verification)
let recovered = PqcBinaryFormat::from_bytes(&bytes).unwrap();
assert_eq!(format, recovered);
println!("Algorithm: {}", recovered.algorithm().name());
`
Install the Python bindings:
`bash`
cd bindings/python
pip install maturin
maturin develop --release
`python
from pqc_binary_format import Algorithm, EncParameters, PqcMetadata, PqcBinaryFormat
$3
Build the WebAssembly bindings:
`bash
cd bindings/javascript
npm install
npm run build
``javascript
import init, { WasmAlgorithm, WasmEncParameters, WasmPqcMetadata, WasmPqcBinaryFormat } from './pqc_binary_format.js';await init();
const algorithm = new WasmAlgorithm('hybrid');
const encParams = new WasmEncParameters(
new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12]),
new Uint8Array(16)
);
const metadata = new WasmPqcMetadata(encParams);
const pqcFormat = new WasmPqcBinaryFormat(algorithm, metadata, new Uint8Array([1, 2, 3, 4, 5]));
const serialized = pqcFormat.toBytes();
const deserialized = WasmPqcBinaryFormat.fromBytes(serialized);
console.log(
Algorithm: ${deserialized.algorithm.name});
`$3
Build the Rust library first, then use the Go bindings:
`bash
cargo build --release
cd bindings/go
go build example.go
``go
package mainimport (
"fmt"
"log"
pqc "github.com/PQCrypta/pqcrypta-community/bindings/go"
)
func main() {
iv := []byte{1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12}
tag := make([]byte, 16)
data := []byte{1, 2, 3, 4, 5}
format, err := pqc.NewPqcBinaryFormat(pqc.AlgorithmHybrid, iv, tag, data)
if err != nil {
log.Fatal(err)
}
defer format.Free()
serialized, _ := format.ToBytes()
deserialized, _ := pqc.FromBytes(serialized)
defer deserialized.Free()
fmt.Printf("Algorithm: %s\n", deserialized.GetAlgorithmName())
}
`$3
Build the Rust library and generate the C header:
`bash
cargo build --release
cbindgen --config cbindgen.toml --output include/pqc_binary_format.h
cd bindings/c-cpp
make
``cpp
#include "pqc_binary_format.h"
#include
#include int main() {
std::vector iv = {1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12};
std::vector tag(16, 0);
std::vector data = {1, 2, 3, 4, 5};
PqcFormatHandle* format = pqc_format_new(
PQC_ALGORITHM_HYBRID,
iv.data(), iv.size(),
tag.data(), tag.size(),
data.data(), data.size()
);
ByteBuffer serialized = pqc_format_to_bytes(format);
PqcFormatHandle* deserialized = pqc_format_from_bytes(serialized.data, serialized.len);
char* alg_name = pqc_format_get_algorithm_name(deserialized);
std::cout << "Algorithm: " << alg_name << std::endl;
pqc_free_string(alg_name);
pqc_free_buffer(serialized);
pqc_format_free(deserialized);
pqc_format_free(format);
return 0;
}
`๐ Language Bindings
PQC Binary Format provides production-ready, fully tested bindings for multiple programming languages. All bindings support the complete API and produce cross-compatible binary formats.
$3
| Language | Status | Package | Documentation | Examples |
|----------|--------|---------|---------------|----------|
| Rust | โ
Native |
pqc-binary-format | docs.rs | 3 examples |
| Python | โ
Tested | pqc_binary_format | Python README | 2 examples |
| JavaScript/WASM | โ
Tested | pqc_binary_format (npm) | JS README | 1 example |
| Go | โ
Tested | github.com/PQCrypta/pqcrypta-community/bindings/go | pkg.go.dev | 1 example |
| C | โ
Tested | FFI via Rust | C/C++ README | 1 example |
| C++ | โ
Tested | FFI via Rust | C/C++ README | 1 example |$3
`bash
Rust
cargo add pqc-binary-formatPython (via maturin)
python3 -m venv .venv && source .venv/bin/activate
pip install maturin
maturin develop --releaseJavaScript/WASM (via wasm-pack)
wasm-pack build --target web --features wasmGo
go get github.com/PQCrypta/pqcrypta-community/bindings/goC/C++ (build from source)
cargo build --release --no-default-features
Link against target/release/libpqc_binary_format.so
`$3
All language bindings are fully interoperable! You can:
- โ
Encrypt data in Python, decrypt in Rust
- โ
Serialize in Go, deserialize in JavaScript
- โ
Create format in C++, validate in Python
- โ
Mix any combination across platforms
Example workflow:
`bash
Create encrypted data with Python
python3 examples/python/basic_usage.py > data.binVerify with C++
LD_LIBRARY_PATH=target/release ./examples/cpp/basic_usage < data.binProcess with Go
cd examples/go && go run basic_usage.go < ../../data.bin
`$3
All bindings support:
- โ
Full algorithm suite (47 algorithms)
- โ
Metadata serialization/deserialization
- โ
SHA-256 integrity verification
- โ
Feature flags (compression, streaming, etc.)
- โ
Error handling with detailed messages
- โ
Memory safety (Rust-backed)
$3
| Platform | Status | Notes |
|----------|--------|-------|
| crates.io (Rust) | โ
Published | v1.0.14 live! |
| PyPI (Python) | โ
Published | v1.0.14 live! |
| npm (JavaScript) | โ
Published | v1.0.14 live! |
| pkg.go.dev (Go) | โ
Indexed | v1.0.14 live! |
๐ฆ Binary Format Specification
`text
+-------------------+
| Magic (4 bytes) | "PQC\x01" - Format identifier
+-------------------+
| Version (1 byte) | 0x01 - Format version
+-------------------+
| Algorithm (2 bytes)| Algorithm identifier (0x0050 - 0x0905)
+-------------------+
| Flags (1 byte) | Feature flags (compression, streaming, etc.)
+-------------------+
| Metadata Len (4) | Length of metadata section
+-------------------+
| Data Len (8) | Length of encrypted payload
+-------------------+
| Metadata (var) | Algorithm-specific parameters
+-------------------+
| Data (var) | Encrypted data
+-------------------+
| Checksum (32) | SHA-256 integrity checksum
+-------------------+
`๐ Supported Algorithms
The format supports 47 cryptographic algorithm identifiers:
$3
- Classical (0x0050): X25519 + Ed25519 + AES-256-GCM
- Password Classical (0x0051): Password-based encryption$3
- Hybrid (0x0100): ML-KEM-1024 + X25519 + ML-DSA-87 + Ed25519$3
- Post-Quantum (0x0200): ML-KEM-1024 + ML-DSA-87
- ML-KEM-1024 (0x0202): Pure ML-KEM with AES-256-GCM
- Multi-KEM (0x0203): Dual-layer KEM
- Multi-KEM Triple (0x0204): Triple-layer KEM
- Quad-Layer (0x0205): Four independent layers
- PQ3-Stack (0x0207): Forward secrecy stack$3
High-security configurations for enterprise use$3
Falcon-based signature algorithms$3
Research and next-generation algorithms$3
NIST 2025 Backup KEM standard - code-based cryptography
- HQC-128 (0x0600): NIST Level 1, 128-bit security
- HQC-192 (0x0601): NIST Level 3, 192-bit security
- HQC-256 (0x0602): NIST Level 5, 256-bit security$3
- ML-KEM-512 (0x0700): NIST Level 1, 128-bit security
- ML-KEM-768 (0x0701): NIST Level 3, 192-bit security$3
- ML-DSA-44 (0x0800): NIST Level 2, 128-bit security
- ML-DSA-65 (0x0801): NIST Level 3, 192-bit security
- ML-DSA-87 (0x0802): NIST Level 5, 256-bit security$3
- SLH-DSA-SHA2-128s (0x0900): NIST Level 1, small signatures
- SLH-DSA-SHA2-128f (0x0901): NIST Level 1, fast signatures
- SLH-DSA-SHA2-192s (0x0902): NIST Level 3, small signatures
- SLH-DSA-SHA2-192f (0x0903): NIST Level 3, fast signatures
- SLH-DSA-SHA2-256s (0x0904): NIST Level 5, small signatures
- SLH-DSA-SHA2-256f (0x0905): NIST Level 5, fast signatures๐ฏ Features
$3
Control optional behavior with feature flags:
`rust
use pqc_binary_format::{PqcBinaryFormat, Algorithm, FormatFlags, PqcMetadata, EncParameters};
use std::collections::HashMap;let flags = FormatFlags::new()
.with_compression() // Data was compressed before encryption
.with_streaming() // Streaming encryption mode
.with_additional_auth(); // Additional authentication layer
let metadata = PqcMetadata {
enc_params: EncParameters {
iv: vec![1; 12],
tag: vec![1; 16],
params: HashMap::new(),
},
..Default::default()
};
let format = PqcBinaryFormat::with_flags(
Algorithm::QuadLayer,
flags,
metadata,
vec![1, 2, 3],
);
assert!(format.flags().has_compression());
assert!(format.flags().has_streaming());
`$3
The format includes rich metadata for decryption:
`rust
use pqc_binary_format::{PqcMetadata, KemParameters, SigParameters, EncParameters, CompressionParameters};
use std::collections::HashMap;let metadata = PqcMetadata {
// Key Encapsulation (optional)
kem_params: Some(KemParameters {
public_key: vec![/ ML-KEM public key /],
ciphertext: vec![/ encapsulated key /],
params: HashMap::new(),
}),
// Digital Signature (optional)
sig_params: Some(SigParameters {
public_key: vec![/ ML-DSA public key /],
signature: vec![/ signature bytes /],
params: HashMap::new(),
}),
// Symmetric Encryption (required)
enc_params: EncParameters {
iv: vec![1; 12], // Nonce/IV
tag: vec![1; 16], // AEAD auth tag
params: HashMap::new(),
},
// Compression (optional)
compression_params: Some(CompressionParameters {
algorithm: "zstd".to_string(),
level: 3,
original_size: 1024,
params: HashMap::new(),
}),
// Custom parameters (extensible)
custom: HashMap::new(),
};
`$3
Add your own metadata:
`rust
use pqc_binary_format::PqcMetadata;let mut metadata = PqcMetadata::new();
metadata.add_custom("my_param".to_string(), vec![1, 2, 3]);
// Later...
if let Some(value) = metadata.get_custom("my_param") {
println!("Custom param: {:?}", value);
}
`๐ Integrity Verification
Every format includes a SHA-256 checksum calculated over all fields:
`rust
use pqc_binary_format::PqcBinaryFormat;let bytes = format.to_bytes().unwrap();
// Tamper with the data
// let mut corrupted = bytes.clone();
// corrupted[50] ^= 0xFF;
// Deserialization automatically verifies checksum
match PqcBinaryFormat::from_bytes(&bytes) {
Ok(format) => println!("โ Checksum valid"),
Err(e) => println!("โ Checksum failed: {}", e),
}
`๐ Examples
$3
`rust
use pqc_binary_format::{PqcBinaryFormat, Algorithm, PqcMetadata, EncParameters};
use std::collections::HashMap;fn main() {
let metadata = PqcMetadata {
enc_params: EncParameters {
iv: vec![1; 12],
tag: vec![1; 16],
params: HashMap::new(),
},
..Default::default()
};
let format = PqcBinaryFormat::new(
Algorithm::Hybrid,
metadata,
vec![/ your encrypted data /],
);
// Save to file
let bytes = format.to_bytes().unwrap();
std::fs::write("encrypted.pqc", &bytes).unwrap();
// Load from file
let loaded_bytes = std::fs::read("encrypted.pqc").unwrap();
let loaded = PqcBinaryFormat::from_bytes(&loaded_bytes).unwrap();
println!("Algorithm: {}", loaded.algorithm().name());
}
`$3
Rust (Encryption)
`rust
let format = PqcBinaryFormat::new(Algorithm::PostQuantum, metadata, data);
let bytes = format.to_bytes().unwrap();
// Send bytes to Python/JavaScript/Go/C++
`Python (Decryption)
`python
from pqc_binary_format import PqcBinaryFormatformat = PqcBinaryFormat.from_bytes(bytes)
print(f"Algorithm: {format.algorithm().name()}")
print(f"Data: {len(format.data())} bytes")
`JavaScript (Decryption)
`javascript
const format = WasmPqcBinaryFormat.fromBytes(bytes);
console.log(Algorithm: ${format.algorithm.name});
console.log(Data: ${format.data.length} bytes);
`Go (Decryption)
`go
format, _ := pqc.FromBytes(bytes)
defer format.Free()
fmt.Printf("Algorithm: %s\n", format.GetAlgorithmName())
fmt.Printf("Data: %d bytes\n", len(format.GetData()))
`$3
`rust
// Old data encrypted with Classical algorithm
let old_format = PqcBinaryFormat::from_bytes(&old_encrypted_data)?;
assert_eq!(old_format.algorithm(), Algorithm::Classical);// Re-encrypt with Post-Quantum algorithm
let plaintext = decrypt_with_classical(&old_format)?;
let new_metadata = create_pq_metadata()?;
let new_format = PqcBinaryFormat::new(
Algorithm::PostQuantum,
new_metadata,
encrypt_with_pq(&plaintext)?,
);
// Same format, different algorithm!
`๐ Use Cases
$3
Encrypt in Rust, decrypt in Python, JavaScript, or Go using the same format.$3
Self-describing format ensures data can be decrypted decades later even as algorithms evolve.$3
Switch between algorithms without changing application code.$3
Embedded metadata provides audit trail for regulatory compliance (GDPR, HIPAA, etc.).$3
Standardized format enables fair comparison of PQC algorithm performance.๐งช Testing
`bash
Run tests
cargo testRun tests with output
cargo test -- --nocaptureRun specific test
cargo test test_binary_format_roundtrip
`๐ Benchmarks
`bash
Run benchmarks
cargo benchView benchmark results
open target/criterion/report/index.html
`Performance characteristics:
- Serialization: ~50 MB/s for typical payloads
- Deserialization: ~45 MB/s (includes checksum verification)
- Overhead: ~100 bytes + metadata size
๐ง Development
$3
`bash
git clone https://github.com/PQCrypta/pqcrypta-community.git
cd pqcrypta-community
cargo build --release
`$3
`bash
cargo run --example basic_usage
cargo run --example with_compression
cargo run --example cross_platform
``We welcome contributions! See CONTRIBUTING.md for guidelines.
- Language Bindings: โ
Rust (native), โ
Python (tested v1.0.14), โ
JavaScript/WASM (tested v1.0.14), โ
Go (tested v1.0.14), โ
C/C++ (tested v1.0.14)
- Examples: โ
9 validated examples across 6 languages
- Package Distribution: โ
All platforms published! crates.io, PyPI, npm, pkg.go.dev
- Additional Language Bindings: Java, C#, Ruby, Swift, Kotlin - help us expand!
- Documentation: Tutorials, integration guides, video walkthroughs
- Testing: Additional test cases, fuzzing, property-based testing
- Performance: SIMD optimizations, benchmark improvements
- Standards: Help draft RFC for IETF standardization submission
Licensed under either of:
- MIT License (LICENSE-MIT or http://opensource.org/licenses/MIT)
- Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
at your option.
This format was developed as part of the PQCrypta enterprise post-quantum cryptography platform. Special thanks to:
- NIST Post-Quantum Cryptography Project
- The Rust cryptography community
- Contributors to pqcrypto, ring, and other foundational crates
- NIST Post-Quantum Cryptography
- ML-KEM (Kyber) Specification
- ML-DSA (Dilithium) Specification
- PQCrypta Documentation
- pqcrypto - Rust PQC implementations
- Open Quantum Safe - PQC library collection
- CIRCL - Cloudflare's crypto library
- GitHub Issues: Report bugs
- Discussions: Ask questions
- Website: pqcrypta.com
- Documentation: docs.rs/pqc-binary-format
---
Made with โค๏ธ by the PQCrypta Community
Securing the future, one byte at a time.