4@file scaling_analysis.py
5@brief White-box overhead scaling across ML-KEM parameter sets and masking orders.
8@note Table-size, overhead and timing figures are analytical projections scaled
9from the ML-KEM-768 baseline, not independent end-to-end measurements.
11@section scaling_analysis_output Output Files
12- `results/scaling_analysis.json` - ML-KEM-512/768/1024 table and overhead scaling projections
14@section scaling_analysis_usage Usage
16python scaling_analysis.py
21This software is provided for academic and research purposes.
22See LICENSE file for details.
28from datetime
import datetime
29from typing
import Dict, Any
77 @brief Read the measured construction footprints
from the committed experiment JSONs.
78 @return (A_shared_mb, B_baked_mb): base tables plus the 3.41 MB encoding sublayer.
79 @details Raises
if the producers have
not run -- no footprint
is hardcoded here.
85 os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__)))),
88 with open(os.path.join(rd,
"whitebox_reference.json"))
as _f:
89 cons = _json.load(_f)[
"constructions"]
90 with open(os.path.join(rd,
"whitebox_encoded.json"))
as _f:
91 enc = float(_json.load(_f)[
"storage"][
"encoding_tables_MB"])
92 a = round(float(cons[
"A_shared_full_table"][
"total_MB"]) + enc, 2)
93 b = round(float(cons[
"B_baked_per_component"][
"total_MB"]) + enc, 2)
102 "bytes_per_table_entry": 2,
103 "table_entries_per_coeff": 3329,
104 "base_tables_per_factor": 3,
106 "assumed_overhead_768": 47,
107 "floor_overhead_768": 17,
108 "measured_core_768_mb_B_baked": _FP_B,
109 "measured_core_768_mb_A_shared": _FP_A,
110 "assumed_table_size_768_mb": 11,
111 "assumed_decaps_time_768_ms": 10.0,
117 @brief NTT table count
for module rank k.
118 @param k Module rank.
119 @return Table count (128, parameter-independent).
123 base_tables = WB_CONSTANTS[
"ntt_factors"]
133 @brief Deployment core-footprint envelope
in MB
for module rank k.
134 @param k Module rank.
135 @return (b_core_mb, a_core_mb) tuple: the k-scaling Construction-B core
and
136 the k-independent Construction-A core.
144 b_core = k * 2.56 + 3.41
145 a_core = WB_CONSTANTS[
"measured_core_768_mb_A_shared"]
146 return (round(b_core), round(a_core))
151 @brief White-box overhead factor
for module rank k.
152 @param k Module rank.
153 @return Overhead factor (rounded).
154 @note Superlinear (k^1.1): more polynomial multiplications
and larger intermediate state.
156 base_overhead = WB_CONSTANTS[
157 "assumed_overhead_768"
162 scaling = (k / base_k) ** 1.1
164 return round(base_overhead * scaling)
169 @brief Estimated decapsulation time
in ms
for module rank k.
170 @param k Module rank.
171 @return (min_ms, max_ms) tuple.
173 base_time = WB_CONSTANTS[
174 "assumed_decaps_time_768_ms"
179 base_overhead = WB_CONSTANTS[
"assumed_overhead_768"]
181 scaling = overhead / base_overhead
184 center = base_time * scaling
187 min_ms = center * (1 - variance)
188 max_ms = center * (1 + variance)
191 return (math.floor(min_ms + 0.5), math.floor(max_ms + 0.5))
196 @brief Minimum recommended RAM (MB)
for deployment.
197 @param k Module rank.
198 @return RAM size rounded up to a common value.
199 @note Targets at least 2x table size.
204 min_ram = max_table_mb * 2
207 ram_sizes = [64, 128, 256, 512, 1024]
208 for size
in ram_sizes:
216 base_shares: int, target_shares: int
219 @brief Overhead of raising masking order
for table-based white-box.
220 @param base_shares Baseline share count.
221 @param target_shares Target share count.
222 @return Dict of memory/performance factors
and security bits.
223 @note Memory
and performance both O(n^2) via ISW-style gadgets (Ishai-Sahai-Wagner, Private Circuits, Crypto 2003).
228 memory_factor = (target_shares**2) / (base_shares**2)
236 theoretical_perf = (target_shares / base_shares) ** 2
237 practical_overhead = 1.2 * 1.1 * 1.1
238 performance_factor = theoretical_perf * practical_overhead
242 base_security_bits = 12.9
246 additional_bits = (target_shares - base_shares) * math.log2(3329) / 2
247 target_security_bits = base_security_bits + additional_bits
250 "base_shares": base_shares,
251 "target_shares": target_shares,
252 "memory_overhead_factor": round(memory_factor, 2),
253 "performance_overhead_factor": round(performance_factor, 2),
254 "base_security_bits": base_security_bits,
255 "target_security_bits": int(
258 "security_improvement_bits": round(additional_bits),
263 """@brief Compute scaling analysis, print tables, and write JSON output."""
266 print(
"ML-KEM WHITE-BOX SCALING ANALYSIS")
267 print(
"PQ-WB-KEM: White-Box ML-KEM Implementation")
268 print(
"Mathematics (MDPI)")
270 print(f
"Timestamp: {datetime.now()}")
275 print(
"1. ML-KEM PARAMETER SCALING")
281 f
"\n{'Parameter':<15} {'ML-KEM-512':<15} {'ML-KEM-768':<15} {'ML-KEM-1024':<15}"
285 for name, params
in ML_KEM_PARAMS.items():
293 scaling_results[name] = {
295 "nist_level": params[
"nist_level"],
296 "ntt_tables": ntt_tables,
297 "table_size_mb": {
"min": table_min,
"max": table_max},
298 "overhead_factor": overhead,
299 "decaps_time_ms": {
"min": time_min,
"max": time_max},
300 "target_ram_mb": target_ram,
303 print(f
"{'Module rank k':<15} {'2':<15} {'3':<15} {'4':<15}")
304 print(f
"{'NIST Level':<15} {'1':<15} {'3':<15} {'5':<15}")
309 f
"{'NTT tables':<15} {r['ML-KEM-512']['ntt_tables']:<15} {r['ML-KEM-768']['ntt_tables']:<15} {r['ML-KEM-1024']['ntt_tables']:<15}"
312 s512 = f
"{r['ML-KEM-512']['table_size_mb']['min']}--{r['ML-KEM-512']['table_size_mb']['max']} MB"
313 s768 = f
"{r['ML-KEM-768']['table_size_mb']['min']}--{r['ML-KEM-768']['table_size_mb']['max']} MB"
314 s1024 = f
"{r['ML-KEM-1024']['table_size_mb']['min']}--{r['ML-KEM-1024']['table_size_mb']['max']} MB"
315 print(f
"{'Table size':<15} {s512:<15} {s768:<15} {s1024:<15}")
318 f
"{'Overhead':<15} {str(r['ML-KEM-512']['overhead_factor'])+'x':<15} {str(r['ML-KEM-768']['overhead_factor'])+'x':<15} {str(r['ML-KEM-1024']['overhead_factor'])+'x':<15}"
321 t512 = f
"{r['ML-KEM-512']['decaps_time_ms']['min']}--{r['ML-KEM-512']['decaps_time_ms']['max']} ms"
322 t768 = f
"{r['ML-KEM-768']['decaps_time_ms']['min']}--{r['ML-KEM-768']['decaps_time_ms']['max']} ms"
323 t1024 = f
"{r['ML-KEM-1024']['decaps_time_ms']['min']}--{r['ML-KEM-1024']['decaps_time_ms']['max']} ms"
324 print(f
"{'Decaps time':<15} {t512:<15} {t768:<15} {t1024:<15}")
327 f
"{'Target RAM':<15} {'>=' + str(r['ML-KEM-512']['target_ram_mb']) + ' MB':<15} {'>=' + str(r['ML-KEM-768']['target_ram_mb']) + ' MB':<15} {'>=' + str(r['ML-KEM-1024']['target_ram_mb']) + ' MB':<15}"
333 print(
"2. HIGHER-ORDER MASKING ANALYSIS")
342 str(m[
"target_shares"]): {
343 "shares": m[
"target_shares"],
344 "memory_overhead_factor": m[
"memory_overhead_factor"],
345 "performance_overhead_factor": m[
"performance_overhead_factor"],
346 "security_bits": m[
"target_security_bits"],
357 _core = WB_CONSTANTS[
"measured_core_768_mb_B_baked"]
358 print(
"\n3-share -> 5-share upgrade:")
360 f
" Memory overhead: {masking_3to5['memory_overhead_factor']}x ({_core:.1f} MB -> {_core * masking_3to5['memory_overhead_factor']:.1f} MB, construction B)"
362 print(f
" Performance overhead: {masking_3to5['performance_overhead_factor']}x")
364 f
" Security: 2^{masking_3to5['base_security_bits']} -> 2^{masking_3to5['target_security_bits']} (+{masking_3to5['security_improvement_bits']} bits)"
367 print(
"\n3-share -> 7-share upgrade:")
369 f
" Memory overhead: {masking_3to7['memory_overhead_factor']}x ({_core:.1f} MB -> {_core * masking_3to7['memory_overhead_factor']:.1f} MB, construction B)"
371 print(f
" Performance overhead: {masking_3to7['performance_overhead_factor']}x")
373 f
" Security: 2^{masking_3to7['base_security_bits']} -> 2^{masking_3to7['target_security_bits']} (+{masking_3to7['security_improvement_bits']} bits)"
379 print(
"3. CALCULATED VALUES FOR PAPER")
382 computed_512 = scaling_results[
"ML-KEM-512"][
"ntt_tables"]
383 computed_768 = scaling_results[
"ML-KEM-768"][
"ntt_tables"]
384 computed_1024 = scaling_results[
"ML-KEM-1024"][
"ntt_tables"]
385 computed_512_overhead = scaling_results[
"ML-KEM-512"][
"overhead_factor"]
386 computed_1024_overhead = scaling_results[
"ML-KEM-1024"][
"overhead_factor"]
387 computed_5share_mem = masking_3to5[
"memory_overhead_factor"]
388 computed_5share_perf = masking_3to5[
"performance_overhead_factor"]
390 print(f
"\n{'Metric':<35} {'Value':<20}")
392 print(f
"{'ML-KEM-512 NTT tables':<35} {computed_512}")
393 print(f
"{'ML-KEM-768 NTT tables':<35} {computed_768}")
394 print(f
"{'ML-KEM-1024 NTT tables':<35} {computed_1024}")
395 print(f
"{'ML-KEM-512 overhead':<35} {computed_512_overhead}x")
397 f
"{'ML-KEM-768 overhead':<35} 47x deployment (est., construction B; 17x RNG-excluded floor)"
399 print(f
"{'ML-KEM-1024 overhead':<35} {computed_1024_overhead}x")
400 print(f
"{'5-share memory factor':<35} {computed_5share_mem}x")
401 print(f
"{'5-share performance factor':<35} {computed_5share_perf}x")
403 f
"{'5-share security improvement':<35} +{masking_3to5['security_improvement_bits']} bits"
409 "description":
"ML-KEM White-Box Scaling Analysis - Calculated values for paper tables",
410 "ml_kem_params": ML_KEM_PARAMS,
411 "wb_constants": WB_CONSTANTS,
412 "scaling_analysis": scaling_results,
413 "higher_order_masking": {
414 "3_to_2_share": masking_3to2,
415 "3_to_4_share": masking_3to4,
416 "3_to_5_share": masking_3to5,
417 "3_to_7_share": masking_3to7,
418 "points": masking_points,
420 "calculated_values": {
422 "ML-KEM-512": computed_512,
423 "ML-KEM-768": computed_768,
424 "ML-KEM-1024": computed_1024,
426 "overhead_factors": {
427 "ML-KEM-512": computed_512_overhead,
429 "ML-KEM-1024": computed_1024_overhead,
432 "memory_factor": computed_5share_mem,
433 "performance_factor": computed_5share_perf,
434 "security_improvement_bits": masking_3to5[
"security_improvement_bits"],
439 script_dir = os.path.dirname(os.path.abspath(__file__))
440 project_root = os.path.dirname(os.path.dirname(script_dir))
441 results_dir = os.path.join(project_root,
"results")
442 os.makedirs(results_dir, exist_ok=
True)
444 output_file = os.path.join(results_dir,
"scaling_analysis.json")
445 with open(output_file,
"w")
as f:
446 json.dump(output, f, indent=2)
448 print(f
"Results saved to: {output_file}")
451 print(
"SCALING ANALYSIS COMPLETE")
457if __name__ ==
"__main__":
Dict[str, Any] calculate_higher_order_masking(int base_shares, int target_shares)
Overhead of raising masking order for table-based white-box.
_load_measured_footprints()
Read the measured construction footprints from the committed experiment JSONs.
int calculate_ntt_tables(int k)
NTT table count for module rank k.
main()
Compute scaling analysis, print tables, and write JSON output.
float calculate_overhead_factor(int k)
White-box overhead factor for module rank k.
tuple calculate_decaps_time_ms(int k)
Estimated decapsulation time in ms for module rank k.
int calculate_target_ram_mb(int k)
Minimum recommended RAM (MB) for deployment.
tuple calculate_table_size_mb(int k)
Deployment core-footprint envelope in MB for module rank k.