pqc-binary-format 2.0.1

Standardized binary format for post-quantum cryptography encrypted data interchange
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145

//! # PQC Binary Format
//!
//! A standardized binary format for post-quantum cryptography encrypted data interchange.
//!
//! This crate implements **wire format version 1** (the `0x01` version byte, see
//! [`PQC_BINARY_VERSION`]) as defined by `draft-riddel-pqc-binary-format-00`. The
//! crate's own SemVer (2.x) is independent of the wire format version.
//!
//! ## Overview
//!
//! This crate provides a universal, self-describing binary format for encrypted data that works
//! across different post-quantum cryptographic algorithms. It solves the "Babel Tower problem"
//! where different PQC implementations cannot interoperate due to incompatible data formats.
//! Serialized envelopes are byte-compatible across the Rust, Python, WASM/JavaScript, C/C++,
//! and Go bindings.
//!
//! ## Features
//!
//! - **Algorithm-agnostic**: Works with 47 cryptographic algorithm identifiers
//! - **Self-describing metadata**: UTF-8 JSON parameters, compression settings, and custom fields
//! - **Integrity verification**: SHA-256 checksum over all preceding bytes
//! - **Feature flags**: Compression, streaming, authentication, experimental features
//! - **Extensible**: Custom parameters for algorithm-specific needs
//! - **Cross-platform**: Little-endian encoding, interoperable across languages and platforms
//!
//! ## Binary Layout
//!
//! All multi-byte integers are little-endian; the metadata section is a UTF-8
//! JSON object. Fixed-header size is 52 bytes.
//!
//! ```text
//! +-------------------+
//! | Magic (4 bytes)   | "PQC\x01"
//! +-------------------+
//! | Version (1 byte)  | 0x01
//! +-------------------+
//! | Algorithm (2 bytes)| Algorithm identifier (little-endian)
//! +-------------------+
//! | Flags (1 byte)    | Feature flags (reserved, 0x00 in v1)
//! +-------------------+
//! | Metadata Len (4)  | Length of metadata section (little-endian)
//! +-------------------+
//! | Metadata (var)    | Algorithm-specific metadata (UTF-8 JSON)
//! +-------------------+
//! | Data Len (8)      | Length of encrypted data (little-endian)
//! +-------------------+
//! | Data (var)        | Encrypted payload
//! +-------------------+
//! | Checksum (32)     | SHA-256 over all preceding bytes
//! +-------------------+
//! ```
//!
//! ## Quick Example
//!
//! ```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],
//!         tag: vec![1; 16],
//!         params: HashMap::new(),
//!     },
//!     ..Default::default()
//! };
//!
//! // Create encrypted data container
//! let encrypted_data = vec![1, 2, 3, 4, 5];
//! let format = PqcBinaryFormat::new(Algorithm::Hybrid, metadata, encrypted_data);
//!
//! // Serialize to bytes
//! let bytes = format.to_bytes().unwrap();
//!
//! // Deserialize from bytes (includes checksum verification)
//! let deserialized = PqcBinaryFormat::from_bytes(&bytes).unwrap();
//! assert_eq!(format, deserialized);
//! ```
//!
//! ## Supported Algorithms
//!
//! - **Classical**: X25519 + Ed25519 + AES-256-GCM
//! - **Hybrid**: ML-KEM-1024 + X25519 + ML-DSA-87 + Ed25519
//! - **Post-Quantum**: ML-KEM-1024 + ML-DSA-87
//! - **ML-KEM-1024**: Pure ML-KEM with AES-256-GCM
//! - **Multi-KEM**: Multiple key encapsulation layers
//! - **Quad-Layer**: Four independent cryptographic layers
//! - And 41 more algorithm identifiers (Max-Secure, FN-DSA, HQC, ML-KEM/DSA, SLH-DSA, ...)
//!
//! ## Use Cases
//!
//! - **Cross-platform encryption**: Encrypt in Rust, decrypt in Python/JavaScript/Go
//! - **Algorithm migration**: Seamlessly switch between algorithms
//! - **Long-term archival**: Self-describing format ensures future compatibility
//! - **Compliance**: Embedded metadata for audit trails
//! - **Research**: Standardized format for benchmarking PQC algorithms

#![warn(missing_docs)]
#![warn(clippy::all)]
#![warn(clippy::pedantic)]
#![allow(clippy::missing_errors_doc)]
#![allow(clippy::module_name_repetitions)]
#![allow(clippy::doc_markdown)]
#![allow(clippy::uninlined_format_args)]
#![allow(clippy::must_use_candidate)]
#![allow(clippy::return_self_not_must_use)]
#![allow(clippy::needless_pass_by_value)]
#![allow(clippy::unused_self)]
#![allow(clippy::struct_field_names)]
#![allow(clippy::ptr_as_ptr)]
#![allow(clippy::manual_let_else)]
#![allow(clippy::new_without_default)]

pub mod algorithm;
pub mod error;
pub mod format;
pub mod metadata;

// Language bindings (conditional compilation)
#[cfg(feature = "python")]
pub mod python;

#[cfg(feature = "wasm")]
pub mod wasm;

// FFI bindings always available for C/C++/Go
pub mod ffi;

// Re-exports for convenience
pub use algorithm::Algorithm;
pub use error::{CryptoError, Result};
pub use format::{FormatFlags, PqcBinaryFormat};
pub use metadata::{
    CompressionParameters, EncParameters, KemParameters, PqcMetadata, SigParameters,
};

/// Current version of the PQC Binary Format specification
pub const PQC_BINARY_VERSION: u8 = 0x01;

/// Magic bytes identifying PQC Binary Format v1.0
pub const PQC_MAGIC: [u8; 4] = *b"PQC\x01";

/// Version string for this crate
pub const VERSION: &str = env!("CARGO_PKG_VERSION");