Transactions on Cryptographic Hardware and Embedded Systems 2025
Adaptive Template Attacks on the Kyber Binomial Sampler
README
Adaptive Template Attacks on the Kyber Binomial Sampler
Eric Chun-Yu Peng, Markus G. Kuhn
This repository contains the Julia code
needed for reproducing the experiments described in our paper
Eric Chun-Yu Peng, Markus G. Kuhn: Adaptive Template Attacks on the
Kyber Binomial Sampler.
IACR Transactions on Cryptographic Hardware and Embedded
Systems, Vol. 2025, No. 3.
Requirements
This code was mainly developed and tested on x86-64 (64-bit)
computers running Ubuntu Linux 20.04 or 24.04 with 48 GB RAM. We hope
it will run on any platform that is supported by
Julia and has
at least 16 GB RAM. About 25 GB disk space would be ideal, but there
are also ways to run the demo with only about 12 GB disk space.
Install Julia
To run this code, you will need Julia
(version 1.11 or newer).
For Linux or macOS, best install
Julia via the
juliaup
installation manager using the following shell command line:
$ curl -fsSL https://install.julialang.org | sh
Download this repository
Clone this repository and its submodules to your local machine, then install
(“instantiate”) the required Julia package dependencies for this project
into your Julia depot path (default: ~/.julia/):
$ git clone --recursive https://github.com/eric-cyp24/Kyber768cbd.jl.git
$ cd Kyber768cbd.jl
$ julia --project -e "import Pkg; Pkg.instantiate()"
Download trace data for DK2 and MS2
This repository contains only Julia code. To reproduce some of the
experiments from the paper, you also need to separately download the
data used.
The following Julia script will download preprocessed traces for two
devices (4000 traces to profile DK2 and 1000 traces each to attack
KeyGen (K) and Encaps (E) on MS2). It will also download pre-built
post-LDA templates for the other devices.
(The downloaded traces have already been downsampled from 2.5 GHz to
100 MHz using a Lanczos anti-aliasing filter, and have then been cut
into 48 segments each, as detailed in sections 3, 4.3 and 5.3 of the
paper.)
The script will download this data into the folder data/ (into
subfolder Traces/), unless you specify another folder using the
environment variable DATA_DIR. This folder will later also be used
for temporary data.
Choose one of the following options, depending on how much disk space
you have:
- Option 1: if you have the space, download all provided data at once with ``` $ julia --project scripts/downloaddata.jl # requires 19 GB ```
- Option 2: download data needed for profiling and attack separately, as indicated below, using the options ``` $ julia --project scripts/downloaddata.jl --profiling # requires 8.1 GB $ julia --project scripts/downloaddata.jl --attack # requires 4.9 GB ``` right before the profiling and attack steps. You can then remove them immediately after the corresponding processing step, to reduce the required disk space, using ``` $ julia --project scripts/deletedata.jl --profiling # frees 8.1 GB $ julia --project scripts/deletedata.jl --attack # frees 4.9 GB ``` respectively. The above allows you to reproduce all the attacks against the MS2 device, as well as the profiling steps for the DK2 device. **Optional:** You can also download the profiling and attack outcomes, including all the LDA projections and adjusted template parameters for all the other profiling and target device combinations: ``` $ julia --project scripts/downloaddata.jl --results # requires 6.0 GB ```
Build tables 2 and 3
You can run the following Julia script to generate the LaTeX table source code
for tables 2 and 3, and pdflatex to generate these tables as
results/SuccessRateTables.pdf.
$ julia --project scripts/h5result2latextable_multiboardsingletrace.jl
$ pdflatex -output-directory results scripts/SuccessRateTables.tex
If you downloaded the results for other target devices than MS2, you
should see those columns already completed:
To complete the still missing MS2 columns:
- First, build the DK2 profiling templates with the following profiling step.
- Then, run the single-trace attacks on the MS2 target with templates from all
devices (DK1–RS2).
Profiling
Build the LDA-based templates from profiling traces of device DK2:
data/Traces/SOCKET_HPF/DK2/test_20241219/lanczos2_25/traces_lanczos2_25_proc.h5.
The resulting templates will be stored in the folder
data/Traces/SOCKET_HPF/DK2/test_20241219/lanczos2_25/Templates_POIe40-80/.
$ julia --project scripts/downloaddata.jl --profiling # for Option 2 only
$ julia --project scripts/profiling_kyber768cbd.jl
$ julia --project scripts/deletedata.jl --profiling # for Option 2 only
Single-trace attacks
Run the single-trace attacks on the MS2 target device:
$ julia --project scripts/downloaddata.jl --attack # for Option 2 only
$ julia --project scripts/attack_kyber768cbd_Buf_singletrace.jl
You can speed up the attack by running Julia with multiple threads:
$ julia --project -t4 scripts/attack_kyber768cbd_Buf_singletrace.jl
Option -t4 tells Julia to execute with 4 threads.
Adjust this based on your computer's resources, i.e. speed up the
computation with more threads or decrease RAM usage with fewer.
Each attack trace set (table cell) takes 3–15 minutes to finish.
Therefore, this script may run for a while (roughly 4–5 hours on
our computers).
The attack results will be stored as HDF5 files in folder
data/Traces/SOCKET_HPF/MS2/test_20241221/lanczos2_25_test_K/Results/Templates_POIe40-80/.
To see more detailed attack metadata, use an HDF5 viewer, e.g.
HDFView Software or
myHDF5 online viewer; or open the file
directly with the HDF5.jl package
in Julia, as in
$ julia --project
julia> using HDF5
julia> h = h5open("data/Traces/SOCKET_HPF/MS2/test_20241221/lanczos2_25_test_K/Results/Templates_POIe40-80/marginalize_Buf_Result_with_Templates_POIe40-80_from_SOCKET_HPF_DK2_test_20241219.h5")
julia> h["Traces_Normalized_Templates_Adj_EM"]["success_rate_single_trace"][]
0.777
Attacking the Encaps operation
To attack the Encaps operation (Table 3 above), run the same attack
script with the additional command line argument: --targetOP Encaps
$ julia --project scripts/attack_kyber768cbd_Buf_singletrace.jl --targetOP Encaps
Generate (LaTeX) tables
To view the single-trace attack results, run the following code (again) to
generate results/SuccessRateTables.pdf with the newly produced success
rates:
$ julia --project scripts/h5result2latextable_multiboardsingletrace.jl
$ pdflatex -output-directory results scripts/SuccessRateTables.tex
Adaptive template attack evaluation
To view the effect of the EM-based template adjustment, run the following
script:
$ julia --project scripts/figure_emadj_templates.jl --variable XY --output results/traces_and_XY_templates.png
This generates the before-and-after plots (a) and (b) from Figure 5,
stored in the results/ folder as
traces_and_XY_templates.png and traces_and_XY_templates_EMadj.png.
If you want to see the effect of EM template adjustment on a lower-leakage
intermediate variable (iv), modify the command line options for the script:
$ julia --project scripts/figure_emadj_templates.jl --variable X --output results/traces_and_X_templates.png
You should now see plots (c) and (d) from Figure 5 in
traces_and_X_templates.png and traces_and_X_templates_EMadj.png,
also in the results/ folder, similar to the ones shown below.
