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.
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
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.
24@section obfuscation_storage_usage Usage
26python obfuscation_storage.py
32This software
is provided
for academic
and research purposes.
33See LICENSE file
for details.
37from pathlib import Path
49 """@brief Repository results directory."""
50 return Path(__file__).resolve().parent.parent.parent /
"results"
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.
59 pi = np.empty((K, N), dtype=np.uint16)
60 pi_inv = np.empty((K, N), dtype=np.uint16)
62 perm = rng.permutation(N).astype(np.uint16)
64 inv = np.empty(N, dtype=np.uint16)
65 inv[perm.astype(np.int64)] = np.arange(N, dtype=np.uint16)
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.
77 path = results_dir() / "concrete_security_bounds.json"
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."
84 d = json.loads(path.read_text(encoding=
"utf-8"))
85 bounds = d[
"security_bounds"]
87 int(bounds[
"core_footprint_A_shared"][
"table_size_bytes"]),
88 int(bounds[
"core_footprint_B_baked"][
"table_size_bytes"]),
94 @brief Measure the obfuscation-layer storage
and write the summary JSON.
97 rng = np.random.default_rng(SEED)
101 np.array_equal(pi_inv[p][pi[p].astype(np.int64)], np.arange(N))
106 "Shuffle inverse does not round-trip; refusing to "
107 "report a size for a shuffle that is not a permutation."
110 shuffle_bytes = int(pi.nbytes + pi_inv.nbytes)
111 if shuffle_bytes != K * 2 * N * BYTES_PER_ENTRY:
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})."
119 total_a = core_a + shuffle_bytes + masking_bytes
120 total_b = core_b + shuffle_bytes + masking_bytes
124 "object":
"permutation of the N=256 NTT coefficients of the secret, per polynomial",
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)",
135 "bytes": masking_bytes,
136 "basis":
"runtime three-share; no masked tables stored (whitebox_reference.py three_share)",
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)",
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",
156 out.write_text(json.dumps(summary, indent=2), encoding=
"utf-8")
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)
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))
165 "deployment : A %.2f MB / B %.2f MB (core + a few KB)"
166 % (total_a / MB, total_b / MB)
168 print(
"written : %s" % out)
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.