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
run_all.py
Go to the documentation of this file.
1#!/usr/bin/env python3
2# -*- coding: utf-8 -*-
3"""
4@file run_all.py
5@brief Runs all PQ-WB-KEM experiments in sequence for reproducibility.
6@ingroup orchestration
7
8@section run_all_output Output Files
9- `results/experiment_summary.json` - Aggregate run manifest listing every experiment,
10 its output JSON, and its pass/fail status.
11
12@section run_all_usage Usage
13@code{.sh}
14python run_all.py
15@endcode
16
17@note A missing experiment script is a hard error, not a silent skip: the manifest and
18exit code report exactly which producers ran. Deterministic (seeded) experiments
19regenerate byte-identical outputs; wall-clock and native-benchmark experiments are
20machine-dependent and flagged as such. If liboqs-python is absent, the native
21ML-KEM-768 baseline is recorded as an explicit skip (a host prerequisite, not a
22deterministic experiment) so the seeded experiments still report success; running
23baseline_benchmark.py on its own still exits non-zero.
24
25@author Ugur Coruh
26
27@copyright
28This software is provided for academic and research purposes.
29See LICENSE file for details.
30"""
31
32import os
33import sys
34import json
35import subprocess
36from datetime import datetime
37from pathlib import Path
38
39
40def get_project_root() -> Path:
41 """
42 @brief Return the project root directory.
43 @return Path to the repository root.
44 """
45 return Path(__file__).parent.parent.parent
46
47
48# The wall-clock producer names its output per platform; take the name from it
49# rather than repeating the platform test here, where it would drift.
50sys.path.insert(0, str(Path(__file__).parent))
51from wallclock_ci import detect_env # noqa: E402
52
53WALLCLOCK_OUTPUT = f"wallclock_statistics_{detect_env()}.json"
54
55
56# Experiment manifest: (script, output JSON, description, machine_dependent).
57# Order respects data dependencies -- concrete_security_bounds consumes the DCA,
58# reference-table and encoding outputs, so those run first.
59EXPERIMENTS = [
60 (
61 "baseline_benchmark.py",
62 "baseline_benchmark.json",
63 "ML-KEM-768 reference baseline (liboqs)",
64 True,
65 ),
66 (
67 "whitebox_reference.py",
68 "whitebox_reference.json",
69 "Base-multiply table footprints + NTT correctness",
70 True,
71 ),
72 (
73 "whitebox_encoded.py",
74 "whitebox_encoded.json",
75 "Encoding sublayer + encoding-unaware recovery",
76 False,
77 ),
78 (
79 "share_statistics.py",
80 "share_statistics.json",
81 "Three-share masking uniformity (chi-square)",
82 False,
83 ),
84 (
85 "dca_simulation.py",
86 "dca_simulation.json",
87 "Differential computation analysis resistance",
88 False,
89 ),
90 (
91 "algebraic_attack_analysis.py",
92 "algebraic_attack_analysis.json",
93 "Algebraic attack + full ML-KEM-768 module recovery",
94 True,
95 ),
96 (
97 "overhead_calculation.py",
98 "overhead_calculation.json",
99 "White-box vs reference overhead projection",
100 True,
101 ),
102 (
103 "scaling_analysis.py",
104 "scaling_analysis.json",
105 "ML-KEM-512/768/1024 scaling projections",
106 False,
107 ),
108 (
109 "entry_determinacy.py",
110 "entry_determinacy.json",
111 "Entry-determinacy dichotomy (d, M*, PRF control)",
112 False,
113 ),
114 (
115 "table_extraction_witness.py",
116 "table_extraction_witness.json",
117 "Extraction witness on the repo's own builders",
118 False,
119 ),
120 (
121 "encoding_layer_entropy.py",
122 "encoding_layer_entropy.json",
123 "Encoding sublayer: storage vs entropy",
124 False,
125 ),
126 (
127 "concrete_security_bounds.py",
128 "concrete_security_bounds.json",
129 "DCA estimate plus the core byte-read footprint",
130 False,
131 ),
132 (
133 "obfuscation_storage.py",
134 "obfuscation_storage.json",
135 "Shuffle + masking storage; deployment total = core + KB",
136 False,
137 ),
138 (
139 "wallclock_ci.py",
140 WALLCLOCK_OUTPUT,
141 "Wall-clock overhead mean +/- CI (per environment)",
142 True,
143 ),
144]
145
146# baseline_benchmark.py exits with this code when liboqs-python is not installed.
147# run_all treats it as an explicit, machine-dependent skip (the native baseline is a
148# host prerequisite, not one of the deterministic experiments); a standalone run of
149# baseline_benchmark.py still exits non-zero. Kept in sync with that script's constant.
150LIBOQS_MISSING_EXIT_CODE = 3
151
152
153def run_python_script(script_path: str, description: str) -> int:
154 """
155 @brief Run a Python script as a subprocess.
156 @param script_path Path to the script to execute.
157 @param description Human-readable label for logging.
158 @return The subprocess exit code (0 on success).
159 """
160 print(f"\n{'='*70}")
161 print(f"RUNNING: {description}")
162 print(f"Script: {os.path.basename(script_path)}")
163 print(f"{'='*70}\n")
164 result = subprocess.run([sys.executable, script_path], cwd=get_project_root())
165 label = "SUCCESS" if result.returncode == 0 else f"EXIT {result.returncode}"
166 print(f"\n[{label}] {description}")
167 return result.returncode
168
169
170def main():
171 """
172 @brief Run every experiment and write the JSON summary.
173 @return 0 if all experiments passed, 1 otherwise.
174 """
175 project_root = get_project_root()
176 results_dir = project_root / "results"
177 code_dir = project_root / "code" / "python"
178 results_dir.mkdir(exist_ok=True)
179
180 print("=" * 70)
181 print("PQ-WB-KEM: Reproducible Experiments (White-Box ML-KEM-768)")
182 print("Paper: MDPI Mathematics")
183 print("=" * 70)
184 print(f"Project root: {project_root}")
185 print(f"Started: {datetime.now()}")
186
187 summary = {
188 "project": "PQ-WB-KEM",
189 "paper": "MDPI Mathematics",
190 "experiments": [],
191 }
192
193 all_success = True
194 for script, output, description, machine_dependent in EXPERIMENTS:
195 script_path = code_dir / script
196 if not script_path.exists():
197 raise FileNotFoundError(
198 f"Experiment producer missing: {script_path}. run_all.py does not "
199 f"silently skip experiments; every cited result must have a committed "
200 f"producer. Restore {script} or remove it from EXPERIMENTS."
201 )
202 returncode = run_python_script(str(script_path), description)
203
204 if script == "baseline_benchmark.py" and returncode == LIBOQS_MISSING_EXIT_CODE:
205 # liboqs-python is absent: the native ML-KEM-768 baseline is a host
206 # prerequisite, not one of the deterministic (seeded) experiments.
207 # Record an explicit skip -- no fabricated timings -- and let the seeded
208 # experiments still report overall success. A standalone run of
209 # baseline_benchmark.py still exits non-zero.
210 print(
211 f"\n[SKIPPED] {description}: liboqs-python not installed; native "
212 f"baseline omitted (deterministic experiments unaffected)."
213 )
214 summary["experiments"].append(
215 {
216 "name": description,
217 "script": script,
218 "output": output,
219 "machine_dependent": machine_dependent,
220 "success": None,
221 "status": "skipped",
222 "skip_reason": "liboqs-python not installed; native ML-KEM-768 "
223 "baseline unavailable on this host",
224 }
225 )
226 continue
227
228 ok = returncode == 0
229 all_success = all_success and ok
230 summary["experiments"].append(
231 {
232 "name": description,
233 "script": script,
234 "output": output,
235 "machine_dependent": machine_dependent,
236 "success": ok,
237 "status": "passed" if ok else "failed",
238 }
239 )
240
241 print("\n" + "=" * 70)
242 print("EXPERIMENT SUMMARY")
243 print("=" * 70)
244 tag_by_status = {"passed": "PASS", "failed": "FAIL", "skipped": "SKIP"}
245 for exp in summary["experiments"]:
246 tag = tag_by_status[exp["status"]]
247 flag = " (machine-dependent)" if exp["machine_dependent"] else ""
248 print(f" [{tag}] {exp['name']}{flag}")
249
250 # No run timestamp: the manifest is committed, and a clock reading would make
251 # every re-run diff against it for no reader's benefit.
252 summary["all_success"] = all_success
253 with open(results_dir / "experiment_summary.json", "w") as f:
254 json.dump(summary, f, indent=2)
255
256 print(f"\nCompleted: {datetime.now()}")
257 print(f"Results saved to: {results_dir}")
258 if all_success:
259 print("\n[ALL EXPERIMENTS PASSED]")
260 else:
261 print("\n[SOME EXPERIMENTS FAILED] -- see per-experiment status above.")
262 return 0 if all_success else 1
263
264
265if __name__ == "__main__":
266 sys.exit(main())
main()
Run every experiment and write the JSON summary.
Definition run_all.py:170
int run_python_script(str script_path, str description)
Run a Python script as a subprocess.
Definition run_all.py:153
Path get_project_root()
Return the project root directory.
Definition run_all.py:40