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 scared.

Getting started

Requirements and installation

estraces requires Python 3.10 or higher (3.10, 3.11, 3.12, 3.13).

The library uses modern Python packaging standards (PEP 517/518/621) with pyproject.toml and requires:

• NumPy 2.0 or higher
• Python 3.10+

You can install it by several ways:

• with pip (recommended)
• with conda
• from source

Installing with pip

Simply install using pip:

pip install estraces

For the latest development version:

pip install git+https://gitlab.com/eshard/estraces.git

Installing from source

To install estraces from source, you will need:

• Python 3.10 or higher
• pip and build tools

Clone the repository and install:

git clone https://gitlab.com/eshard/estraces.git
cd estraces
pip install .

For development (editable install with test dependencies):

pip install -e ".[test]"

Installing with conda

To install from conda:

conda install -c eshard estraces

Or create a new environment with estraces:

conda create -n myenv python=3.10 -c eshard estraces
conda activate myenv

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.