estraces - Traces and trace sets Python library for side-channel attacks

estraces is a Python library to manipulate side-channel trace sets. It aims at giving a clear and uniform API to handle traces samples and metadata for various persistency and file formats. It uses Numpy to handle data.

estraces was originally developped and maintain by eshard, and is heavily used in the open-source side-channel analysis framework.

Getting started

Requirements and installation

estraces requires and must work on Python 3.6, 3.7 and 3.8 versions.

You can install it by several ways:

• from source
• with pip
• with conda

At time of writing, we highly recommend to install from conda when using estraces with python 3.8.

Installing from source

To install estraces from source, you will need the following requirements:

• pip and setuptools with version greater than 40.0
• For Python 3.8, you'll need to build and install h5py from source see H5PY installation instructions before installing estraces

From the source code folder, run:

pip install .

Installing with pip

First, you should update your pip and setuptools version:

pip install -U pip setuptools

If you use Python 3.8, you must first build and install h5py, see instructions.

pip install estraces

Installing with conda

To install from conda, simply run:

conda install -c eshard estraces

Opens a trace set

If you have a trace set as binary files, you can get a trace header set by using the binary reader:

# First import the lib
import estraces

# We suppose the binary files are under traces/ and are named something.bin
my_traces = estraces.read_ths_from_bin_filenames_pattern(
    'traces/*.bin', # First indicate the filename pattern for the bin file
    dtype='uint8', # Indicate the numpy dtype of the data
    metadatas_parsers={} # This dict allows to associate metadata
)

You can then read your samples:

# This will return the data for the first 100 traces
my_traces.samples[:100]

# This will return the frame 0 - 1000 of all the traces as a numpy array
my_traces.samples[:, :1000]

# You can iterate on traces
for trace in my_traces:
    # do something

Documentation

To go further and learn all about estraces, please go to the full documentation.

Contributing

All contributions, starting with feedbacks, are welcomed. Please read CONTRIBUTING.md if you wish to contribute to the project.

License

This library is licensed under LGPL V3 license. See the LICENSE file for details.

It is mainly intended for non-commercial use, by academics, students or professional willing to learn the basics of side-channel analysis.

If you wish to use this library in a commercial or industrial context, eshard provides commercial licenses under fees. Contact us!

Authors

See AUTHORS for the list of contributors to the project.