PQ-WB-KEM: White-Box ML-KEM-768 1.0
PQ-WB-KEM: Toward a White-Box Construction of ML-KEM-768 with Arithmetic Masking for M2M Communications - Mathematics (MDPI)
Loading...
Searching...
No Matches
obfuscation_storage.py
Go to the documentation of this file.
1#!/usr/bin/env python3
2# -*- coding: utf-8 -*-
3"""
4@file obfuscation_storage.py
5@brief Measure the stored size of the two obfuscation layers wrapping the base
6 multiply -- the coefficient shuffle and the runtime masking.
7@ingroup core
8
9@details The paper's storage breakdown previously carried the shuffle and masking
10cost as a bare estimate. This produces it. The shuffle is a permutation of the
11N=256 NTT coefficients of the secret (built by np.random.permutation(N) in
12algebraic_attack_analysis.py; the manuscript calls it a coefficient shuffle),
13applied per secret polynomial (k=3 for ML-KEM-768). It is stored with its inverse
14at the uint16 width the base and encoding tables use. Masking stores nothing: the
15three arithmetic shares are drawn at runtime per decapsulation
16(whitebox_reference.py three_share), so its stored size is zero. The deployment
17footprint is therefore the measured core (concrete_security_bounds.json) plus a
18few kilobytes.
19
20@note Deterministic (seed 42); writes results/obfuscation_storage.json. The core
21sizes are read from concrete_security_bounds.json, not recomputed, so this script
22depends on that result being present.
23
24@section obfuscation_storage_usage Usage
25@code{.sh}
26python obfuscation_storage.py
27@endcode
28
29@author Ugur Coruh
30
31@copyright
32This software is provided for academic and research purposes.
33See LICENSE file for details.
34"""
35
36import json
37from pathlib import Path
38
39import numpy as np
40
41N = 256 # NTT polynomial degree; the shuffle permutes these coefficients
42K = 3 # module rank for ML-KEM-768: one shuffle per secret polynomial
43SEED = 42
44BYTES_PER_ENTRY = 2 # uint16, matching the base-multiply and encoding tables
45MB = 1_000_000 # the paper reports decimal MB (25.57, 11.08, 3.41)
46
47
48def results_dir() -> Path:
49 """@brief Repository results directory."""
50 return Path(__file__).resolve().parent.parent.parent / "results"
51
52
54 """
55 @brief One coefficient shuffle pi and its inverse, as stored uint16 tables.
56 @param rng Seeded NumPy generator.
57 @return (pi, pi_inv) each shape (K, N), uint16.
58 """
59 pi = np.empty((K, N), dtype=np.uint16)
60 pi_inv = np.empty((K, N), dtype=np.uint16)
61 for p in range(K):
62 perm = rng.permutation(N).astype(np.uint16)
63 pi[p] = perm
64 inv = np.empty(N, dtype=np.uint16)
65 inv[perm.astype(np.int64)] = np.arange(N, dtype=np.uint16)
66 pi_inv[p] = inv
67 return pi, pi_inv
68
69
71 """
72 @brief Read the measured core footprints from concrete_security_bounds.json.
73 @return (a_bytes, b_bytes) integer byte counts for Constructions A and B.
74 @note Hard error if absent -- the deployment total is core plus shuffle, and a
75 guessed core would defeat the point of measuring the shuffle.
76 """
77 path = results_dir() / "concrete_security_bounds.json"
78 if not path.exists():
79 raise FileNotFoundError(
80 f"Missing {path}. Run concrete_security_bounds.py first; "
81 f"obfuscation_storage.py reads the measured core from it and does not "
82 f"recompute or guess it."
83 )
84 d = json.loads(path.read_text(encoding="utf-8"))
85 bounds = d["security_bounds"]
86 return (
87 int(bounds["core_footprint_A_shared"]["table_size_bytes"]),
88 int(bounds["core_footprint_B_baked"]["table_size_bytes"]),
89 )
90
91
92def main():
93 """
94 @brief Measure the obfuscation-layer storage and write the summary JSON.
95 @return 0 on success.
96 """
97 rng = np.random.default_rng(SEED)
98 pi, pi_inv = build_shuffle(rng)
99
100 roundtrip = all(
101 np.array_equal(pi_inv[p][pi[p].astype(np.int64)], np.arange(N))
102 for p in range(K)
103 )
104 if not roundtrip:
105 raise RuntimeError(
106 "Shuffle inverse does not round-trip; refusing to "
107 "report a size for a shuffle that is not a permutation."
108 )
109
110 shuffle_bytes = int(pi.nbytes + pi_inv.nbytes)
111 if shuffle_bytes != K * 2 * N * BYTES_PER_ENTRY:
112 raise RuntimeError(
113 f"Serialized shuffle size {shuffle_bytes} does not match the expected "
114 f"{K * 2 * N * BYTES_PER_ENTRY} (K x (pi+pi_inv) x N x {BYTES_PER_ENTRY})."
115 )
116
117 masking_bytes = 0 # runtime three-share; no table is stored
118 core_a, core_b = read_core()
119 total_a = core_a + shuffle_bytes + masking_bytes
120 total_b = core_b + shuffle_bytes + masking_bytes
121
122 summary = {
123 "shuffle": {
124 "object": "permutation of the N=256 NTT coefficients of the secret, per polynomial",
125 "N": N,
126 "k": K,
127 "dtype": "uint16",
128 "entries": K * 2 * N,
129 "bytes": shuffle_bytes,
130 "mb": round(shuffle_bytes / MB, 3),
131 "self_test_roundtrip": roundtrip,
132 "basis": "measured (pi + pi_inv built and serialized, seed 42)",
133 },
134 "masking_support": {
135 "bytes": masking_bytes,
136 "basis": "runtime three-share; no masked tables stored (whitebox_reference.py three_share)",
137 },
138 "core": {
139 "A_shared_bytes": core_a,
140 "A_shared_mb": round(core_a / MB, 2),
141 "B_baked_bytes": core_b,
142 "B_baked_mb": round(core_b / MB, 2),
143 "source": "concrete_security_bounds.json (base tables + encoding sublayer)",
144 },
145 "deployment_total": {
146 "A_shared_bytes": total_a,
147 "A_shared_mb": round(total_a / MB, 2),
148 "B_baked_bytes": total_b,
149 "B_baked_mb": round(total_b / MB, 2),
150 "note": "core + shuffle + masking(0); the obfuscation layers add a few KB, "
151 "so the deployment footprint equals the measured core to two decimals",
152 },
153 }
154
155 out = results_dir() / "obfuscation_storage.json"
156 out.write_text(json.dumps(summary, indent=2), encoding="utf-8")
157
158 print(
159 "shuffle : %d B = %.3f MB (k=%d x (pi+pi^-1) x N=%d x %dB, roundtrip=%s)"
160 % (shuffle_bytes, shuffle_bytes / MB, K, N, BYTES_PER_ENTRY, roundtrip)
161 )
162 print("masking : %d B (runtime, no stored table)" % masking_bytes)
163 print("core : A %.2f MB / B %.2f MB" % (core_a / MB, core_b / MB))
164 print(
165 "deployment : A %.2f MB / B %.2f MB (core + a few KB)"
166 % (total_a / MB, total_b / MB)
167 )
168 print("written : %s" % out)
169 return 0
170
171
172if __name__ == "__main__":
173 raise SystemExit(main())
build_shuffle(rng)
One coefficient shuffle pi and its inverse, as stored uint16 tables.
read_core()
Read the measured core footprints from concrete_security_bounds.json.
main()
Measure the obfuscation-layer storage and write the summary JSON.
Path results_dir()
Repository results directory.