hellman / wboxkit

White-box Design and Analysis kit

wboxkit: White-box Cryptography Design and Analysis kit

This project is a successor of the previous cryptolu/whitebox framework proposed at the WhibOx 2019 workshop, which was written in Python 2 and used custom Boolean circuits. The new version (this repo) is rewritten for Python 3 and also is based on the recent more generic circuit framework circkit. It also brings improved interfaces and some tutorials (first presented at the CHES 2022 White-box Cryptography tutorial, see (outdated) repo).

The primary use-case of wboxkit is research and experiments on white-box cryptography implementations. Currently, it has attacks/circuit only for AES-128, but general countermeasures (ISW03 linear masking, BU18 nonlinear masking, SEL21 nonlinear masking, BU21 dummy shuffling).

It is not yet documented, but the examples in the tutorials should be sufficient for many purposes.

Installation

It can be installed from PyPI using pip (a C extension requires a compiler and the python-dev package). It is recommended to use PyPy3 which offers much better performance.

pip install wboxkit
# or
pypy -m pip install wboxkit

For the LDA (linear algebraic / linear decoding attack) to work, it has to be installed with SageMath:

sage -pip install wboxkit
sage -sh
$ wboxkit.lda traces/

Scripts

The package installs a few scripts:

• wboxkit.trace records a set of computational traces of a given Boolean circuit (serialized in a file).
• wboxkit.exact performs the exact matching attack.
• wboxkit.lda performs the linear decoding / linear algebraic attack (LDA).

Tutorials

• Tutorial 1 - Circuits
• Tutorial 2 - Countermeasures
• Tutorial 3 - Tracing
• Tutorial 4 - Attacks

See also circkit documentation/tutorials.