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
baseline_benchmark.py
Go to the documentation of this file.
1#!/usr/bin/env python3
2# -*- coding: utf-8 -*-
3"""
4@file baseline_benchmark.py
5@brief ML-KEM-768 baseline KeyGen/Encaps/Decaps benchmark via liboqs.
6@note Wall-clock timing is build/platform-dependent; for robust reporting use
7 wallclock_ci.py, which aggregates N=20 runs (mean +/- 95% CI) per environment
8 (absolute liboqs times are build- and platform-specific; the dimensionless overhead ratios are the comparable metric).
9@ingroup benchmarks
10
11@details Reference timings (warmup + median/95% CI) used as the baseline for
12white-box overhead factors; decaps is the white-box target. An unavailable
13ML-KEM-768 is a hard error (RuntimeError): the benchmark never substitutes a
14different algorithm. Emits results/baseline_benchmark.json.
15
16@section baseline_benchmark_output Output Files
17- `results/baseline_benchmark.json` - Reference ML-KEM-768 performance baseline
18
19@section baseline_benchmark_usage Usage
20@code{.sh}
21python baseline_benchmark.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 time
31import json
32import os
33import statistics
34from typing import Dict
35import sys
36
37# Distinct exit code for an absent liboqs so run_all.py can treat the native
38# baseline as a machine-dependent skip; a standalone run still exits non-zero.
39LIBOQS_MISSING_EXIT_CODE = 3
40
41try:
42 import oqs
43except ImportError:
44 print("ERROR: liboqs-python not installed")
45 print("Install with: pip install liboqs-python")
46 sys.exit(LIBOQS_MISSING_EXIT_CODE)
47
48
49def benchmark_operation(func, iterations: int = 10000, warmup: int = 1000) -> Dict:
50 """
51 @brief Time a callable over warmup + measured iterations.
52 @param func Zero-arg callable to benchmark.
53 @param iterations Measured iteration count.
54 @param warmup Discarded warmup iteration count.
55 @return Dict of iterations and mean/median/stdev/min/max/95% CI in ms.
56 """
57 # Warmup
58 for _ in range(warmup):
59 func()
60
61 # Actual timing
62 times = []
63 for _ in range(iterations):
64 start = time.perf_counter_ns()
65 func()
66 end = time.perf_counter_ns()
67 times.append((end - start) / 1_000_000) # Convert to ms
68
69 return {
70 "iterations": iterations,
71 "mean_ms": statistics.mean(times),
72 "median_ms": statistics.median(times),
73 "stdev_ms": statistics.stdev(times) if len(times) > 1 else 0,
74 "min_ms": min(times),
75 "max_ms": max(times),
76 "ci_95_ms": (
77 1.96 * statistics.stdev(times) / (len(times) ** 0.5)
78 if len(times) > 1
79 else 0
80 ),
81 }
82
83
84def run_benchmark(algorithm: str = "ML-KEM-768", iterations: int = 10000) -> Dict:
85 """
86 @brief Run the full KeyGen/Encaps/Decaps benchmark for an ML-KEM variant.
87 @param algorithm liboqs KEM name; an unavailable ML-KEM-768 raises RuntimeError
88 (no fallback to a different algorithm).
89 @param iterations Measured iteration count per operation.
90 @return Results dict with algorithm details and per-operation timing stats.
91 """
92 print(f"\n{'='*60}")
93 print("ML-KEM Baseline Benchmark")
94 print(f"Algorithm: {algorithm}")
95 print(f"Iterations: {iterations}")
96 print(f"{'='*60}")
97
98 results = {
99 "algorithm": algorithm,
100 "liboqs_version": oqs.oqs_version(),
101 "iterations": iterations,
102 }
103
104 try:
105 kem = oqs.KeyEncapsulation(algorithm)
106 except Exception as e:
107 raise RuntimeError(
108 f"liboqs could not instantiate '{algorithm}': {e}. This benchmark does not "
109 f"silently substitute a different algorithm; install a liboqs build that exposes "
110 f"ML-KEM-768 (OQS_ENABLE_KEM_ML_KEM) and retry."
111 ) from e
112
113 print(f"\nUsing: {algorithm}")
114 print(f"liboqs version: {oqs.oqs_version()}")
115
116 # Get algorithm details
117 details = kem.details
118 results["details"] = {
119 "name": details["name"],
120 "version": details.get("version", "N/A"),
121 "claimed_nist_level": details["claimed_nist_level"],
122 "length_public_key": details["length_public_key"],
123 "length_secret_key": details["length_secret_key"],
124 "length_ciphertext": details["length_ciphertext"],
125 "length_shared_secret": details["length_shared_secret"],
126 }
127
128 print("\nAlgorithm Details:")
129 print(f" Public key size: {details['length_public_key']} bytes")
130 print(f" Secret key size: {details['length_secret_key']} bytes")
131 print(f" Ciphertext size: {details['length_ciphertext']} bytes")
132 print(f" Shared secret size: {details['length_shared_secret']} bytes")
133
134 # Generate a key pair for encaps/decaps benchmarks
135 public_key = kem.generate_keypair()
136 ciphertext, _ = kem.encap_secret(public_key)
137
138 print("\nBenchmarking KeyGen...")
139
140 def keygen_func():
141 kem2 = oqs.KeyEncapsulation(algorithm)
142 kem2.generate_keypair()
143
144 results["keygen"] = benchmark_operation(keygen_func, iterations)
145 print(f" Median: {results['keygen']['median_ms']:.4f} ms")
146 print(f" 95% CI: +/- {results['keygen']['ci_95_ms']:.4f} ms")
147
148 print("\nBenchmarking Encapsulation...")
149
150 def encaps_func():
151 kem.encap_secret(public_key)
152
153 results["encaps"] = benchmark_operation(encaps_func, iterations)
154 print(f" Median: {results['encaps']['median_ms']:.4f} ms")
155 print(f" 95% CI: +/- {results['encaps']['ci_95_ms']:.4f} ms")
156
157 print("\nBenchmarking Decapsulation...")
158
159 def decaps_func():
160 kem.decap_secret(ciphertext)
161
162 results["decaps"] = benchmark_operation(decaps_func, iterations)
163 print(f" Median: {results['decaps']['median_ms']:.4f} ms")
164 print(f" 95% CI: +/- {results['decaps']['ci_95_ms']:.4f} ms")
165
166 # Summary
167 print(f"\n{'='*60}")
168 print("BENCHMARK SUMMARY")
169 print(f"{'='*60}")
170 print(f"{'Operation':<15} {'Median (ms)':<15} {'95% CI':<15}")
171 print(f"{'-'*45}")
172 print(
173 f"{'KeyGen':<15} {results['keygen']['median_ms']:<15.4f} +/- {results['keygen']['ci_95_ms']:.4f}"
174 )
175 print(
176 f"{'Encaps':<15} {results['encaps']['median_ms']:<15.4f} +/- {results['encaps']['ci_95_ms']:.4f}"
177 )
178 print(
179 f"{'Decaps':<15} {results['decaps']['median_ms']:<15.4f} +/- {results['decaps']['ci_95_ms']:.4f}"
180 )
181 print(f"{'='*60}")
182
183 return results
184
185
186def main():
187 """@brief Run the benchmark and write results to results/baseline_benchmark.json."""
188 results = run_benchmark(iterations=10000)
189
190 script_dir = os.path.dirname(os.path.abspath(__file__))
191 results_dir = os.path.join(os.path.dirname(os.path.dirname(script_dir)), "results")
192 os.makedirs(results_dir, exist_ok=True)
193 output_file = os.path.join(results_dir, "baseline_benchmark.json")
194 with open(output_file, "w") as f:
195 json.dump(results, f, indent=2)
196 print(f"\nResults saved to {output_file}")
197
198 # Baseline results summary
199 print(f"\n{'='*60}")
200 print("BASELINE PERFORMANCE")
201 print(f"{'='*60}")
202 baseline_decaps = results["decaps"]["median_ms"]
203 print(f"Baseline Decaps: {baseline_decaps:.4f} ms")
204 print("Note: White-box overhead will be calculated from actual WB implementation")
205
206
207if __name__ == "__main__":
208 main()
main()
Run the benchmark and write results to results/baseline_benchmark.json.
Dict benchmark_operation(func, int iterations=10000, int warmup=1000)
Time a callable over warmup + measured iterations.
Dict run_benchmark(str algorithm="ML-KEM-768", int iterations=10000)
Run the full KeyGen/Encaps/Decaps benchmark for an ML-KEM variant.