toolkit_zero/serialization/
mod.rs

1//! Struct-to-binary serialization via the VEIL cipher.
2//!
3//! This module converts any [`bincode`]-encodable value into an opaque,
4//! key-dependent byte sequence and back.  The conversion is performed by the
5//! **VEIL** (Variable-Expansion Interleaved Lattice) cipher designed
6//! specifically for this toolkit.
7//!
8//! # What VEIL guarantees
9//!
10//! * **No magic bytes / constant header.** The output has no recognisable
11//!   structure — it looks like uniformly random bytes.
12//! * **Key-dependent, irreversible without the key.** Every step of the
13//!   cipher is keyed.  Without the exact key an attacker cannot invert any
14//!   individual step, let alone the full pipeline.
15//! * **Position-sensitive.** Identical plaintext bytes at different offsets
16//!   always produce different ciphertext bytes.
17//! * **Diffusion across the entire message.** Every output byte depends on
18//!   all preceding input bytes (sequential block accumulator).
19//! * **No standard crypto primitives.** The key schedule, S-box, stream, and
20//!   shuffle are all derived from a custom PRNG seeded with a keyed hash.
21//!
22//! # VEIL pipeline (seal direction)
23//!
24//! ```text
25//! struct  ──bincode──►  raw bytes
26//!                           │
27//!              ┌────────────▼────────────┐
28//!              │  1. keyed S-box sub     │  each byte replaced via key-derived
29//!              │  2. key-stream XOR      │  permutation table + stream
30//!              │  3. position mixing     │  byte ⊕ f(index, neighbours)
31//!              │  4. block diffusion     │  16-byte blocks, sequential acc
32//!              │  5. block byte shuffle  │  keyed permutation per block
33//!              └────────────┬────────────┘
34//!                           │
35//!              bincode wrap (Vec<u8> envelope)
36//!                           │
37//!                       `Vec<u8>`
38//! ```
39//!
40//! `open` reverses every step in exact reverse order.
41//!
42//! # Default key
43//!
44//! When no key is supplied, the string `"serialization/deserialization"` is
45//! used.
46//!
47//! # Example
48//!
49//! ```no_run
50//! use toolkit_zero::serialization::{seal, open, Encode, Decode};
51//!
52//! #[derive(Encode, Decode, Debug, PartialEq)]
53//! struct Point { x: f64, y: f64 }
54//!
55//! let p = Point { x: 1.5, y: -3.0 };
56//!
57//! let blob = seal(&p, None).unwrap();
58//! let back: Point = open(&blob, None).unwrap();
59//! assert_eq!(p, back);
60//!
61//! // with an explicit key
62//! let blob2 = seal(&p, Some("my secret key")).unwrap();
63//! let back2: Point = open(&blob2, Some("my secret key")).unwrap();
64//! assert_eq!(p, back2);
65//! ```
66
67mod veil;
68
69pub use veil::{seal, open, SerializationError};
70pub use bincode::{Encode, Decode};
71
72#[cfg(feature = "backend-deps")]
73pub mod backend_deps;
toolkit_zero/serialization/mod.rs

toolkit_zero/serialization/
mod.rs
