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
overhead_calculation.py
Go to the documentation of this file.
1#!/usr/bin/env python3
2# -*- coding: utf-8 -*-
3"""
4@file overhead_calculation.py
5@brief White-box ML-KEM-768 overhead analysis versus liboqs baseline.
6@ingroup benchmarks
7
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.
15
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)
18
19@section overhead_calculation_usage Usage
20@code{.sh}
21python overhead_calculation.py
22@endcode
23
24@author Ugur Coruh
25@copyright
26This software is provided for academic and research purposes.
27See LICENSE file for details.
28"""
29
30import json
31import math
32import os
33
34
35def main():
36 """
37 @brief Compute and report the analytical white-box overhead, then write JSON.
38 """
39 print("=" * 60)
40 print("PQ-WB-KEM OVERHEAD ANALYSIS")
41 print("PQ-WB-KEM (feasibility study): overhead analysis")
42 print("=" * 60)
43
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")
46
47 # Baseline (liboqs standard ML-KEM-768)
48 baseline_file = os.path.join(results_dir, "baseline_benchmark.json")
49 with open(baseline_file, "r") as f:
50 baseline = json.load(f)
51
52 # ARM64 baseline, measured under qemu-aarch64 user-mode emulation on the x86-64 host.
53 arm64_file = os.path.join(results_dir, "arm64_benchmark.json")
54 with open(arm64_file, "r") as f:
55 arm64 = json.load(f)
56
57 print("\n[1] BASELINE BENCHMARK (liboqs ML-KEM-768 x86_64)")
58 print("-" * 50)
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")
65
66 print("\n[2] ARM64 BENCHMARK (qemu-aarch64 user-mode emulation on the x86-64 host)")
67 print("-" * 50)
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)")
76
77 # Construction B RNG-excluded lower bound: the N=20 wall-clock masking mean (mask-RNG
78 # excluded) times the cache factor. The deployment projection the paper headlines is the
79 # measured native-C 4.30x protected-primitive ratio times the same cache factor (~47x).
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"])
83
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"])
87
88 cache_file = os.path.join(results_dir, "cache_effect.json")
89 with open(cache_file, "r") as f:
90 cache = json.load(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:
94 raise RuntimeError(
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)
97 )
98 # Mid-estimate of the measured bracket; the deployed factor is cache-dominated and
99 # genuinely uncertain between the two endpoints.
100 cache_factor = math.sqrt(cache_lo * cache_hi)
101 floor_overhead_factor = round(
102 masking_factor * cache_factor
103 ) # RNG-excluded lower bound
104 wb_overhead_factor = round(
105 native_factor * cache_factor
106 ) # deployment headline (RNG incl.)
107
108 # Only decapsulation is protected; keygen and encapsulation run unprotected.
109 wb_decaps = baseline_decaps * wb_overhead_factor
110
111 print("\n[3] WHITE-BOX DECAPSULATION PROJECTION (construction B)")
112 print("-" * 50)
113 print(
114 f" Native primitive:{native_factor:.3f}x (protected/direct, RNG included; primitive_bench_x86.json)"
115 )
116 print(
117 f" Masking floor: {masking_factor:.4f}x (N=20 wall-clock mean, mask-generation RNG excluded)"
118 )
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)")
121 print(
122 f" Deployment: {wb_overhead_factor}x = round({native_factor:.3f} x {cache_factor:.2f}) (headline)"
123 )
124 print(
125 f" Floor: {floor_overhead_factor}x = round({masking_factor:.4f} x {cache_factor:.2f}) (RNG-excluded lower bound)"
126 )
127 print(
128 f" WB Decaps: {wb_decaps:.2f} ms (x86-64 baseline x deployment factor)"
129 )
130
131 # The paper anchors its host estimate on the N=20 portable-Windows liboqs mean
132 # (0.213 ms) times the deployment factor; reproduce it so divergence fails here
133 # rather than in review. No ARM-derived wall-clock is reported anywhere.
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:
140 raise RuntimeError(
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)
144 )
145
146 print(
147 "\n[4] MANUSCRIPT CROSS-CHECK (x86-64 host anchored; no ARM-device wall-clock)"
148 )
149 print("-" * 50)
150 print(
151 f" Host (x86-64) baseline decaps: {paper_baseline_decaps_ms} ms (N=20 portable mean)"
152 )
153 print(
154 f" Derived at {wb_overhead_factor}x: {derived_paper_decaps:.3f} ms"
155 )
156 print(
157 f" Manuscript reports: ~{paper_decaps_ms:.0f} ms (7--14 ms with the +-35% band)"
158 )
159
160 print("\n" + "=" * 60)
161 print("SUMMARY")
162 print("=" * 60)
163 print(
164 f"\n Deployment overhead: {wb_overhead_factor}x (construction B, decapsulation only)"
165 )
166 print(
167 f" Model: {native_factor:.2f}x native protected primitive x {cache_factor:.1f}x cache"
168 )
169 print(
170 f" Floor: {floor_overhead_factor}x ({masking_factor:.2f}x RNG-excluded masking x {cache_factor:.1f}x cache);"
171 )
172 print(" the cache term is a mid-estimate of a measured bracket that spans")
173 print(
174 f" {cache_lo:.1f}x to {cache_hi:.1f}x. The product is an analytical projection,"
175 )
176 print(" not an end-to-end white-box measurement.")
177
178 results = {
179 "baseline_benchmark": {
180 "platform": "x86_64 liboqs",
181 "keygen_ms": baseline_keygen,
182 "encaps_ms": baseline_encaps,
183 "decaps_ms": baseline_decaps,
184 },
185 "arm64_benchmark": {
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.",
191 },
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.",
197 },
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",
207 },
208 "paper_values": {
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,
214 },
215 }
216
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)
220
221 print(f"\nResults saved to {output_file}")
222
223
224if __name__ == "__main__":
225 main()
main()
Compute and report the analytical white-box overhead, then write JSON.