3@file entry_determinacy.py
4@brief Entry-determinacy dichotomy for the white-box ML-KEM-768 table families:
5measures the entry-determinacy degree d and the minimal table-access budget M* at
6which an access-pattern-oblivious, table-access-bounded adversary attains Z=1.
7@ingroup security_analysis
9@details The entry-determinacy degree d of a table family is the minimum number of
10entries that determine the whole table. Two regimes are separated here by actual
11reconstruction attempts, not by assertion:
12 NEGATIVE (algebraically determined): the budget at which the adversary attains
13 Z=1 is M* = (independent secret scalars) x (bytes per entry),
with no S_tbl
14 term. Construction B bakes h(x) = shat*x mod q, which
is Z_q-linear: one
15 entry at a nonzero index yields shat by a modular inverse, so d=1
and the
16 whole family regenerates
from 2 entries per degree-2 factor (h2
is derived
17 from shat1
and the public gamma_i). Construction A stores the public map
18 M[x][y] = x*y mod q, which carries no secret: d=0
and M*=0.
19 POSITIVE (entry-unpredictable): a random Z_q bijection admits no completion
20 from a proper subset beyond its last entry (d = q-1),
and an AES-128 PRF
21 table admits none at all within the tested attack classes.
22The separator
is NOT key-determinism: the SPACE-style PRF table
is measured here
23to be exactly
as key-determined
as B (rebuilt byte-identically
from the same key)
24yet resists the same attack. The separator
is efficient local invertibility --
25B
's key->table map is linear and inverts from one entry; AES-128's
is a PRF.
26@note MEASURED: every d, M*, regeneration count
and extrapolation rate below
is
27computed
from objects built
in this run (repo builders build_shared_table
and
28build_baked_tables) by running the reconstruction; no expected value
is written
29into an output field. EXPECTED_* constants are prior-work targets used only to
30emit comparison booleans under comparison_to_expected.
31@note The four counter-design footprints reported
in prior work (7.59 MB to
3217.02 GB) are NOT reproduced here; they are arithmetic extrapolations
and are
33recorded under analytic_not_measured so nothing downstream cites them
as measured.
34@note Deterministic (seed 42); writes results/entry_determinacy.json byte-identically.
36@section entry_determinacy_output Output Files
37- `results/entry_determinacy.json` - Entry-determinacy degrees, M* budgets, PRF control
39@section entry_determinacy_usage Usage
41python entry_determinacy.py
46This software
is provided
for academic
and research purposes.
47See LICENSE file
for details.
51from pathlib import Path
53from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes
55from whitebox_reference import (
71EXPECTED_D_BIJECTION = Q - 1
72EXPECTED_M_STAR_BAKED_BYTES = 1536
73EXPECTED_M_STAR_SHARED_BYTES = 0
74EXPECTED_PRF_LINEAR_REGENERATIONS = 0
81REJECTION_BOUND = (1 << 16) // Q * Q
82REJECTION_RETRY_LIMIT = 64
85PRIOR_FOOTPRINT_RANGE_TEXT =
"7.59 MB to 17.02 GB"
90 @brief Multiplicative inverses of 1..q-1 mod q (Fermat; q
is prime).
91 @return int64 array inv[x]
with x*inv[x] == 1 mod q
for x != 0, inv[0] = 0.
93 inv = np.zeros(Q, dtype=np.int64)
95 inv[x] = pow(x, Q - 2, Q)
96 bad = [x
for x
in range(1, Q)
if (x * int(inv[x])) % Q != 1]
99 "Modular inversion failed for indices %s: q=%d is not prime, so the "
100 "linear key->table map is not invertible and the entry-determinacy "
101 "measurement is undefined. Remediation: q must be the ML-KEM prime "
102 "3329; check whitebox_reference.Q." % (bad[:4], Q)
109 @brief Output-encoding sublayer: per factor two secret Z_q bijections plus
110 their inverses (only the two forward maps are independent).
111 @param rng Seeded NumPy generator.
112 @return (E, Einv) uint16 arrays of shape (NUM_COMPONENTS, 2, q).
114 E = np.empty((NUM_COMPONENTS, 2, Q), dtype=np.uint16)
115 Einv = np.empty((NUM_COMPONENTS, 2, Q), dtype=np.uint16)
116 for i
in range(NUM_COMPONENTS):
118 perm = rng.permutation(Q).astype(np.uint16)
120 inv = np.empty(Q, dtype=np.uint16)
121 inv[perm.astype(np.int64)] = np.arange(Q, dtype=np.uint16)
128 @brief SPACE-style control: q-entry table whose entries are AES-128(key, index)
129 truncated into Z_q. Same shape
and dtype
as a Construction-B h-table.
130 @param key 16-byte AES key.
131 @return uint16 array of q entries.
133 if len(key) != AES_BLOCK_BYTES:
135 "AES-128 key is %d bytes, expected %d. The PRF control must use the "
136 "real primitive at the real key length or it is not a SPACE-style "
137 "control. Remediation: draw the key as 16 bytes from the seeded RNG."
138 % (len(key), AES_BLOCK_BYTES)
140 enc = Cipher(algorithms.AES(key), modes.ECB()).encryptor()
148 block = int(x).to_bytes(AES_BLOCK_BYTES - 4,
"big") + int(ctr).to_bytes(
151 word = int.from_bytes((enc.update(block))[:2],
"big")
152 if word < REJECTION_BOUND:
153 vals.append(word % Q)
156 if ctr > REJECTION_RETRY_LIMIT:
158 "Rejection sampling failed to draw a uniform Z_q value for index %d within %d "
159 "retries. Remediation: the control must be unbiased; widen REJECTION_BOUND to a "
160 "multiple of q below 2^16 or draw more PRF output per index."
161 % (x, REJECTION_RETRY_LIMIT)
164 return np.array(vals, dtype=np.uint16)
169 @brief Read one entry at each candidate index, invert the linear model
170 s = T[x0]*x0^-1, regenerate the whole table
and score it. Row s of the
171 shared table M
is exactly the candidate model x -> s*x, so M enumerates
172 every linear hypothesis without recomputing one.
173 @param table q-entry uint16 table under attack.
174 @param M Shared multiply table
from build_shared_table().
175 @param inv Modular inverse array.
176 @return dict
with regeneration count, informative index count
and the
177 extrapolation accuracy (mean/max over read positions).
179 if table.shape != (Q,):
181 "Table under attack has shape %s, expected (%d,). The control must "
182 "match the h-table shape or the comparison is not at identical shape. "
183 "Remediation: build the control with q entries." % (table.shape, Q)
185 t = table.astype(np.int64)
186 idx = np.arange(1, Q, dtype=np.int64)
187 cand = (t[idx] * inv[idx]) % Q
189 agree = pred == table[
None, :]
190 regenerations = int(np.count_nonzero(agree.all(axis=1)))
193 hits = agree.sum(axis=1) - agree[np.arange(idx.size), idx]
194 rate = hits / float(Q - 1)
196 "read_positions_tried": int(idx.size),
197 "linear_regenerations": regenerations,
198 "extrapolation_accuracy_mean": float(rate.mean()),
199 "extrapolation_accuracy_max": float(rate.max()),
205 @brief Entry-determinacy of a Z_q bijection by completion:
with one entry
206 omitted the missing image
is the unique unused value;
with two omitted
207 the completions can be swapped.
208 @param perm q-entry uint16 permutation table.
209 @return (max_omitted_determined, completions_at_one_omitted, completions_at_two_omitted).
211 p = perm.astype(np.int64)
212 if np.unique(p).size != Q:
214 "Permutation table holds %d distinct values, expected %d: it is not a "
215 "Z_q bijection, so the completion argument does not apply. "
216 "Remediation: build encodings with rng.permutation(q)."
217 % (int(np.unique(p).size), Q)
220 def completions(omitted):
221 seen = np.ones(Q, dtype=bool)
222 seen[p[[x
for x
in range(Q)
if x
not in omitted]]] =
False
223 missing = int(np.count_nonzero(seen))
227 for f
in range(1, missing + 1):
231 one = completions({0})
232 two = completions({0, 1})
235 "Omitting one entry of a bijection left %d consistent completions, "
236 "expected a unique one. Remediation: the table is not a bijection; "
237 "check build_encoding_sublayer." % one
239 max_omitted = 1
if one == 1
and two > 1
else 0
240 return max_omitted, one, two
245 @brief Build both constructions plus the encoding sublayer
and the AES-128 PRF
246 control, measure entry-determinacy degrees, M* budgets
and the
247 key-determinism separator,
and write JSON.
249 rng = np.random.default_rng(SEED)
253 shat = [ntt_forward(rng.integers(-2, 3, size=N) % Q) % Q
for _
in range(K)]
254 M = build_shared_table()
255 baked = [build_baked_tables(h)
for h
in shat]
257 aes_key = rng.integers(0, 256, size=AES_BLOCK_BYTES, dtype=np.uint8).tobytes()
260 probe = baked[0][0][0]
261 bytes_per_entry = int(probe.itemsize)
262 table_entries = int(probe.size)
264 if prf.shape != probe.shape
or prf.nbytes != probe.nbytes:
266 "PRF control shape/size %s/%dB differs from the h-table %s/%dB; the "
267 "control must be at identical shape and size or the dichotomy is "
268 "confounded by geometry. Remediation: build the control with q uint16 "
269 "entries." % (prf.shape, prf.nbytes, probe.shape, probe.nbytes)
275 consistent_at_zero_entries = int(np.unique(M, axis=0).shape[0])
276 x0 = int(rng.integers(1, Q))
277 s_probe = (int(probe[x0]) * int(inv[x0])) % Q
278 rebuilt_probe = M[s_probe]
279 b_determined_at_one = bool(np.array_equal(rebuilt_probe, probe))
280 if not b_determined_at_one:
282 "Construction-B h-table did not regenerate from one entry at index %d. "
283 "h(x)=shat*x is Z_q-linear, so this must succeed; a failure means the "
284 "builder no longer bakes a linear map. Remediation: check "
285 "whitebox_reference.build_baked_tables." % x0
291 table_entries - 1
if consistent_at_zero_entries > 1
else table_entries
293 d_baked = table_entries - b_max_omitted
296 a_public_rebuild = build_shared_table()
297 a_determined_at_zero = bool(np.array_equal(a_public_rebuild, M))
298 d_shared = 0
if a_determined_at_zero
else table_entries
299 if not a_determined_at_zero:
301 "Construction-A shared table did not regenerate from public parameters "
302 "alone, contradicting its definition as the public map x*y mod q. "
303 "Remediation: check whitebox_reference.build_shared_table determinism."
309 d_bijection = table_entries - max_omitted_bij
314 prf_distinct = int(np.unique(prf).size)
315 prf_is_bijection = prf_distinct == table_entries
318 if (prf_attack[
"linear_regenerations"] == 0
and not prf_is_bijection)
321 if prf_max_omitted
is None:
323 "PRF control admitted a reconstruction (linear regenerations=%d, "
324 "bijection=%s); the control is not entry-unpredictable and the "
325 "dichotomy cannot be evidenced against it. Remediation: verify the "
326 "AES-128 PRF table build."
327 % (prf_attack[
"linear_regenerations"], prf_is_bijection)
329 d_prf = table_entries - prf_max_omitted
338 for i
in range(NUM_COMPONENTS):
339 h0, h1, h2 = baked[j][i]
340 s0 = (int(h0[x0]) * int(inv[x0])) % Q
342 s1 = (int(h1[x0]) * int(inv[x0])) % Q
347 r0, r1, r2 = M[s0], M[s1], M[(g * s1) % Q]
349 np.array_equal(r0, h0)
350 and np.array_equal(r1, h1)
351 and np.array_equal(r2, h2)
354 "Construction-B family regeneration failed at poly %d component "
355 "%d from %d read entries. Remediation: the baked tables are no "
356 "longer h(x)=shat*x; check build_baked_tables."
357 % (j, i, entries_read)
360 m_star_baked = entries_read * bytes_per_entry
361 m_star_shared = 0 * bytes_per_entry
363 size_baked_family = sum(int(t.nbytes)
for poly
in baked
for tr
in poly
for t
in tr)
364 size_shared = int(M.nbytes)
365 size_encodings = int(E.nbytes) + int(Einv.nbytes)
366 independent_bijections = int(E.shape[0] * E.shape[1])
370 prf_key_determined = bool(np.array_equal(prf_rebuilt, prf))
371 baked_rebuilt = build_baked_tables(shat[0])
372 baked_key_determined = bool(
375 for tr_a, tr_b
in zip(baked_rebuilt, baked[0])
376 for a, b
in zip(tr_a, tr_b)
382 "baked_d_matches_expected": d_baked == EXPECTED_D_BAKED,
383 "shared_d_matches_expected": d_shared == EXPECTED_D_SHARED,
384 "bijection_d_matches_expected": d_bijection == EXPECTED_D_BIJECTION,
385 "baked_M_star_matches_expected": m_star_baked == EXPECTED_M_STAR_BAKED_BYTES,
386 "shared_M_star_matches_expected": m_star_shared == EXPECTED_M_STAR_SHARED_BYTES,
387 "prf_regenerations_match_expected": prf_attack[
"linear_regenerations"]
388 == EXPECTED_PRF_LINEAR_REGENERATIONS,
389 "expected_values_used_for_comparison_only":
True,
391 disagreements = sorted(k
for k, v
in comparisons.items()
if v
is False)
399 "num_components": NUM_COMPONENTS,
400 "component_poly_pairs": K * NUM_COMPONENTS,
401 "bytes_per_entry": bytes_per_entry,
402 "entries_per_h_table": table_entries,
405 "provenance":
"Every field under 'measured' is computed from objects "
406 "built in this run (build_shared_table / build_baked_tables / "
407 "AES-128) by running the reconstruction. No expected value "
408 "is written into any field here.",
409 "entry_determinacy_degree": {
412 "regenerated_from_entries": 1,
414 "candidate_tables_consistent_with_zero_entries": consistent_at_zero_entries,
415 "informative_read_positions": baked_attack[
"read_positions_tried"],
416 "linear_regenerations": baked_attack[
"linear_regenerations"],
417 "extrapolation_accuracy_mean": baked_attack[
418 "extrapolation_accuracy_mean"
420 "how":
"h(x)=shat*x is Z_q-linear: one entry at a nonzero index "
421 "gives shat by a modular inverse; the regenerated table "
422 "was compared byte-identically.",
427 "regenerated_from_entries": 0,
428 "rebuilt_from_public_parameters_byte_identical": a_determined_at_zero,
429 "how":
"M[x][y]=x*y mod q was rebuilt from public parameters "
430 "alone and compared byte-identically to the built table.",
433 "random_zq_bijection": {
435 "max_omitted_entries_still_determined": max_omitted_bij,
436 "consistent_completions_with_one_entry_omitted": comp_one,
437 "consistent_completions_with_two_entries_omitted": comp_two,
438 "linear_regenerations": bij_attack[
"linear_regenerations"],
439 "extrapolation_accuracy_mean": bij_attack[
440 "extrapolation_accuracy_mean"
442 "how":
"Completion counting on a built sublayer permutation: one "
443 "omitted entry has a unique unused image, two omitted are "
447 "prf_control_space_style": {
449 "max_omitted_entries_still_determined": prf_max_omitted,
450 "distinct_values": prf_distinct,
451 "is_bijection": prf_is_bijection,
452 "attack_classes_tested": [
453 "linear inversion s = T[x0]*x0^-1 over " "all q read positions",
454 "bijection completion",
456 "how":
"No tested proper-subset reconstruction succeeded; d is "
457 "reported within the tested attack classes, not as an "
458 "unconditional lower bound.",
462 "minimal_budget_M_star": {
463 "B_baked_per_component": {
464 "M_star_bytes": m_star_baked,
465 "entries_read": entries_read,
466 "independent_secret_scalar_slots": scalar_slots,
467 "tables_regenerated": tables_rebuilt,
468 "family_size_S_tbl_bytes": size_baked_family,
469 "M_star_fraction_of_S_tbl": m_star_baked / float(size_baked_family),
470 "how":
"Read 2 entries per (poly, component) -- h2 is derived from "
471 "shat1 and the public gamma_i and was never read -- then "
472 "regenerated all %d tables byte-identically. M* = "
473 "entries_read x table.itemsize." % tables_rebuilt,
476 "A_shared_full_table": {
477 "M_star_bytes": m_star_shared,
479 "independent_secret_scalar_slots": 0,
480 "family_size_S_tbl_bytes": size_shared,
481 "how":
"The table is a public function of the parameters: zero "
482 "entries are needed, so M* = 0 x table.itemsize.",
486 "prf_control_at_identical_shape_and_size": {
487 "primitive":
"AES-128-ECB (real primitive, %d-bit key)" % AES_KEY_BITS,
488 "entries": int(prf.size),
489 "bytes": int(prf.nbytes),
490 "shape_and_size_match_h_table":
True,
491 "linear_regenerations_over_q_candidates": prf_attack[
492 "linear_regenerations"
494 "read_positions_tried": prf_attack[
"read_positions_tried"],
495 "extrapolation_accuracy_mean": prf_attack[
496 "extrapolation_accuracy_mean"
498 "extrapolation_accuracy_max": prf_attack[
"extrapolation_accuracy_max"],
499 "baked_extrapolation_accuracy_mean": baked_attack[
500 "extrapolation_accuracy_mean"
502 "one_over_q_floor": 1.0 / float(Q),
503 "how":
"The identical attack (read one entry, invert the linear model, "
504 "predict the unread entries) was run on the PRF table and on a "
505 "Construction-B h-table of the same shape, dtype and byte count.",
508 "separator_key_determinism_is_not_the_separator": {
509 "prf_table_rebuilt_from_same_key_byte_identical": prf_key_determined,
510 "baked_table_rebuilt_from_same_secret_byte_identical": baked_key_determined,
511 "both_families_are_key_determined": bool(
512 prf_key_determined
and baked_key_determined
514 "baked_linear_regenerations": baked_attack[
"linear_regenerations"],
515 "prf_linear_regenerations": prf_attack[
"linear_regenerations"],
516 "baked_entries_to_invert_key_locally": 1,
517 "prf_candidates_exhausted_without_success": prf_attack[
518 "read_positions_tried"
520 "conclusion":
"Both table families are a deterministic function of "
521 "their key and both rebuild byte-identically from it, "
522 "yet only B is regenerated by the attack. Key-determinism "
523 "therefore does not separate them; efficient local "
524 "invertibility does -- B's key->table map is Z_q-linear "
525 "and inverts from one entry, AES-128's is a PRF.",
529 "A_shared_table_bytes": size_shared,
530 "B_baked_family_bytes": size_baked_family,
531 "encoding_sublayer_bytes": size_encodings,
532 "encoding_independent_bijections": independent_bijections,
533 "how":
"Summed .nbytes of the arrays built in this run.",
537 "analytic_not_measured": {
538 "provenance":
"Values here are arithmetic or asymptotic. They are NOT "
539 "measurements from this run and must not be cited as measured.",
540 "prior_work_counter_design_footprint_range": {
541 "value": PRIOR_FOOTPRINT_RANGE_TEXT,
542 "reproduced_here":
False,
543 "basis":
"analytic (arithmetic extrapolation reported in prior work; "
544 "the four counter-design families are not built or measured by "
545 "this script). Nothing downstream may cite this range as measured.",
547 "M_star_independent_of_S_tbl": {
548 "claim":
"M* = (independent secret scalars) x (bytes per entry) "
549 "contains no S_tbl term, so the Z=1 budget does not grow with "
551 "basis":
"analytic (the measured M_star_fraction_of_S_tbl above is "
552 "consistent with it at this single parameter set; one point "
553 "does not by itself establish independence).",
556 "claim":
"For an entry-unpredictable family against an access-pattern-"
557 "oblivious, table-access-bounded adversary with M < S_tbl/2 and "
558 "L lookups uniform over random ciphertexts, Z <= (1/2)^L.",
559 "basis":
"analytic (theorem statement; not evaluated numerically here).",
561 "prf_key_recovery_effort": {
562 "claim":
"Recovering the AES-128 key from the PRF table has no local "
563 "algebraic route; exhaustive search is 2^%d." % AES_KEY_BITS,
564 "basis":
"analytic (the measured quantity is the count of linear "
565 "candidates exhausted without success, reported above).",
568 "comparison_to_expected": comparisons,
569 "disagreements_with_expected": disagreements,
571 "wallclock_fields_emitted": 0,
572 "machine_dependent_fields": [],
573 "note":
"Seeded (seed %d); no wall-clock field is emitted, so the JSON is "
574 "byte-identical run-to-run." % SEED,
576 "note":
"Reference NumPy measurement on the simulation host. The dichotomy is "
577 "evidenced by running reconstructions against tables built by the "
578 "repo's own builders; the deployed footprint and latency remain "
579 "analytical projections.",
582 results_dir = Path(__file__).parent.parent.parent /
"results"
583 results_dir.mkdir(exist_ok=
True)
585 results_dir /
"entry_determinacy.json",
"w", encoding=
"utf-8", newline=
"\n"
587 json.dump(out, f, indent=2)
590 "ENTRY-DETERMINACY DICHOTOMY (q=%d, n=%d, k=%d, %d components)"
591 % (Q, N, K, NUM_COMPONENTS)
594 print(
"NEGATIVE (algebraically determined)")
596 " B baked h(x)=shat*x : d=%d M*=%d B (%d entries x %d B), regenerated %d/%d tables"
607 " M*/S_tbl = %d/%d = %.3e"
608 % (m_star_baked, size_baked_family, m_star_baked / float(size_baked_family))
611 " A shared M[x][y]=x*y: d=%d M*=%d B (public map, rebuilt byte-identically)"
612 % (d_shared, m_star_shared)
614 print(
"POSITIVE (entry-unpredictable)")
616 " random Z_q bijection: d=%d (1 omitted -> %d completion, 2 omitted -> %d)"
617 % (d_bijection, comp_one, comp_two)
619 print(
" AES-128 PRF control : d=%d (within tested attack classes)" % d_prf)
622 "PRF CONTROL at identical shape/size (%d entries, %d B):"
623 % (prf.size, prf.nbytes)
626 " linear regenerations over %d candidates : %d (B: %d)"
628 prf_attack[
"read_positions_tried"],
629 prf_attack[
"linear_regenerations"],
630 baked_attack[
"linear_regenerations"],
634 " extrapolation mean : %.4e (max %.4e) vs B %.4f | 1/q floor = %.4e"
636 prf_attack[
"extrapolation_accuracy_mean"],
637 prf_attack[
"extrapolation_accuracy_max"],
638 baked_attack[
"extrapolation_accuracy_mean"],
643 "SEPARATOR: PRF key-determined=%s, B key-determined=%s -> key-determinism is"
644 % (prf_key_determined, baked_key_determined)
647 " NOT the separator; efficient local invertibility is (B: 1 entry; PRF: %d"
648 % prf_attack[
"read_positions_tried"]
651 " linear candidates exhausted, %d hits)." % prf_attack[
"linear_regenerations"]
655 "Prior-work counter-design footprint range %s: NOT reproduced (analytic)."
656 % PRIOR_FOOTPRINT_RANGE_TEXT
659 print(
"DISAGREEMENTS WITH EXPECTED: %s" %
", ".join(disagreements))
661 print(
"All measured values agree with prior-work expected targets.")
662 print(
"Wrote %s" % (results_dir /
"entry_determinacy.json"))
665if __name__ ==
"__main__":
modular_inverses()
Multiplicative inverses of 1..q-1 mod q (Fermat; q is prime).
build_prf_table(key)
SPACE-style control: q-entry table whose entries are AES-128(key, index) truncated into Z_q.
bijection_determinacy(perm)
Entry-determinacy of a Z_q bijection by completion: with one entry omitted the missing image is the u...
linear_attack(table, M, inv)
Read one entry at each candidate index, invert the linear model s = T[x0]*x0^-1, regenerate the whole...
build_encoding_sublayer(rng)
Output-encoding sublayer: per factor two secret Z_q bijections plus their inverses (only the two forw...
main()
Build both constructions plus the encoding sublayer and the AES-128 PRF control, measure entry-determ...