README

TraceTools is a set of tools for power trace analysis.

Features

PlotTraces (utils/plot_traces) is a graphical viewer that supports viewing power traces stored as NumPy, Inspector TRS or plain text.
Static alignment of signals.
Use of pattern matching to find similar regions within a signal.
Zero phase filter application on signals
Welch's T-tests in unvariate, bivariate and trivariate configurations (with or without normalisation)
Pearson's Chi Square test.
Conversion between Numpy and Inspector TRS power trace formats.
Correlation Power Analysis (CPA) attacks.
Compress power traces by calculating overlapping moving average.

Install

TraceTools

Before building TraceTools, install the dependencies by running the following command (only in Debian like systems, you may have to find correct package names for other distributions).

TraceTools have only been tested on Ubuntu but will work on other systems with minimal changes.

sudo apt install libboost-filesystem-dev libboost-math-dev libfftw3-dev libeigen3-dev cmake

Build the thirdparty iir1 library by running the following commands,

git submodule update --init --recursive
cd thirdparty/iir1
mkdir base 
mkdir build
cd build
cmake .. -DCMAKE_INSTALL_PREFIX=<path_to_trace_tools>/thirdparty/iir1/base
make install

Build TraceTools by running make in ./src directory. You may optionally use PARALLEL=1 to enable OpenMP based parallelism.

make -e 'PARALLEL=1'

Then use make install to install TraceTools to a directory, you may optionally use PREFIX to set installation directory.

make -e 'PREFIX=/home/user/tracetools' install

PlotTraces

The following Python 3 dependencies are required to run PlotTraces. Once these are met, it can be run by executing ./utils/plot_traces.

numpy
pyqtgraph
pandas
trsfile

Usage

TraceTools operates on files with power traces. These files and be either NumPy or Inspector TRS files. Output files will be written as NumPy trace files.

traceprocessor [options] <command> <trace-file>

File formats

Power traces in the NumPy format may have an additional text file accompanying data for each power traces. The filename must be the original NumPy file's name suffixed with .data. Each line holds the byte data in a hex string and each line represents the data for the corresponding power trace in the NumPy file.

Inspector TRS file format is described here.

Commands

List of all commands

univfott - univariate first order t-test
bivfott - bivariate first order t-test
bivfott,mt - bivariate first order t-test multi-threaded
trivfott - trivariate first order t-test
filter - apply zero phase filtering on power traces (highpass or lowpass)
convert - convert between NumPy and TRS files
compress - compress power traces by calculating overlapping moving average
corr - CPA attack on power traces
normcombfott - first order t-test on normalised and combined power traces
normcombcorr - CPA attack on normalised and combined power traces
chisq - chi square test on power traces
staticalign - statically align power traces
patternmatch - find similar looking regions in power traces and output all matching regions only

Switches for commands

Common to all commands

-e, --at-each-ntraces Output to file at each 'n' number of traces
-F, --force-space Force operations when there's not enough space
-r, --trace-range Run only for given range of traces (start, length)
-s, --sample-range Run only on samples window (start, length)
-f, --filter-group Filter by group (byte 1 of data), [0x00, 0xff]
-x, --sample-combinations Combine samples of each trace a given number of times, [1, 3]
-y, --sample-window Combine sample windows of each trace (use with -x)
-w, --moving-avg-wind Set value of moving average window size
-d, --data-range Range of data indexes that are used for correlation, stdin needs to be fed with (end - start + 1) model values (i.e. Hamming weight) for each trace
-c, --convert-to Conversion target
-l, --libname Module library name
-u, --guess-count Guess count, [1, 256]
-g, --groups Number of trace groups (default is 2), when larger than 0 the group count is the first byte of data, [1, 256]

`filter` Command

--filter-type Filter type [lowpass, highpass, bandstop]
--filter-samplerate Filter samplerate in Hz
--filter-cutoff Filter cutoff frequency in Hz (only in highpass, lowpass)
--filter-center Filter center frequency (only in bandstop)
--filter-width Filter width (only in bandstop)

`staticalign` & `patternmatch` Commands

--align-ref-range Range of reference window for static alignment
--align-min-corr Minimum level of correlation for NCC (Normalised Cross Correlation) (default: 0.8)

`staticalign` Command

--align-search-in Search range, [start, end)
--align-max-shift Maximum allowed shift (default: inf)

`patternmatch` Command

--pattern-matches Match N number of NCC (Normalised Cross Correlation) peaks (default: 1)
--pattern-padding Start and end padding for each matched pattern (default: 0, 0)

`chisq` Command

--chisq-min Mininum value for all samples
--chisq-div Divisor that normalizes all samples

Examples

Run a univariate t-test, a resulting t-test trace is output for each 20000 input traces.

traceprocessor -e 20000 univfott traces.npy

Run CPA attack on samples in traces.npy. The data used for each trace is in traces.npy.data. Since the data is not grouped, -g 1 so that the mean calculation considers the whole trace file as one group.

python3 hw.py traces.npy.data | traceprocessor -x 1 -g 1 -u 256 -d 0 0 normcombcorr traces.npy

Run Chi Sqaure test for traces 0 thorugh 500000 in traces.npy. The minimum value in traces.npy is -80000 and the normilizing factor is 160000. In other words, reducing -80000 and then dividing each sample by 160000 will produce a value in the range [0, 1].

traceprocessor -r 0 500000 --chisq-min -80000 --chisq-div 160000 -e 20000 chisq traces.npy

0xADE1A1DE/tracetools