Skip to main content

Crate pqc_binary_format

Crate pqc_binary_format 

Source
Expand description

§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.

+-------------------+
| 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

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

Re-exports§

pub use algorithm::Algorithm;
pub use error::CryptoError;
pub use error::Result;
pub use format::FormatFlags;
pub use format::PqcBinaryFormat;
pub use metadata::CompressionParameters;
pub use metadata::EncParameters;
pub use metadata::KemParameters;
pub use metadata::PqcMetadata;
pub use metadata::SigParameters;

Modules§

algorithm
Algorithm identifiers for supported post-quantum cryptographic algorithms.
error
Error types for PQC Binary Format operations.
ffi
C/C++ FFI bindings for PQC Binary Format
format
Core binary format implementation with serialization and validation.
metadata
Metadata structures for algorithm-specific parameters.
python
Python bindings for PQC Binary Format using PyO3
wasm
WebAssembly bindings for PQC Binary Format

Constants§

PQC_BINARY_VERSION
Current version of the PQC Binary Format specification
PQC_MAGIC
Magic bytes identifying PQC Binary Format v1.0
VERSION
Version string for this crate