4@file overhead_calculation.py
5@brief White-box ML-KEM-768 overhead analysis versus liboqs baseline.
8@note The construction-B overhead factor is derived here from the measured masking mean
9 (wallclock_statistics_windows.json) and the measured cache bracket (cache_effect.json);
10 it
is an analytical projection,
not an end-to-end measured white-box timing.
11@note The ARM64 figures come
from AArch64 binaries run under qemu-aarch64 user-mode
12 emulation on the x86-64 host: QEMU emulates the ARM64 instruction set
while the
13 host CPU performs the work. They characterise instruction-level behaviour
and are
14 not any ARM device
's wall-clock, so no physical-device timing is derived from them.
16@section overhead_calculation_output Output Files
17- `results/overhead_calculation.json` - White-box vs reference performance-overhead ratio (consumes baseline_benchmark.json
and arm64_benchmark.json)
19@section overhead_calculation_usage Usage
21python overhead_calculation.py
26This software
is provided
for academic
and research purposes.
27See LICENSE file
for details.
37 @brief Compute
and report the analytical white-box overhead, then write JSON.
40 print(
"PQ-WB-KEM OVERHEAD ANALYSIS")
41 print(
"PQ-WB-KEM (feasibility study): overhead analysis")
44 script_dir = os.path.dirname(os.path.abspath(__file__))
45 results_dir = os.path.join(os.path.dirname(os.path.dirname(script_dir)),
"results")
48 baseline_file = os.path.join(results_dir,
"baseline_benchmark.json")
49 with open(baseline_file,
"r")
as f:
50 baseline = json.load(f)
53 arm64_file = os.path.join(results_dir,
"arm64_benchmark.json")
54 with open(arm64_file,
"r")
as f:
57 print(
"\n[1] BASELINE BENCHMARK (liboqs ML-KEM-768 x86_64)")
59 baseline_keygen = baseline[
"keygen"][
"mean_ms"]
60 baseline_encaps = baseline[
"encaps"][
"mean_ms"]
61 baseline_decaps = baseline[
"decaps"][
"mean_ms"]
62 print(f
" KeyGen: {baseline_keygen:.4f} ms")
63 print(f
" Encaps: {baseline_encaps:.4f} ms")
64 print(f
" Decaps: {baseline_decaps:.4f} ms")
66 print(
"\n[2] ARM64 BENCHMARK (qemu-aarch64 user-mode emulation on the x86-64 host)")
68 arm64_keygen = arm64[
"results"][
"keygen"][
"mean_ms"]
69 arm64_encaps = arm64[
"results"][
"encaps"][
"mean_ms"]
70 arm64_decaps = arm64[
"results"][
"decaps"][
"mean_ms"]
71 print(f
" KeyGen: {arm64_keygen:.3f} ms")
72 print(f
" Encaps: {arm64_encaps:.3f} ms")
73 print(f
" Decaps: {arm64_decaps:.3f} ms")
74 print(
" (instruction-level behaviour of the emulated ISA; the host CPU does the")
75 print(
" work, so these are not any ARM device's wall-clock)")
80 wallclock_file = os.path.join(results_dir,
"wallclock_statistics_windows.json")
81 with open(wallclock_file,
"r")
as f:
82 masking_factor = float(json.load(f)[
"metrics"][
"masking_overhead_x"][
"mean"])
84 native_file = os.path.join(results_dir,
"primitive_bench_x86.json")
85 with open(native_file,
"r")
as f:
86 native_factor = float(json.load(f)[
"protected_over_direct_ratio"])
88 cache_file = os.path.join(results_dir,
"cache_effect.json")
89 with open(cache_file,
"r")
as f:
91 cache_lo = float(cache[
"primitive"][
"cold_realistic_penalty_factor"])
92 cache_hi = float(cache[
"working_set_sweep"][
"penalty_table_vs_L1"])
93 if not 0.0 < cache_lo < cache_hi:
95 "cache_effect.json bracket is degenerate (lo=%r, hi=%r); re-run cache_effect.c "
96 "before projecting the overhead." % (cache_lo, cache_hi)
100 cache_factor = math.sqrt(cache_lo * cache_hi)
101 floor_overhead_factor = round(
102 masking_factor * cache_factor
104 wb_overhead_factor = round(
105 native_factor * cache_factor
109 wb_decaps = baseline_decaps * wb_overhead_factor
111 print(
"\n[3] WHITE-BOX DECAPSULATION PROJECTION (construction B)")
114 f
" Native primitive:{native_factor:.3f}x (protected/direct, RNG included; primitive_bench_x86.json)"
117 f
" Masking floor: {masking_factor:.4f}x (N=20 wall-clock mean, mask-generation RNG excluded)"
119 print(f
" Cache bracket: {cache_lo:.3f}x .. {cache_hi:.3f}x (measured)")
120 print(f
" Cache factor: {cache_factor:.2f}x (geometric mean of the bracket)")
122 f
" Deployment: {wb_overhead_factor}x = round({native_factor:.3f} x {cache_factor:.2f}) (headline)"
125 f
" Floor: {floor_overhead_factor}x = round({masking_factor:.4f} x {cache_factor:.2f}) (RNG-excluded lower bound)"
128 f
" WB Decaps: {wb_decaps:.2f} ms (x86-64 baseline x deployment factor)"
134 with open(wallclock_file,
"r")
as f:
135 host_baseline_ms = float(json.load(f)[
"metrics"][
"liboqs_decaps_ms"][
"mean"])
136 paper_baseline_decaps_ms = round(host_baseline_ms, 3)
137 paper_decaps_ms = 10.0
138 derived_paper_decaps = paper_baseline_decaps_ms * wb_overhead_factor
139 if abs(derived_paper_decaps - paper_decaps_ms) > 0.5:
141 "the deployment factor %dx puts the host decapsulation at %.3f ms, but the "
142 "manuscript reports ~%.0f ms; reconcile the manuscript with this model."
143 % (wb_overhead_factor, derived_paper_decaps, paper_decaps_ms)
147 "\n[4] MANUSCRIPT CROSS-CHECK (x86-64 host anchored; no ARM-device wall-clock)"
151 f
" Host (x86-64) baseline decaps: {paper_baseline_decaps_ms} ms (N=20 portable mean)"
154 f
" Derived at {wb_overhead_factor}x: {derived_paper_decaps:.3f} ms"
157 f
" Manuscript reports: ~{paper_decaps_ms:.0f} ms (7--14 ms with the +-35% band)"
160 print(
"\n" +
"=" * 60)
164 f
"\n Deployment overhead: {wb_overhead_factor}x (construction B, decapsulation only)"
167 f
" Model: {native_factor:.2f}x native protected primitive x {cache_factor:.1f}x cache"
170 f
" Floor: {floor_overhead_factor}x ({masking_factor:.2f}x RNG-excluded masking x {cache_factor:.1f}x cache);"
172 print(
" the cache term is a mid-estimate of a measured bracket that spans")
174 f
" {cache_lo:.1f}x to {cache_hi:.1f}x. The product is an analytical projection,"
176 print(
" not an end-to-end white-box measurement.")
179 "baseline_benchmark": {
180 "platform":
"x86_64 liboqs",
181 "keygen_ms": baseline_keygen,
182 "encaps_ms": baseline_encaps,
183 "decaps_ms": baseline_decaps,
186 "platform":
"ARM64 QEMU",
187 "keygen_ms": arm64_keygen,
188 "encaps_ms": arm64_encaps,
189 "decaps_ms": arm64_decaps,
190 "measurement_note":
"AArch64 binaries under qemu-aarch64 user-mode emulation on the x86-64 host; QEMU emulates the ARM64 instruction set while the host CPU performs the work. Characterises instruction-level behaviour of the emulated ISA, not any ARM device's wall-clock.",
192 "whitebox_estimate": {
193 "overhead_factor": wb_overhead_factor,
194 "floor_overhead_factor": floor_overhead_factor,
195 "decaps_ms": wb_decaps,
196 "note":
"Construction B, decapsulation only; keygen and encapsulation run unprotected at baseline.",
198 "projection_model": {
199 "native_primitive_factor": native_factor,
200 "native_source":
"primitive_bench_x86.json: protected_over_direct_ratio (RNG included)",
201 "masking_factor": masking_factor,
202 "masking_source":
"wallclock_statistics_windows.json: metrics.masking_overhead_x.mean (N=20; mask-generation RNG excluded, so a lower bound on masking cost)",
203 "cache_factor": cache_factor,
204 "cache_bracket_measured": [cache_lo, cache_hi],
205 "cache_source":
"cache_effect.json: geometric mean of primitive.cold_realistic_penalty_factor and working_set_sweep.penalty_table_vs_L1",
206 "status":
"analytical projection (measured masking x mid-estimate of a measured cache bracket); not an end-to-end white-box measurement",
209 "note":
"Only decapsulation is protected; keygen/encaps run unprotected at baseline.",
210 "decaps_ms": paper_decaps_ms,
211 "baseline_decaps_ms": paper_baseline_decaps_ms,
212 "overhead": wb_overhead_factor,
213 "floor_overhead": floor_overhead_factor,
217 output_file = os.path.join(results_dir,
"overhead_calculation.json")
218 with open(output_file,
"w")
as f:
219 json.dump(results, f, indent=2)
221 print(f
"\nResults saved to {output_file}")
224if __name__ ==
"__main__":
main()
Compute and report the analytical white-box overhead, then write JSON.