CHES 2022 - White-box Cryptography Tutorial

Authors: Matthieu Rivain and Aleksei Udovenko

This repository contains preparation instructions and notebooks for the WBC tutorial at CHES 2022.

---

Warning: this is an archive repository and is outdated. See wboxkit repo for updated library and tutorials.

---

Note: the repository is currently assembled primarily for the tutorial at CHES 2022; a large part of the tutorial should be runnable with just pip install circkit wboxkit and the jupyter lab / notebook. However, some parts (e.g. wboxkit.fastcircuit compilation) are not yet automatically built when installing from pip (will be fixed soon).

The main repository for circkit is: github.com/cryptoexperts/circkit The tutorial was prepared using a local copy of circkit in this repository, but pip install circkit should also work.

Minimal Setup (pure Python)

Might be slow and LDA won't work.

sudo apt install graphviz

pip install jupyterlab binteger pycryptodome graphviz

Running notebooks:

jupyter lab

Running tools/attacks:

export PYTHONPATH=.:$PYTHONPATH
python3 tools/trace.py ...
python3 attacks/analyze_exact.py ....

Setup (using Docker)

The simplest is to use the prepared docker image.

WARNING: as the image is quite large (4.5 GiB) due to SageMath, it is recommended to download it in advance:

sudo docker pull hellman1908/ches2022wbc

Then, run as follows:

git clone https://github.com/hellman/ches2022wbc

# run Jupyter Notebook
sudo docker run -it \
	--network=host \
	-v `pwd`/ches2022wbc:/home/user/ches2022wbc \
	hellman1908/ches2022wbc

# run shell
sudo docker run -it \
	--network=host \
	-v `pwd`/ches2022wbc:/home/user/ches2022wbc \
	hellman1908/ches2022wbc /bin/bash

Then, Ctrl+Click or copy/paste the link http://127.0.0.1:9999/lab?token=....

Alternatively, a lightweight image (without SageMath) can be installed:

sudo docker pull hellman1908/ches2022wbc_nosagemath
git clone https://github.com/hellman/ches2022wbc
sudo docker run -it \
	--network=host \
	-v `pwd`/ches2022wbc:/home/user/ches2022wbc \
	hellman1908/ches2022wbc_nosagemath

Note: without host network, try running

sudo docker run -it \
	-p 127.0.0.1:9999:9999 \
	-v `pwd`/ches2022wbc:/home/user/ches2022wbc \
	hellman1908/ches2022wbc_nosagemath \
	jupyter lab --no-browser --port=9999 --ip=127.0.0.1

Setup (using Linux)

Recommended:

1. Install SageMath (only needed for linear algebraic attack)
2. Install pypy3 (much faster circuit gen. and attacks)

Required:

1. Install jupyter lab (any python env.)

pip install jupyterlab

2. Install ipykernel for the pypy3 interpreter, e.g.:

pypy3 -m pip install -U pip
pypy3 -m pip install -U pycryptodome binteger ipykernel jupyter_client
pypy3 -m ipykernel install --prefix=$HOME/.local/ --name 'pypy3'

jupyter kernelspec list

3. Clone this repository and compile the fastcircuit library:

git clone https://github.com/hellman/ches2022wbc
cd ches2022wbc
make

3. Test running jupyter as

jupyter lab

Then, Ctrl+Click or copy/paste the link http://127.0.0.1:9999/lab?token=....

You can also try opening the Tutorial 0 - Test Setup.ipynb in the ches2022wbc repository, and executing the code cell.