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
whitebox_reference Namespace Reference

Functions

 _bitrev7 (k)
 Bit-reversal of a 7-bit index (FIPS-203 NTT twiddle order).
 
 _negacyclic (f, g)
 Schoolbook multiply in Z_q[X]/(X^256+1); independent correctness oracle.
 
 _poly_mod_x2 (f, gamma)
 Reduce a length-256 polynomial modulo (X^2 - gamma) over Z_q.
 
 _zeta_powers ()
 Powers of zeta mod q for the NTT.
 
 base_mul_baked (tabs, uh, i)
 Construction B base multiply via baked per-component lookups.
 
 base_mul_direct (sh, uh, i)
 Reference base multiply for degree-2 factor i (direct arithmetic).
 
 base_mul_shared (M, sh, uh, i)
 Construction A base multiply via shared-table lookups (full-range secret).
 
 build_baked_tables (sh)
 Construction B tables for one secret polynomial: per-component q-entry tables with the fixed secret baked in.
 
 build_shared_table ()
 Construction A table: one shared full multiply table M[x][y]=x*y mod q.
 
 cbd_range_occupancy (shat_polys)
 Count NTT-domain secret coordinates landing in the coefficient-domain CBD range {-2..2} mod q.
 
 main ()
 Build both constructions on the real NTT-domain secret, check correctness, measure sizes and masking overhead, write JSON.
 
 measure_cbd_range_occupancy (n_seeds=200)
 Occupancy rate over many independent secrets, so the reference-sample count is not mistaken for the underlying rate.
 
 measure_overhead (iters=100000, seed=SEED)
 Construction-B protected-primitive overhead (baked table lookup plus 3-share masking versus direct arithmetic) on the real full-range NTT-domain secret, for wall-clock CI aggregation (wallclock_ci.py).
 
 ntt_forward (poly)
 Forward NTT: coefficient domain to NTT domain.
 
 sample_cbd (rng, size, eta=ETA)
 Draw from the centered binomial distribution CBD_eta of FIPS 203.
 
 three_share (v, rng)
 Split a value into three arithmetic shares mod q.
 

Variables

dict CBD_RANGE = {(-2) % Q, (-1) % Q, 0, 1, 2}
 
int ETA = 2
 
 GAMMAS
 
int K = 3
 
int N = 256
 
int NUM_COMPONENTS = N // 2
 
int Q = 3329
 
int SEED = 42
 
int ZETA = 17
 
 ZETA_POWERS = _zeta_powers()
 

Function Documentation

◆ _bitrev7()

whitebox_reference._bitrev7 (   k)
protected

Bit-reversal of a 7-bit index (FIPS-203 NTT twiddle order).

Parameters
kIndex in [0, 128).
Returns
Bit-reversed 7-bit index.

Definition at line 70 of file whitebox_reference.py.

Referenced by ntt_forward().

+ Here is the caller graph for this function:

◆ _negacyclic()

whitebox_reference._negacyclic (   f,
  g 
)
protected

Schoolbook multiply in Z_q[X]/(X^256+1); independent correctness oracle.

Parameters
fFirst length-256 coefficient vector.
gSecond length-256 coefficient vector.
Returns
Length-256 product coefficient vector.

Definition at line 167 of file whitebox_reference.py.

Referenced by main().

+ Here is the caller graph for this function:

◆ _poly_mod_x2()

whitebox_reference._poly_mod_x2 (   f,
  gamma 
)
protected

Reduce a length-256 polynomial modulo (X^2 - gamma) over Z_q.

Parameters
fCoefficient vector.
gammaComponent twiddle constant.
Returns
(a0, a1) reduced coordinates.

Definition at line 188 of file whitebox_reference.py.

Referenced by main().

+ Here is the caller graph for this function:

◆ _zeta_powers()

whitebox_reference._zeta_powers ( )
protected

Powers of zeta mod q for the NTT.

Returns
Array of 256 zeta powers.

Definition at line 55 of file whitebox_reference.py.

◆ base_mul_baked()

whitebox_reference.base_mul_baked (   tabs,
  uh,
  i 
)

Construction B base multiply via baked per-component lookups.

Parameters
tabsBaked tables for the secret polynomial;
uhCiphertext;
iComponent.
Returns
(p0, p1) mod q.

Definition at line 245 of file whitebox_reference.py.

◆ base_mul_direct()

whitebox_reference.base_mul_direct (   sh,
  uh,
  i 
)

Reference base multiply for degree-2 factor i (direct arithmetic).

Parameters
shNTT-domain secret polynomial (length 256, full-range).
uhNTT-domain ciphertext polynomial (length 256).
iComponent index in [0, 128).
Returns
(p0, p1) product coordinates mod q.

Definition at line 153 of file whitebox_reference.py.

◆ base_mul_shared()

whitebox_reference.base_mul_shared (   M,
  sh,
  uh,
  i 
)

Construction A base multiply via shared-table lookups (full-range secret).

Parameters
MShared multiply table.
shNTT-domain secret;
uhNTT-domain ciphertext;
iComponent.
Returns
(p0, p1) mod q.

Definition at line 213 of file whitebox_reference.py.

◆ build_baked_tables()

whitebox_reference.build_baked_tables (   sh)

Construction B tables for one secret polynomial: per-component q-entry tables with the fixed secret baked in.

Parameters
shNTT-domain secret polynomial (full-range).
Returns
list of 128 (h0, h1, h2) uint16 triples.

Definition at line 227 of file whitebox_reference.py.

◆ build_shared_table()

whitebox_reference.build_shared_table ( )

Construction A table: one shared full multiply table M[x][y]=x*y mod q.

Returns
uint16 array of shape (q, q); secret-independent.

Definition at line 204 of file whitebox_reference.py.

Referenced by main().

+ Here is the caller graph for this function:

◆ cbd_range_occupancy()

whitebox_reference.cbd_range_occupancy (   shat_polys)

Count NTT-domain secret coordinates landing in the coefficient-domain CBD range {-2..2} mod q.

Parameters
shat_polysList of NTT-domain secret polynomials.
Returns
(coordinates, in_range_count).

Definition at line 125 of file whitebox_reference.py.

Referenced by main(), and measure_cbd_range_occupancy().

+ Here is the caller graph for this function:

◆ main()

whitebox_reference.main ( void  )

Build both constructions on the real NTT-domain secret, check correctness, measure sizes and masking overhead, write JSON.

Definition at line 300 of file whitebox_reference.py.

References _negacyclic(), _poly_mod_x2(), build_shared_table(), cbd_range_occupancy(), main(), measure_cbd_range_occupancy(), sample_cbd(), and three_share().

Referenced by main().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ measure_cbd_range_occupancy()

whitebox_reference.measure_cbd_range_occupancy (   n_seeds = 200)

Occupancy rate over many independent secrets, so the reference-sample count is not mistaken for the underlying rate.

Parameters
n_seedsNumber of independent secrets sampled.
Returns
(coordinates, in_range_count) totals across all seeds.

Definition at line 136 of file whitebox_reference.py.

References cbd_range_occupancy(), and sample_cbd().

Referenced by main().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ measure_overhead()

whitebox_reference.measure_overhead (   iters = 100000,
  seed = SEED 
)

Construction-B protected-primitive overhead (baked table lookup plus 3-share masking versus direct arithmetic) on the real full-range NTT-domain secret, for wall-clock CI aggregation (wallclock_ci.py).

Parameters
itersNumber of base multiplications timed per variant.
seedDeterministic seed.
Returns
Overhead ratio (protected / direct).

Definition at line 269 of file whitebox_reference.py.

References sample_cbd().

+ Here is the call graph for this function:

◆ ntt_forward()

whitebox_reference.ntt_forward (   poly)

Forward NTT: coefficient domain to NTT domain.

Parameters
polyLength-256 coefficient vector.
Returns
NTT-domain coefficient vector (full-range over Z_q).

Definition at line 79 of file whitebox_reference.py.

References _bitrev7().

+ Here is the call graph for this function:

◆ sample_cbd()

whitebox_reference.sample_cbd (   rng,
  size,
  eta = ETA 
)

Draw from the centered binomial distribution CBD_eta of FIPS 203.

Parameters
rngSeeded numpy Generator.
sizeNumber of coefficients.
etaDistribution parameter; 2 for the ML-KEM-768 secret.
Returns
Integer array over {-eta..eta}, distributed as sum(a_i) - sum(b_i).
Note
Not uniform over the support: CBD(2) puts 6/16 on 0, 4/16 on each of +/-1 and 1/16 on each of +/-2. Sampling uniformly over {-2..2} would share the support but not the distribution, and the manuscript states the secret is drawn from the CBD.

Definition at line 109 of file whitebox_reference.py.

Referenced by main(), measure_cbd_range_occupancy(), and measure_overhead().

+ Here is the caller graph for this function:

◆ three_share()

whitebox_reference.three_share (   v,
  rng 
)

Split a value into three arithmetic shares mod q.

Parameters
vValue;
rngNumPy Generator.
Returns
(a, b, c) with a+b+c == v mod q.

Definition at line 258 of file whitebox_reference.py.

Referenced by main().

+ Here is the caller graph for this function:

Variable Documentation

◆ CBD_RANGE

dict whitebox_reference.CBD_RANGE = {(-2) % Q, (-1) % Q, 0, 1, 2}

Definition at line 104 of file whitebox_reference.py.

◆ ETA

int whitebox_reference.ETA = 2

Definition at line 106 of file whitebox_reference.py.

◆ GAMMAS

whitebox_reference.GAMMAS
Initial value:
1= np.array(
2 [pow(ZETA, 2 * _bitrev7(i) + 1, Q) for i in range(NUM_COMPONENTS)], dtype=np.int64
3)

Definition at line 99 of file whitebox_reference.py.

◆ K

int whitebox_reference.K = 3

Definition at line 49 of file whitebox_reference.py.

◆ N

int whitebox_reference.N = 256

Definition at line 48 of file whitebox_reference.py.

◆ NUM_COMPONENTS

int whitebox_reference.NUM_COMPONENTS = N // 2

Definition at line 50 of file whitebox_reference.py.

◆ Q

int whitebox_reference.Q = 3329

Definition at line 47 of file whitebox_reference.py.

◆ SEED

int whitebox_reference.SEED = 42

Definition at line 52 of file whitebox_reference.py.

◆ ZETA

int whitebox_reference.ZETA = 17

Definition at line 51 of file whitebox_reference.py.

◆ ZETA_POWERS

whitebox_reference.ZETA_POWERS = _zeta_powers()

Definition at line 67 of file whitebox_reference.py.