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
scaling_analysis.py
Go to the documentation of this file.
1#!/usr/bin/env python3
2# -*- coding: utf-8 -*-
3"""
4@file scaling_analysis.py
5@brief White-box overhead scaling across ML-KEM parameter sets and masking orders.
6@ingroup analysis
7
8@note Table-size, overhead and timing figures are analytical projections scaled
9from the ML-KEM-768 baseline, not independent end-to-end measurements.
10
11@section scaling_analysis_output Output Files
12- `results/scaling_analysis.json` - ML-KEM-512/768/1024 table and overhead scaling projections
13
14@section scaling_analysis_usage Usage
15@code{.sh}
16python scaling_analysis.py
17@endcode
18
19@author Ugur Coruh
20@copyright
21This software is provided for academic and research purposes.
22See LICENSE file for details.
23"""
24
25import json
26import math
27import os
28from datetime import datetime
29from typing import Dict, Any
30
31# ML-KEM parameters (FIPS 203)
32ML_KEM_PARAMS = {
33 "ML-KEM-512": {
34 "n": 256,
35 "k": 2,
36 "q": 3329,
37 "eta1": 3,
38 "eta2": 2,
39 "du": 10,
40 "dv": 4,
41 "nist_level": 1,
42 "pk_bytes": 800,
43 "sk_bytes": 1632,
44 "ct_bytes": 768,
45 },
46 "ML-KEM-768": {
47 "n": 256,
48 "k": 3,
49 "q": 3329,
50 "eta1": 2,
51 "eta2": 2,
52 "du": 10,
53 "dv": 4,
54 "nist_level": 3,
55 "pk_bytes": 1184,
56 "sk_bytes": 2400,
57 "ct_bytes": 1088,
58 },
59 "ML-KEM-1024": {
60 "n": 256,
61 "k": 4,
62 "q": 3329,
63 "eta1": 2,
64 "eta2": 2,
65 "du": 11,
66 "dv": 5,
67 "nist_level": 5,
68 "pk_bytes": 1568,
69 "sk_bytes": 3168,
70 "ct_bytes": 1568,
71 },
72}
73
74
76 """
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.
80 """
81 import os
82 import json as _json
83
84 rd = os.path.join(
85 os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__)))),
86 "results",
87 )
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)
94 return a, b
95
96
98
99# White-box implementation constants
100WB_CONSTANTS = {
101 "ntt_factors": 128, # X^256+1 factors over Z_q
102 "bytes_per_table_entry": 2, # uint16 per entry; q = 3329 fits in 12 bits
103 "table_entries_per_coeff": 3329, # q possible values
104 "base_tables_per_factor": 3, # h0, h1, h2 per irreducible factor
105 "masking_shares": 3, # Default 3-share masking
106 "assumed_overhead_768": 47, # construction B deployment: native-C 4.30x protected primitive x ~11x cache
107 "floor_overhead_768": 17, # RNG-excluded lower bound: ~1.55x masking floor x ~11x cache; A is not projected
108 "measured_core_768_mb_B_baked": _FP_B, # B: 7.67 base + 3.41 encoding (from whitebox_reference/encoded JSON)
109 "measured_core_768_mb_A_shared": _FP_A, # A: 22.16 base + 3.41 encoding (from whitebox_reference/encoded JSON)
110 "assumed_table_size_768_mb": 11, # construction B measured core (k=3)
111 "assumed_decaps_time_768_ms": 10.0, # x86-64 host 0.213 ms x ~47x deployment (B); no ARM-device measurement
112}
113
114
115def calculate_ntt_tables(k: int) -> int:
116 """
117 @brief NTT table count for module rank k.
118 @param k Module rank.
119 @return Table count (128, parameter-independent).
120 """
121 # X^256+1 factors into 128 degree-2 polynomials for every ML-KEM parameter
122 # set (n, q fixed); the count is param-independent.
123 base_tables = WB_CONSTANTS["ntt_factors"] # 128 (constant)
124
125 # The number of NTT multiplication tables is the factorization count (128),
126 # constant across parameter sets; only the per-vector component
127 # multiplications (k x 128) scale with the module rank.
128 return base_tables # 128, constant
129
130
131def calculate_table_size_mb(k: int) -> tuple:
132 """
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.
137 """
138 # Construction B (baked, recommended): measured core = k * 2.56 MB baked base
139 # tables + 3.41 MB encoding sublayer, scaling with k. Construction A (shared)
140 # is k-independent at 25.57 MB core. The deployment envelope runs from the
141 # compact B core up to the A core; the runtime obfuscation layers (coefficient
142 # shuffle 3 KB, three-share masking 0 B; see obfuscation_storage.py) add only a
143 # few KB and do not move these MB-scale figures.
144 b_core = k * 2.56 + 3.41
145 a_core = WB_CONSTANTS["measured_core_768_mb_A_shared"] # 25.57, k-independent
146 return (round(b_core), round(a_core))
147
148
149def calculate_overhead_factor(k: int) -> float:
150 """
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.
155 """
156 base_overhead = WB_CONSTANTS[
157 "assumed_overhead_768"
158 ] # 47x deployment for k=3 (construction B)
159 base_k = 3
160
161 # Slightly superlinear scaling: k^1.1
162 scaling = (k / base_k) ** 1.1
163
164 return round(base_overhead * scaling)
165
166
167def calculate_decaps_time_ms(k: int) -> tuple:
168 """
169 @brief Estimated decapsulation time in ms for module rank k.
170 @param k Module rank.
171 @return (min_ms, max_ms) tuple.
172 """
173 base_time = WB_CONSTANTS[
174 "assumed_decaps_time_768_ms"
175 ] # ~10 ms for k=3 (x86 host 0.213 x ~47x, construction B)
176
177 # Time scales with overhead
178 overhead = calculate_overhead_factor(k)
179 base_overhead = WB_CONSTANTS["assumed_overhead_768"]
180
181 scaling = overhead / base_overhead
182
183 # Add variance for different platforms
184 center = base_time * scaling
185 variance = 0.35 # ±35% for platform differences
186
187 min_ms = center * (1 - variance)
188 max_ms = center * (1 + variance)
189
190 # half-up rounding (Python's round() is banker's: round(6.5) == 6)
191 return (math.floor(min_ms + 0.5), math.floor(max_ms + 0.5))
192
193
194def calculate_target_ram_mb(k: int) -> int:
195 """
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.
200 """
201 _, max_table_mb = calculate_table_size_mb(k)
202
203 # Round up to nearest power of 2 for practical RAM sizes
204 min_ram = max_table_mb * 2
205
206 # Round to common RAM sizes: 64, 128, 256, 512, 1024
207 ram_sizes = [64, 128, 256, 512, 1024]
208 for size in ram_sizes:
209 if size >= min_ram:
210 return size
211
212 return 1024
213
214
216 base_shares: int, target_shares: int
217) -> Dict[str, Any]:
218 """
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).
224 """
225 # Memory overhead: O(n^2) for the ISW cross-product tables, so the ratio is
226 # the square of the share ratio. The paper's 3 -> 5 figure (2.78x) is this
227 # quantity; an n(n+1)/2 count of tables would give 2.5x instead.
228 memory_factor = (target_shares**2) / (base_shares**2)
229
230 # Performance overhead: O(n^2) due to ISW-style share recombination
231 # Each multiplication requires n^2 partial products
232 # Additionally, practical overhead includes:
233 # - Cache misses from larger table footprint (~1.2x)
234 # - Memory bandwidth saturation (~1.1x)
235 # - Branch mispredictions from more complex control flow (~1.1x)
236 theoretical_perf = (target_shares / base_shares) ** 2
237 practical_overhead = 1.2 * 1.1 * 1.1 # ~1.45x practical multiplier
238 performance_factor = theoretical_perf * practical_overhead
239
240 # Security improvement
241 # n-share masking protects against (n-1)-order attacks
242 base_security_bits = 12.9 # first-order DCA estimate (1/rho^2, measured rho=0.0113; concrete_security_bounds.py); not a proof
243
244 # Higher-order attacks require combining more intermediates
245 # Each additional share adds ~log2(q) bits of security
246 additional_bits = (target_shares - base_shares) * math.log2(3329) / 2
247 target_security_bits = base_security_bits + additional_bits
248
249 return {
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(
256 target_security_bits
257 ), # floor, matching the footprint/concrete int() convention
258 "security_improvement_bits": round(additional_bits),
259 }
260
261
262def main():
263 """@brief Compute scaling analysis, print tables, and write JSON output."""
264
265 print("=" * 70)
266 print("ML-KEM WHITE-BOX SCALING ANALYSIS")
267 print("PQ-WB-KEM: White-Box ML-KEM Implementation")
268 print("Mathematics (MDPI)")
269 print("=" * 70)
270 print(f"Timestamp: {datetime.now()}")
271 print()
272
273 # 1. ML-KEM parameter scaling
274 print("-" * 70)
275 print("1. ML-KEM PARAMETER SCALING")
276 print("-" * 70)
277
278 scaling_results = {}
279
280 print(
281 f"\n{'Parameter':<15} {'ML-KEM-512':<15} {'ML-KEM-768':<15} {'ML-KEM-1024':<15}"
282 )
283 print("-" * 60)
284
285 for name, params in ML_KEM_PARAMS.items():
286 k = params["k"]
287 ntt_tables = calculate_ntt_tables(k)
288 table_min, table_max = calculate_table_size_mb(k)
289 overhead = calculate_overhead_factor(k)
290 time_min, time_max = calculate_decaps_time_ms(k)
291 target_ram = calculate_target_ram_mb(k)
292
293 scaling_results[name] = {
294 "module_rank_k": k,
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,
301 }
302
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}")
305 print("-" * 60)
306
307 r = scaling_results
308 print(
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}"
310 )
311
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}")
316
317 print(
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}"
319 )
320
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}")
325
326 print(
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}"
328 )
329 print()
330
331 # 2. Higher-order masking analysis
332 print("-" * 70)
333 print("2. HIGHER-ORDER MASKING ANALYSIS")
334 print("-" * 70)
335
336 masking_3to2 = calculate_higher_order_masking(3, 2)
337 masking_3to4 = calculate_higher_order_masking(3, 4)
338 masking_3to5 = calculate_higher_order_masking(3, 5)
339 masking_3to7 = calculate_higher_order_masking(3, 7)
340 # Consolidated per-share points for the performance/security figure (artifact-traceable).
341 masking_points = {
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"],
347 }
348 for m in (
349 masking_3to2,
351 masking_3to4,
352 masking_3to5,
353 masking_3to7,
354 )
355 }
356
357 _core = WB_CONSTANTS["measured_core_768_mb_B_baked"] # construction B, k=3
358 print("\n3-share -> 5-share upgrade:")
359 print(
360 f" Memory overhead: {masking_3to5['memory_overhead_factor']}x ({_core:.1f} MB -> {_core * masking_3to5['memory_overhead_factor']:.1f} MB, construction B)"
361 )
362 print(f" Performance overhead: {masking_3to5['performance_overhead_factor']}x")
363 print(
364 f" Security: 2^{masking_3to5['base_security_bits']} -> 2^{masking_3to5['target_security_bits']} (+{masking_3to5['security_improvement_bits']} bits)"
365 )
366
367 print("\n3-share -> 7-share upgrade:")
368 print(
369 f" Memory overhead: {masking_3to7['memory_overhead_factor']}x ({_core:.1f} MB -> {_core * masking_3to7['memory_overhead_factor']:.1f} MB, construction B)"
370 )
371 print(f" Performance overhead: {masking_3to7['performance_overhead_factor']}x")
372 print(
373 f" Security: 2^{masking_3to7['base_security_bits']} -> 2^{masking_3to7['target_security_bits']} (+{masking_3to7['security_improvement_bits']} bits)"
374 )
375 print()
376
377 # 3. Summary for paper
378 print("-" * 70)
379 print("3. CALCULATED VALUES FOR PAPER")
380 print("-" * 70)
381
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"]
389
390 print(f"\n{'Metric':<35} {'Value':<20}")
391 print("-" * 55)
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")
396 print(
397 f"{'ML-KEM-768 overhead':<35} 47x deployment (est., construction B; 17x RNG-excluded floor)"
398 )
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")
402 print(
403 f"{'5-share security improvement':<35} +{masking_3to5['security_improvement_bits']} bits"
404 )
405
406 print()
407
408 output = {
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,
419 },
420 "calculated_values": {
421 "ntt_tables": {
422 "ML-KEM-512": computed_512,
423 "ML-KEM-768": computed_768,
424 "ML-KEM-1024": computed_1024,
425 },
426 "overhead_factors": {
427 "ML-KEM-512": computed_512_overhead,
428 "ML-KEM-768": 47, # construction B deployment projection (matches wb_constants; floor 17)
429 "ML-KEM-1024": computed_1024_overhead,
430 },
431 "5share_upgrade": {
432 "memory_factor": computed_5share_mem,
433 "performance_factor": computed_5share_perf,
434 "security_improvement_bits": masking_3to5["security_improvement_bits"],
435 },
436 },
437 }
438
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)
443
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)
447
448 print(f"Results saved to: {output_file}")
449 print()
450 print("=" * 70)
451 print("SCALING ANALYSIS COMPLETE")
452 print("=" * 70)
453
454 return output
455
456
457if __name__ == "__main__":
458 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.