Skip to main content

Traces and trace header set Python library for side-channel analysis.

Project description

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

pipeline status PyPI version Conda installer Latest Conda release

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

# 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


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


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


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!


See AUTHORS for the list of contributors to the project.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for estraces, version 1.6.4
Filename, size File type Python version Upload date Hashes
Filename, size estraces-1.6.4-py3-none-any.whl (51.2 kB) File type Wheel Python version py3 Upload date Hashes View
Filename, size estraces-1.6.4.tar.gz (28.1 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring DigiCert DigiCert EV certificate Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page