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).
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.
16@section baseline_benchmark_output Output Files
17- `results/baseline_benchmark.json` - Reference ML-KEM-768 performance baseline
19@section baseline_benchmark_usage Usage
21python baseline_benchmark.py
26This software
is provided
for academic
and research purposes.
27See LICENSE file
for details.
34from typing import Dict
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
44 print(
"ERROR: liboqs-python not installed")
45 print(
"Install with: pip install liboqs-python")
46 sys.exit(LIBOQS_MISSING_EXIT_CODE)
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.
58 for _
in range(warmup):
63 for _
in range(iterations):
64 start = time.perf_counter_ns()
66 end = time.perf_counter_ns()
67 times.append((end - start) / 1_000_000)
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,
77 1.96 * statistics.stdev(times) / (len(times) ** 0.5)
84def run_benchmark(algorithm: str =
"ML-KEM-768", iterations: int = 10000) -> Dict:
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.
93 print(
"ML-KEM Baseline Benchmark")
94 print(f
"Algorithm: {algorithm}")
95 print(f
"Iterations: {iterations}")
99 "algorithm": algorithm,
100 "liboqs_version": oqs.oqs_version(),
101 "iterations": iterations,
105 kem = oqs.KeyEncapsulation(algorithm)
106 except Exception
as e:
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."
113 print(f
"\nUsing: {algorithm}")
114 print(f
"liboqs version: {oqs.oqs_version()}")
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"],
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")
135 public_key = kem.generate_keypair()
136 ciphertext, _ = kem.encap_secret(public_key)
138 print(
"\nBenchmarking KeyGen...")
141 kem2 = oqs.KeyEncapsulation(algorithm)
142 kem2.generate_keypair()
145 print(f
" Median: {results['keygen']['median_ms']:.4f} ms")
146 print(f
" 95% CI: +/- {results['keygen']['ci_95_ms']:.4f} ms")
148 print(
"\nBenchmarking Encapsulation...")
151 kem.encap_secret(public_key)
154 print(f
" Median: {results['encaps']['median_ms']:.4f} ms")
155 print(f
" 95% CI: +/- {results['encaps']['ci_95_ms']:.4f} ms")
157 print(
"\nBenchmarking Decapsulation...")
160 kem.decap_secret(ciphertext)
163 print(f
" Median: {results['decaps']['median_ms']:.4f} ms")
164 print(f
" 95% CI: +/- {results['decaps']['ci_95_ms']:.4f} ms")
168 print(
"BENCHMARK SUMMARY")
170 print(f
"{'Operation':<15} {'Median (ms)':<15} {'95% CI':<15}")
173 f
"{'KeyGen':<15} {results['keygen']['median_ms']:<15.4f} +/- {results['keygen']['ci_95_ms']:.4f}"
176 f
"{'Encaps':<15} {results['encaps']['median_ms']:<15.4f} +/- {results['encaps']['ci_95_ms']:.4f}"
179 f
"{'Decaps':<15} {results['decaps']['median_ms']:<15.4f} +/- {results['decaps']['ci_95_ms']:.4f}"
187 """@brief Run the benchmark and write results to results/baseline_benchmark.json."""
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}")
200 print(
"BASELINE PERFORMANCE")
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")
207if __name__ ==
"__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.