Traces Serialiser

Traces Serialiser is a tool that helps to generate side channel analysis traces in a format compatible with Riscure's Inspector tool.

Traces Serialiser is a C++, single header library that depends on nothing other than the standard library.

Traces Serialiser

Usage

Usage (C++)

The only file that needs to be included in your program is Traces_Serialiser.hpp located in the directory src.
To make use of it, add this line to your program

#include "Traces_Serialiser.hpp"

This requires C++17 or later.

Example Usage (C++)

This is the most basic way to use the library at the moment. There are multiple other formats of adding traces, See the API Documentation for full details.

// Two traces with three samples each.
Traces_Serialiser::Serialiser serialiser({{1,2,3},{4,5,6}});

serialiser.Save("/file/path/to/save/to");

The Serialiser object can be used as a template like so:

Traces_Serialiser::Serialiser<float> serialiser(traces);

serialiser.Save("/file/path/to/save/to");

The template parameter refers to the type of the traces. If not provided, the traces will be stored as float values. In the above example, <float> is used, indicating that the traces object is a vector of float values. Any arithmetic type can be used here.

Adding additional headers is simple as all headers have a custom function (at the time of writing). Here is an example of a few of them. A full list is available in the API Documentation.

Traces_Serialiser::Serialiser serialiser(traces);

serialiser.Set_Trace_Title("My traces");
serialiser.Set_Axis_Scale_Y(0.5f);
serialiser.Set_External_Clock_Used();

serialiser.Save("/file/path/to/save/to");

Custom headers can also be added through the Add_Header method, however this is not recommended as it is more error prone.

Traces_Serialiser::Serialiser serialiser(traces);

serialiser.Add_Header(Traces_Serialiser::Serialiser::Tag_Trace_Title,
                      "My traces");

serialiser.Add_Header(0x48, 7);

serialiser.Save("/file/path/to/save/to");

Usage (Python)

Follow the instructions in the Language Bindings section in order to generate python bindings.
Two files are required: Traces_Serialiser.py and _Traces_Serialiser.so located in the directory

/path/to/build/directory/output/bindings/python

To make use of it, add this line to your program

import Traces_Serialiser

Example Usage (Python)

Using the python bindings is slightly more complicated than in C++ but it is mostly the same.

# Two traces with three samples each.
serialiser = Traces_Serialiser.Serialiser_float([[1,2,3],[4,5,6]])

serialiser.Save("/file/path/to/save/to")

Instead of templates, there are four separate python classes. Serialiser_8, Serialiser_16 and Serialiser_32 should be used to store unsigned 8, 16 and 32 bit values. Serialiser_float should be used to store floating point values.

Adding additional headers is simple as all headers have a custom function (at the time of writing). Here is an example of a few of them. A full list is available in the API Documentation.

serialiser = Traces_Serialiser.Serialiser_32(traces)

serialiser.Set_Trace_Title("My traces")
serialiser.Set_Axis_Scale_Y(0.5)
serialiser.Set_External_Clock_Used()

serialiser.Save("/file/path/to/save/to")

Custom headers can also be added through the Add_Header method, however this is not recommended as it is more error prone.

serialiser = Traces_Serialiser.Serialiser_16(traces)

serialiser.Add_Header(Traces_Serialiser.Serialiser_8.Tag_Trace_Title,
                      "My traces")

serialiser.Add_Header(0x48, 7)

serialiser.Save("/file/path/to/save/to")

Other Languages

Support for other languages can be added upon request providing they are supported by SWIG.

API Documentation

Documentation is generated using Doxygen. In order to generate this follow these instructions:

Firstly follow the instructions in the Getting started for Development section.
Documentation can be built with CMake using the "doc" target by running the command as shown.

cmake --build . --target doc

Open this file

/path/to/build/directory/doc/html/index.html

Additionally, the cmake configuration option Traces-Serialiser_BUILD_DOCUMENTATION will generate the documentation every time you compile.

Getting started for development

Prerequisites

This uses CMake. As such, CMake needs to be installed first.

Linux

The recommended way of installing CMake is through your package manager.

If a CMake package isn't available on your Linux distribution follow the official CMake install instructions.

MacOS

CMake can be installed using Homebrew with the following command.

brew install cmake

Alternatively, follow the official CMake install instructions.

Windows

Follow the official CMake install instructions.

Building

The library does not need to be built to be used. This section is only needed for building tests, language bindings and documentation.

Create an empty build directory.
From the build directory run this command. This will generate native build files for your platform. A specific generator can be specified using the -G *generator* flag. A [list of generators is available here.] (https://cmake.org/cmake/help/latest/manual/cmake-generators.7.html)

cmake /path/to/source/directory/

Run this command to compile the code. This will compile the program using your chosen generator e.g. make. Alternatively the native build system can be used manually from this point on.

cmake --build .

Language Bindings

In order to support languages other than C++, wrapper code needs to be generated. This can be done using SWIG.

Firstly follow the instructions in the Getting started for Development section.
Ensure that SWIG is installed.
Generate the bindings with this command. This will tell the native build system to build the target called bindings which will run SWIG for you.

cmake --build . --target bindings

Running tests

Firstly follow the instructions in the Getting started for Development section.
Build the tests with this command. This will tell the native build system to build the target called tests.

cmake --build . --target tests

Run the tests

/path/to/build/directory/output/tests

Coverage information

In order to generate code coverage information, Gcovr is required.

Regenerate the build files using the option shown below from the build directory. This is needed as specific compile flags need to be added in order to generate coverage information.

cmake /path/to/source/directory/traces_serialiser -DTraces-Serialiser_CALCULATE_COVERAGE=ON

Run this command. This will tell the native build system to build the target called coverage.

cmake --build . --target coverage

Coverage information can be found by opening the file coverage.html in the folder coverage which should have been created in your build directory.

/path/to/build/directory/coverage/coverage.html

Configuration Options

These are all CMake options and can be appended to the CMake generate command. For example, from the build directory:

cmake /path/to/source/directory/ -DTraces-Serialiser_BUILD_DOCUMENTATION