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 28+ 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
96pub mod algorithm;
97pub mod error;
98pub mod format;
99pub mod metadata;
100
101// Re-exports for convenience
102pub use algorithm::Algorithm;
103pub use error::{CryptoError, Result};
104pub use format::{FormatFlags, PqcBinaryFormat};
105pub use metadata::{
106    CompressionParameters, EncParameters, KemParameters, PqcMetadata, SigParameters,
107};
108
109/// Current version of the PQC Binary Format specification
110pub const PQC_BINARY_VERSION: u8 = 0x01;
111
112/// Magic bytes identifying PQC Binary Format v1.0
113pub const PQC_MAGIC: [u8; 4] = *b"PQC\x01";
114
115/// Version string for this crate
116pub const VERSION: &str = env!("CARGO_PKG_VERSION");
pqc_binary_format/lib.rs

pqc_binary_format/
lib.rs
