3@file table_extraction_witness.py
4@brief Entry-determinacy witness: recover the whole Construction-B baked table set
5from its minimum determining entries, and measure Construction A's zero-read
6secret exposure, using this repository's own table builder.
9@details The entry-determinacy degree d of a table family is the minimum number of
10entries that determine the whole table. Construction B bakes h(x) = shat*x mod q,
11which is Z_q-linear, so d = 1: the entry at the unit index is the scalar itself and
12every other entry is a public multiple of it. The budget at which a table-access-
13bounded adversary attains advantage 1 is therefore M* = (independent secret
14scalars) x (bytes per entry), independent of the stored size S_tbl. This script
15witnesses that claim end to end: it reads the determining entries out of tables
16built by build_baked_tables(), regenerates the full set, checks bit-exactness over
17all 384 (component, polynomial) pairs and several seeds, and measures the success
18rate Z of the regenerated tables against base_mul_direct on fresh ciphertexts.
19Construction A is measured on the other side of the dichotomy: build_shared_table()
20takes no secret argument (d = 0, a public function), so the secret is never in the
21table and the extractor needs zero table reads -- it is the plain `sh` argument of
23@note The separator is not key-determinism (a PRF-derived table family is also a
24deterministic function of its key) but efficient local invertibility: B's
25scalar-to-table map is linear and inverts from one entry.
26@note Every numeric field is derived from objects built in this run: footprints come
27from ndarray .nbytes / .itemsize, read volume from the entries actually fetched, and
28Z from executed trials. Prior expectations appear only as booleans under
29`expected_targets`, never as emitted quantities.
31@section table_extraction_witness_output Output Files
32- `results/table_extraction_witness.json` - Entry-determinacy witness, regeneration and Z
34@section table_extraction_witness_usage Usage
36python table_extraction_witness.py
41This software is provided for academic and research purposes.
42See LICENSE file for details.
50from whitebox_reference
import (
65SEEDS = (42, 1337, 20250714, 7, 99)
67ENC_TABLES_PER_FACTOR = 4
68ENC_INDEPENDENT_PER_FACTOR = 2
73 @brief ML-KEM-768 secret: K polys, coefficients uniform over {-2..2} (the CBD support; the extraction budget
is distribution-independent),
in the NTT domain.
74 @param seed Deterministic seed.
75 @return List of K full-range NTT-domain secret polynomials.
77 rng = np.random.default_rng(seed)
78 return [ntt_forward(rng.integers(-2, 3, size=N) % Q) % Q
for _
in range(K)]
83 @brief Array proxy that charges every indexed entry to a read budget.
88 @brief Wrap one table.
89 @param arr uint16 table array.
103 @brief Baked-table view that counts every entry fetched by the extractor.
104 @details The read budget must be measured,
not asserted, so the extractor may
105 only touch tables through this wrapper.
110 @brief Wrap a built table set.
111 @param tabs List of (h0, h1, h2) uint16 triples
from build_baked_tables.
117 def read(self, comp, table_idx, x):
119 @brief Fetch one entry
and charge it to the budget.
120 @param comp Component index;
@param table_idx 0=h0, 1=h1, 2=h2;
@param x Entry index.
121 @return Entry value
as int.
123 tab = self._tabs[comp][table_idx]
131 @brief Serialized footprint of one polynomial
's baked table set.
132 @param tabs List of (h0, h1, h2) uint16 triples.
133 @return Total bytes
from the built arrays
' .nbytes.
135 return sum(int(t.nbytes)
for triple
in tabs
for t
in triple)
140 @brief Output-encoding sublayer: per factor two random Z_q bijections plus their
141 two derived inverses.
142 @param seed Deterministic seed.
143 @return (tables, independent_bijections)
with tables a list of uint16 arrays.
145 rng = np.random.default_rng(seed)
146 tables, independent = [], 0
147 for _
in range(NUM_COMPONENTS):
148 for _
in range(ENC_INDEPENDENT_PER_FACTOR):
149 perm = rng.permutation(Q).astype(np.uint16)
150 inv = np.zeros(Q, dtype=np.uint16)
151 inv[perm.astype(np.int64)] = np.arange(Q, dtype=np.uint16)
152 if not np.array_equal(
153 inv[perm.astype(np.int64)], np.arange(Q, dtype=np.uint16)
156 "encoding table is not a bijection; remediation: sample the "
157 "encoding with rng.permutation(Q) so every residue occurs once"
159 tables.extend((perm, inv))
161 if len(tables) != NUM_COMPONENTS * ENC_TABLES_PER_FACTOR:
163 "encoding sublayer table count mismatch; remediation: emit exactly two "
164 "encodings and two inverses per degree-2 factor"
166 return tables, independent
171 @brief Read the determining entries of each baked table
and rebuild the full set.
172 @details h(x) = shat*x
is Z_q-linear, so the entry at the unit index
is the
173 baked scalar; h2 needs no extra read because gamma_i
is public.
174 @param view ReadCountingTables over the target table set.
175 @param gammas Public component twiddles.
176 @return List of regenerated (h0, h1, h2) uint16 triples.
178 x = np.arange(Q, dtype=np.int64)
180 for i
in range(NUM_COMPONENTS):
181 s0 = view.read(i, 0, 1)
182 s1 = view.read(i, 1, 1)
186 ((s0 * x) % Q).astype(np.uint16),
187 ((s1 * x) % Q).astype(np.uint16),
188 ((g * s1 * x) % Q).astype(np.uint16),
196 @brief Measure Construction B
's entry-determinacy degree d instead of asserting it.
197 @details Sufficiency: one charged read per baked table regenerates it bit-exactly.
198 Minimality: two distinct secrets
yield different tables, so zero entries cannot
199 determine the family
and d > 0. The two results pin d exactly.
200 @param seed_a First secret seed;
@param seed_b Independent secret seed.
201 @return (d, reads_per_table, one_read_sufficient, zero_reads_insufficient).
204 tabs_a, tabs_b = build_baked_tables(sh_a), build_baked_tables(sh_b)
205 zero_insufficient = any(
206 tabs_a[i][t].tobytes() != tabs_b[i][t].tobytes()
207 for i
in range(NUM_COMPONENTS)
210 x = np.arange(Q, dtype=np.int64)
212 s0 = view.read(0, 0, 1)
213 one_sufficient = ((s0 * x) % Q).astype(np.uint16).tobytes() == tabs_a[0][
216 if not one_sufficient:
218 "one entry does not determine a baked table; remediation: do not emit a "
219 "determinacy degree -- the Z_q-linearity premise h(x)=shat*x has failed"
221 if not zero_insufficient:
223 "baked tables do not vary with the secret; remediation: the family would be "
224 "secret-independent and this witness would be measuring the wrong claim"
231 bool(one_sufficient),
232 bool(zero_insufficient),
238 @brief Bit-exact comparison of two baked table sets.
239 @param a First table set;
@param b Second table set.
240 @return (all_equal, pairs_compared, pairs_exact).
243 for ta, tb
in zip(a, b):
245 if all(x.tobytes() == y.tobytes()
for x, y
in zip(ta, tb)):
247 return exact == pairs, pairs, exact
252 @brief Check that every nonzero index recovers the baked scalar: s0 = h0[x]*x^-1.
253 @param tabs Baked tables
for one polynomial;
@param sh The polynomial
's secret.
254 @return (indices_tested_per_table, indices_inverted_per_table_min, total_inverted).
256 x = np.arange(1, Q, dtype=np.int64)
258 [pow(int(v), Q - 2, Q) for v
in x], dtype=np.int64
260 per_table_min, total =
None, 0
261 for i
in range(NUM_COMPONENTS):
262 h0 = tabs[i][0].astype(np.int64)
263 rec = (h0[x] * xinv) % Q
264 hits = int(np.count_nonzero(rec == int(sh[2 * i])))
266 per_table_min = hits
if per_table_min
is None else min(per_table_min, hits)
267 return int(x.size), int(per_table_min), int(total)
272 @brief Run the entry-determinacy witness on both constructions
and write JSON.
275 per_seed, base_bytes_seen, read_bytes_seen = [], set(), set()
279 entries_read = bytes_read = 0
280 pairs_total = pairs_exact = 0
283 tabs = build_baked_tables(shat[j])
291 entries_read += view.entries_read
292 bytes_read += view.bytes_read
293 if pairs_total != K * NUM_COMPONENTS:
295 "(component, polynomial) pair count is %d, expected k*NUM_COMPONENTS; "
296 "remediation: build tables for every one of the K secret polynomials"
301 "regenerated tables are not bit-exact for seed %d; remediation: the "
302 "witness must not be reported as passing -- investigate the linearity "
303 "assumption h(x)=shat*x before touching the JSON" % seed
305 base_bytes_seen.add(stored)
306 read_bytes_seen.add(bytes_read)
310 "pairs_checked": pairs_total,
311 "pairs_bit_exact": pairs_exact,
312 "bit_exact": bool(all_ok),
313 "entries_read": entries_read,
314 "bytes_read": bytes_read,
315 "stored_bytes_base": stored,
318 if len(base_bytes_seen) != 1
or len(read_bytes_seen) != 1:
320 "footprint or read volume varies across seeds; remediation: both are "
321 "structural and must be seed-invariant -- inspect the builder"
323 s_tbl_base = base_bytes_seen.pop()
324 bytes_read = read_bytes_seen.pop()
328 s_enc = sum(int(t.nbytes)
for t
in enc_tables)
329 s_tbl_core = s_tbl_base + s_enc
339 core_bytes_read += core_view.bytes_read
340 enc_reads = sum(p.reads
for p
in enc_probes)
341 enc_bytes_read = sum(p.bytes_read
for p
in enc_probes)
342 core_bytes_read += enc_bytes_read
343 m_star_invariant_measured = (core_bytes_read == bytes_read)
and (
344 s_tbl_core != s_tbl_base
348 rng = np.random.default_rng(SEED)
350 baked = [build_baked_tables(shat[j])
for j
in range(K)]
355 for _
in range(Z_TRIALS):
356 j = int(rng.integers(0, K))
357 i = int(rng.integers(0, NUM_COMPONENTS))
358 uh = rng.integers(0, Q, size=N)
359 if base_mul_baked(regen[j], uh, i) == base_mul_direct(shat[j], uh, i):
361 z_measured = successes / Z_TRIALS
364 d_b_measured, d_b_reads, d_b_one_suff, d_b_zero_insuff = (
372 frac_base_pct = 100.0 * bytes_read / s_tbl_base
373 frac_core_pct = 100.0 * bytes_read / s_tbl_core
374 ratio_base = s_tbl_base / bytes_read
377 sig_shared = inspect.signature(build_shared_table)
378 shared_params = list(sig_shared.parameters)
381 "build_shared_table takes parameters %r; remediation: Construction A is "
382 "only secret-independent if the builder receives no secret" % shared_params
384 m_a = build_shared_table()
386 m_b = build_shared_table()
387 digest_a = hashlib.sha256(m_a.tobytes()).hexdigest()
388 digest_b = hashlib.sha256(m_b.tobytes()).hexdigest()
389 if digest_a != digest_b:
391 "shared table differs across builds; remediation: build_shared_table must "
392 "be a pure public function of q"
394 a_secret_independent = digest_a == digest_b
395 s_tbl_a = int(m_a.nbytes)
399 class CountingShared:
401 @brief Shared-table view counting every M lookup made
while recovering sh.
404 def __init__(self, m):
408 def __getitem__(self, key):
414 rebuild_probe = CountingShared(m_a)
415 d_a_measured = rebuild_probe.reads
416 a_zero_reads_sufficient = (
417 hashlib.sha256(build_shared_table().tobytes()).hexdigest() == digest_a
418 and rebuild_probe.reads == 0
420 if not a_zero_reads_sufficient:
422 "shared table is not reproducible from public parameters at zero reads; "
423 "remediation: re-derive Construction A's determinacy degree before emitting it"
426 counting_m = CountingShared(m_a)
428 np.array(p, dtype=np.int64)
for p
in shat
430 a_reads_to_recover = counting_m.reads
431 a_recovery_exact = all(
432 recovered_sh[j].tobytes() == shat[j].astype(np.int64).tobytes()
435 if not a_recovery_exact:
437 "Construction A secret recovery is not exact; remediation: sh is passed in "
438 "the clear to base_mul_shared -- verify the argument plumbing"
441 uh_chk = rng.integers(0, Q, size=N)
442 if base_mul_shared(counting_m, shat[0], uh_chk, 0) != base_mul_direct(
446 "shared-table base multiply disagrees with the reference; remediation: do "
447 "not report Construction A numbers until the builder is fixed"
449 a_lookups_per_basemul = counting_m.reads - a_reads_to_recover
450 alt_digest = hashlib.sha256(build_shared_table().tobytes()).hexdigest()
451 a_independent_of_alt_secret = (
452 alt_digest == digest_a
and sh_alt[0].tobytes() != shat[0].tobytes()
457 scalars_independent = K * NUM_COMPONENTS * 2
458 bytes_per_entry = int(baked[0][0][0].itemsize)
459 m_star_b_analytic = scalars_independent * bytes_per_entry
460 m_star_a_analytic = 0 * bytes_per_entry
464 "seeds": list(SEEDS),
469 "num_components": NUM_COMPONENTS,
470 "component_poly_pairs": K * NUM_COMPONENTS,
471 "bytes_per_entry_measured": bytes_per_entry,
474 "construction_B_baked": {
475 "entry_determinacy_degree_measured": d_b_measured,
476 "entry_determinacy_evidence": {
477 "reads_charged_for_one_table": d_b_reads,
478 "one_entry_regenerates_table_bit_exactly": d_b_one_suff,
479 "zero_entries_insufficient_tables_vary_with_secret": d_b_zero_insuff,
481 "entries_read": per_seed[0][
"entries_read"],
482 "bytes_read": bytes_read,
483 "S_tbl_base_bytes": s_tbl_base,
484 "S_tbl_base_MB": round(s_tbl_base / 1e6, 2),
485 "S_encoding_sublayer_bytes": s_enc,
486 "encoding_tables_built": len(enc_tables),
487 "encoding_independent_bijections": enc_independent,
488 "S_tbl_core_bytes": s_tbl_core,
489 "S_tbl_core_MB": round(s_tbl_core / 1e6, 2),
490 "compression_ratio_base": round(ratio_base, 1),
491 "regeneration_bit_exact_all_seeds": all(
492 p[
"bit_exact"]
for p
in per_seed
494 "per_seed": per_seed,
495 "Z_trials": Z_TRIALS,
496 "Z_successes": successes,
497 "Z_measured": z_measured,
499 "indices_tested_per_table": idx_tested,
500 "indices_inverted_per_table_min": idx_min,
501 "indices_inverted_total": idx_total,
502 "tables_swept": NUM_COMPONENTS,
504 "withdrawal_basis_fraction": {
505 "note":
"Fraction of the stored tables the adversary must exfiltrate; "
506 "base and core denominators are reported separately and must "
508 "denominator_base_bytes": s_tbl_base,
509 "denominator_base_meaning":
"baked h0/h1/h2 tables only (no encodings)",
510 "fraction_of_base_percent": round(frac_base_pct, 6),
511 "denominator_core_bytes": s_tbl_core,
512 "denominator_core_meaning":
"baked tables plus the output-encoding sublayer",
513 "fraction_of_core_percent": round(frac_core_pct, 6),
515 "M_star_invariance_two_point": {
516 "note":
"Scalar count held fixed while the stored set is enlarged by "
517 "the encoding sublayer; the read budget is re-measured.",
518 "point_1_S_tbl_bytes": s_tbl_base,
519 "point_1_bytes_read": bytes_read,
520 "point_2_S_tbl_bytes": s_tbl_core,
521 "point_2_bytes_read": core_bytes_read,
522 "encoding_entry_reads_charged": enc_reads,
523 "encoding_bytes_read": enc_bytes_read,
524 "budget_unchanged_while_S_tbl_grew": bool(
525 m_star_invariant_measured
528 "basis":
"measured (tables built by whitebox_reference.build_baked_tables; "
529 "sizes from ndarray .nbytes; reads charged per fetched entry)",
531 "construction_A_shared": {
532 "entry_determinacy_degree_measured": d_a_measured,
533 "entry_determinacy_evidence": {
534 "zero_reads_reproduce_table_byte_identically": bool(
535 a_zero_reads_sufficient
537 "public_function_of_q_only":
not shared_params,
539 "builder_parameters": shared_params,
540 "takes_no_secret_argument":
not shared_params,
541 "S_tbl_A_bytes": s_tbl_a,
542 "S_tbl_A_MB": round(s_tbl_a / 1e6, 2),
543 "sha256_build_1": digest_a,
544 "sha256_build_2": digest_b,
545 "secret_independent_byte_identical": bool(a_secret_independent),
546 "byte_identical_across_independent_secrets": bool(
547 a_independent_of_alt_secret
549 "table_reads_to_recover_secret": a_reads_to_recover,
550 "secret_recovery_bit_exact": bool(a_recovery_exact),
551 "shared_lookups_per_base_multiply": a_lookups_per_basemul,
552 "basis":
"measured (table built by whitebox_reference.build_shared_table; "
553 "reads counted through a wrapping proxy)",
557 "note":
"Derived from named parameters and the measured entry width; not a "
558 "run measurement. M* is the budget at which the table-access-bounded "
559 "adversary attains Z=1.",
560 "independent_secret_scalars_B": scalars_independent,
561 "M_star_B_bytes": m_star_b_analytic,
562 "M_star_A_bytes": m_star_a_analytic,
563 "positive_branch_bound":
"Z <= (1/2 + 1/(2q))^L < 1.04 * (1/2)^L for an entry-"
564 "unpredictable family against an access-pattern-oblivious, "
565 "table-access-bounded adversary with M < S_tbl/2.",
566 "why_not_the_bare_half_pow_L":
"per lookup the adversary wins if the entry is retained "
567 "(probability f) or if it guesses an omitted one "
568 "(probability (1-f)/q); at f just below 1/2 the sum "
569 "f + (1-f)/q exceeds 1/2, so the bare (1/2)^L is false "
570 "even for an entry-unpredictable family",
571 "separator":
"efficient local invertibility (B's scalar-to-table map is "
572 "Z_q-linear and inverts from one entry), not key-determinism",
574 "expected_targets": {
575 "note":
"Prior-round expectations, compared against this run's measured "
576 "values. Booleans only; no expectation is emitted as a quantity.",
577 "bytes_read_1536": bytes_read == 1536,
578 "S_tbl_base_7670016": s_tbl_base == 7670016,
579 "ratio_base_4993_5": abs(ratio_base - 4993.5) < 0.05,
580 "Z_equals_1": z_measured == 1.0,
581 "indices_inverted_3328_of_3328": idx_min == 3328
and idx_tested == 3328,
582 "A_secret_independent": bool(a_secret_independent),
583 "A_bytes_22164482": s_tbl_a == 22164482,
584 "M_star_B_matches_measured_read": m_star_b_analytic == bytes_read,
588 "machine_dependent_fields": [],
589 "note":
"No wall-clock quantity is emitted; the JSON is byte-identical "
594 script_dir = os.path.dirname(os.path.abspath(__file__))
595 results_dir = os.path.join(os.path.dirname(os.path.dirname(script_dir)),
"results")
596 os.makedirs(results_dir, exist_ok=
True)
597 path = os.path.join(results_dir,
"table_extraction_witness.json")
598 with open(path,
"w", encoding=
"utf-8", newline=
"\n")
as f:
599 json.dump(out, f, indent=2)
601 b = out[
"measured"][
"construction_B_baked"]
602 a = out[
"measured"][
"construction_A_shared"]
605 "B entries read : %d over %d (component,poly) pairs, %d seeds"
606 % (b[
"entries_read"], out[
"parameters"][
"component_poly_pairs"], len(SEEDS))
609 "B bytes read : %d B (analytic M* = %d B)"
610 % (b[
"bytes_read"], out[
"analytic"][
"M_star_B_bytes"])
613 "B S_tbl base / core : %d B (%.2f MB) / %d B (%.2f MB)"
615 b[
"S_tbl_base_bytes"],
617 b[
"S_tbl_core_bytes"],
621 print(
"B compression ratio : %.1fx" % b[
"compression_ratio_base"])
623 "B regeneration : bit-exact on all seeds = %s"
624 % b[
"regeneration_bit_exact_all_seeds"]
627 "B Z (fresh cts) : %d/%d = %.4f"
628 % (b[
"Z_successes"], b[
"Z_trials"], b[
"Z_measured"])
631 "B invertibility : %d/%d nonzero indices per table (min over %d tables)"
633 b[
"invertibility"][
"indices_inverted_per_table_min"],
634 b[
"invertibility"][
"indices_tested_per_table"],
635 b[
"invertibility"][
"tables_swept"],
639 "B withdrawal basis : %.4f%% of base, %.4f%% of core"
641 b[
"withdrawal_basis_fraction"][
"fraction_of_base_percent"],
642 b[
"withdrawal_basis_fraction"][
"fraction_of_core_percent"],
646 "A builder params : %r -> takes no secret argument = %s"
647 % (a[
"builder_parameters"], a[
"takes_no_secret_argument"])
650 "A table : %d B (%.2f MB), secret-independent = %s"
651 % (a[
"S_tbl_A_bytes"], a[
"S_tbl_A_MB"], a[
"secret_independent_byte_identical"])
654 "A reads to recover : %d (secret is the plain sh argument)"
655 % a[
"table_reads_to_recover_secret"]
658 "expected_targets : %s"
659 % {k: v
for k, v
in out[
"expected_targets"].items()
if k !=
"note"}
663if __name__ ==
"__main__":