streaming_crypto/core_api/constants.rs
1
2/// "RSE1" = Rust Streaming Envelope v1, magic number for this envelope version.
3/// - If the constant represents a **protocol magic field** (like `"RSE1"` in a header), use `[u8; 4]`.
4/// - That way the type itself enforces “exactly 4 bytes” and matches our struct field type (`[u8; 4]`).
5pub const MAGIC_RSE1: [u8; 4] = *b"RSE1";
6pub const HEADER_V1: u16 = 1;
7
8/// Industry-standard master key lengths (AES-128, AES-192, AES-256)
9pub const MASTER_KEY_LENGTHS: [usize; 3] = [16, 24, 32];
10
11/// Defaults when Option<T> is None
12pub const DEFAULT_CHUNK_SIZE: usize = 64 * 1024; // 64 KB
13/// Industry-standard chunk sizes (in bytes) ✅
14pub const ALLOWED_CHUNK_SIZES: &[usize] = &[
15 16 * 1024, // 16 KiB - IoT/embedded, constrained memory
16 32 * 1024, // 32 KiB - Mobile devices, network packets
17 64 * 1024, // 64 KiB - Default (good balance) ✅ RECOMMENDED
18 128 * 1024, // 128 KiB - Desktop apps
19 256 * 1024, // 256 KiB - Server applications
20 1024 * 1024, // 1 MiB - Bulk data processing
21 2048 * 1024, // 2 MiB - Large file transfers
22 4096 * 1024, // 4 MiB - High-throughput systems
23];
24/// Max chunk size sanity bound (32 MiB).
25pub const MAX_CHUNK_SIZE: usize = 32 * 1024 * 1024;
26
27// Basic sanity: minimum length and maybe a magic prefix
28// require first 4 bytes to be a magic number
29// - If the constant is more of a **prefix marker** we’ll check against slices (like `"DICT"` at the start of a dictionary payload), then `&[u8]` is fine:
30pub const MAGIC_DICT: &[u8] = b"DICT";
31pub const MIN_DICT_LEN: usize = 8;
32pub const MAX_DICT_LEN: usize = 1 << 20; // 1 MiB cap for sanity
33
34/// Strategy choices for encoder metadata (decoder may still parallelize).
35pub mod strategy_ids {
36 pub const AUTO: u16 = 0x0000;
37 pub const SEQUENTIAL: u16 = 0x0001;
38 pub const PARALLEL: u16 = 0x0002;
39}
40
41/// Cipher suite identifiers (mirrored in headers).
42pub mod cipher_ids {
43 pub const AES256_GCM: u16 = 0x0001;
44 pub const CHACHA20_POLY1305: u16 = 0x0002;
45
46 pub fn name(id: u16) -> &'static str {
47 match id {
48 AES256_GCM => "AES256_GCM",
49 CHACHA20_POLY1305 => "CHACHA20_POLY1305",
50 _ => "UNKNOWN",
51 }
52 }
53}
54
55/// HKDF PRF identifiers (mirrored in headers).
56pub mod prf_ids {
57 pub const SHA256: u16 = 0x0001;
58 pub const SHA512: u16 = 0x0002;
59 pub const SHA3_256: u16 = 0x0003;
60 pub const SHA3_512: u16 = 0x0004;
61 pub const BLAKE3K: u16 = 0x0005; // keyed BLAKE3 (avoid unless policy requires)
62}
63
64/// Algorithm profile bundles cipher + PRF combinations.
65pub mod alg_profile_ids {
66 pub const AES256_GCM_HKDF_SHA256: u16 = 0x0101;
67 pub const AES256_GCM_HKDF_SHA512: u16 = 0x0102;
68 pub const CHACHA20_POLY1305_HKDF_SHA256: u16 = 0x0201;
69 pub const CHACHA20_POLY1305_HKDF_SHA512: u16 = 0x0202;
70 pub const CHACHA20_POLY1305_HKDF_BLAKE3K: u16 = 0x0203;
71}
72
73/// AAD domain identifiers.
74pub mod aad_domain_ids {
75 pub const GENERIC: u16 = 0x0001;
76 pub const FILE_ENVELOPE: u16 = 0x0002;
77 pub const PIPE_ENVELOPE: u16 = 0x0003;
78}
79
80/// DIGEST ALG identifiers (mirrored in headers).
81pub mod digest_ids {
82 // Sha224 = 0x0001,
83 pub const SHA256: u16 = 0x0002;
84 // Sha384 = 0x0003,
85 pub const SHA512: u16 = 0x0004;
86 // Sha3_224 = 0x0101,
87 pub const SHA3_256: u16 = 0x0102;
88 // Sha3_384 = 0x0103,
89 pub const SHA3_512: u16 = 0x0104;
90 pub const BLAKE3K: u16 = 0x0201; // UN-KEYED Blake3
91}
92
93/// Flag bitmask for optional features and metadata presence.
94pub mod flags {
95 pub const HAS_TOTAL_LEN: u16 = 0x0001;
96 pub const HAS_CRC32: u16 = 0x0002;
97 pub const HAS_TERMINATOR: u16 = 0x0004;
98 pub const HAS_FINAL_DIGEST: u16 = 0x0008;
99 pub const DICT_USED: u16 = 0x0010;
100 pub const AAD_STRICT: u16 = 0x0020;
101}
102
103// ### 📊 Comparison table
104
105// | **Setting** | **Industry Standard** | **Rationale** |
106// |-------------|------------------------|---------------|
107// | **Queue cap** | **[4–16](guide://action?prefill=Tell%20me%20more%20about%3A%204%E2%80%9316)** | **[low latency, avoids memory bloat](guide://action?prefill=Tell%20me%20more%20about%3A%20low%20latency%2C%20avoids%20memory%20bloat)** |
108// | **Workers** | **[match physical cores](guide://action?prefill=Tell%20me%20more%20about%3A%20match%20physical%20cores)** (usually 4–16) | **[CPU‑bound crypto tasks scale linearly](guide://action?prefill=Tell%20me%20more%20about%3A%20CPU%E2%80%91bound%20crypto%20tasks%20scale%20linearly)** |
109// | **Beyond 16** | **[rarely beneficial](guide://action?prefill=Tell%20me%20more%20about%3A%20rarely%20beneficial)** | **[context switching overhead dominates](guide://action?prefill=Tell%20me%20more%20about%3A%20context%20switching%20overhead%20dominates)** |
110
111// ### 🧩 Why worker count matters
112// - **Match physical cores**: Each worker is CPU‑bound (AES, compression, HKDF). Running more workers than cores just adds context‑switch overhead.
113// - **Typical range**: 4–16 workers for server‑class CPUs; 2–8 for laptops.
114// - **Scaling**: Beyond 16 workers, diminishing returns set in unless we’re on a many‑core server (32+ cores).
115pub const WORKERS_COUNT: &[usize] = &[2, 4, 8, 16];
116
117// ### 🧩 Why queue cap matters
118// - **Small queue (2–16)**: Keeps latency low, avoids excessive buffering, and ensures back‑pressure works correctly.
119// - **Large queue (>32)**: Can cause memory bloat, uneven scheduling, and delayed error propagation. Most cryptographic pipelines (AES, VPNs, TLS offload) deliberately cap queues at small powers of two.
120// - **Industry practice**: VPN engines, GPU crypto libraries, and parallel AES implementations typically use **queue caps of 4–16**.
121pub const QUEUE_CAPS: &[usize] = &[2, 4, 8, 16];
122pub const DEFAULT_WORKERS: usize = 2; // or num_cpus::get().saturation_sub(1)
123pub const DEFAULT_QUEUE_CAP: usize = 4; // or workers * 2