pqc_binary_format/
lib.rs

1//! # PQC Binary Format
2//!
3//! A standardized binary format for post-quantum cryptography encrypted data interchange.
4//!
5//! This crate implements **wire format version 1** (the `0x01` version byte, see
6//! [`PQC_BINARY_VERSION`]) as defined by `draft-riddel-pqc-binary-format-00`. The
7//! crate's own SemVer (2.x) is independent of the wire format version.
8//!
9//! ## Overview
10//!
11//! This crate provides a universal, self-describing binary format for encrypted data that works
12//! across different post-quantum cryptographic algorithms. It solves the "Babel Tower problem"
13//! where different PQC implementations cannot interoperate due to incompatible data formats.
14//! Serialized envelopes are byte-compatible across the Rust, Python, WASM/JavaScript, C/C++,
15//! and Go bindings.
16//!
17//! ## Features
18//!
19//! - **Algorithm-agnostic**: Works with 47 cryptographic algorithm identifiers
20//! - **Self-describing metadata**: UTF-8 JSON parameters, compression settings, and custom fields
21//! - **Integrity verification**: SHA-256 checksum over all preceding bytes
22//! - **Feature flags**: Compression, streaming, authentication, experimental features
23//! - **Extensible**: Custom parameters for algorithm-specific needs
24//! - **Cross-platform**: Little-endian encoding, interoperable across languages and platforms
25//!
26//! ## Binary Layout
27//!
28//! All multi-byte integers are little-endian; the metadata section is a UTF-8
29//! JSON object. Fixed-header size is 52 bytes.
30//!
31//! ```text
32//! +-------------------+
33//! | Magic (4 bytes)   | "PQC\x01"
34//! +-------------------+
35//! | Version (1 byte)  | 0x01
36//! +-------------------+
37//! | Algorithm (2 bytes)| Algorithm identifier (little-endian)
38//! +-------------------+
39//! | Flags (1 byte)    | Feature flags (reserved, 0x00 in v1)
40//! +-------------------+
41//! | Metadata Len (4)  | Length of metadata section (little-endian)
42//! +-------------------+
43//! | Metadata (var)    | Algorithm-specific metadata (UTF-8 JSON)
44//! +-------------------+
45//! | Data Len (8)      | Length of encrypted data (little-endian)
46//! +-------------------+
47//! | Data (var)        | Encrypted payload
48//! +-------------------+
49//! | Checksum (32)     | SHA-256 over all preceding bytes
50//! +-------------------+
51//! ```
52//!
53//! ## Quick Example
54//!
55//! ```rust
56//! use pqc_binary_format::{PqcBinaryFormat, Algorithm, PqcMetadata, EncParameters};
57//! use std::collections::HashMap;
58//!
59//! // Create metadata with encryption parameters
60//! let metadata = PqcMetadata {
61//!     enc_params: EncParameters {
62//!         iv: vec![1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12],
63//!         tag: vec![1; 16],
64//!         params: HashMap::new(),
65//!     },
66//!     ..Default::default()
67//! };
68//!
69//! // Create encrypted data container
70//! let encrypted_data = vec![1, 2, 3, 4, 5];
71//! let format = PqcBinaryFormat::new(Algorithm::Hybrid, metadata, encrypted_data);
72//!
73//! // Serialize to bytes
74//! let bytes = format.to_bytes().unwrap();
75//!
76//! // Deserialize from bytes (includes checksum verification)
77//! let deserialized = PqcBinaryFormat::from_bytes(&bytes).unwrap();
78//! assert_eq!(format, deserialized);
79//! ```
80//!
81//! ## Supported Algorithms
82//!
83//! - **Classical**: X25519 + Ed25519 + AES-256-GCM
84//! - **Hybrid**: ML-KEM-1024 + X25519 + ML-DSA-87 + Ed25519
85//! - **Post-Quantum**: ML-KEM-1024 + ML-DSA-87
86//! - **ML-KEM-1024**: Pure ML-KEM with AES-256-GCM
87//! - **Multi-KEM**: Multiple key encapsulation layers
88//! - **Quad-Layer**: Four independent cryptographic layers
89//! - And 41 more algorithm identifiers (Max-Secure, FN-DSA, HQC, ML-KEM/DSA, SLH-DSA, ...)
90//!
91//! ## Use Cases
92//!
93//! - **Cross-platform encryption**: Encrypt in Rust, decrypt in Python/JavaScript/Go
94//! - **Algorithm migration**: Seamlessly switch between algorithms
95//! - **Long-term archival**: Self-describing format ensures future compatibility
96//! - **Compliance**: Embedded metadata for audit trails
97//! - **Research**: Standardized format for benchmarking PQC algorithms
98
99#![warn(missing_docs)]
100#![warn(clippy::all)]
101#![warn(clippy::pedantic)]
102#![allow(clippy::missing_errors_doc)]
103#![allow(clippy::module_name_repetitions)]
104#![allow(clippy::doc_markdown)]
105#![allow(clippy::uninlined_format_args)]
106#![allow(clippy::must_use_candidate)]
107#![allow(clippy::return_self_not_must_use)]
108#![allow(clippy::needless_pass_by_value)]
109#![allow(clippy::unused_self)]
110#![allow(clippy::struct_field_names)]
111#![allow(clippy::ptr_as_ptr)]
112#![allow(clippy::manual_let_else)]
113#![allow(clippy::new_without_default)]
114
115pub mod algorithm;
116pub mod error;
117pub mod format;
118pub mod metadata;
119
120// Language bindings (conditional compilation)
121#[cfg(feature = "python")]
122pub mod python;
123
124#[cfg(feature = "wasm")]
125pub mod wasm;
126
127// FFI bindings always available for C/C++/Go
128pub mod ffi;
129
130// Re-exports for convenience
131pub use algorithm::Algorithm;
132pub use error::{CryptoError, Result};
133pub use format::{FormatFlags, PqcBinaryFormat};
134pub use metadata::{
135    CompressionParameters, EncParameters, KemParameters, PqcMetadata, SigParameters,
136};
137
138/// Current version of the PQC Binary Format specification
139pub const PQC_BINARY_VERSION: u8 = 0x01;
140
141/// Magic bytes identifying PQC Binary Format v1.0
142pub const PQC_MAGIC: [u8; 4] = *b"PQC\x01";
143
144/// Version string for this crate
145pub const VERSION: &str = env!("CARGO_PKG_VERSION");
pqc_binary_format/lib.rs

pqc_binary_format/
lib.rs
