pqc_binary_format/
lib.rs

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

pqc_binary_format/
lib.rs
