Tools

Attack wrapper for Unix (Linux / Mac OS X / BSD...) and Windows

Introduction

The attack wrapper is a tool used to run and evaluate an attack. It is designed to be run on any Unix-like operating system such as Linux, Mac OS X, etc., and Windows. With this tool, you can develop your attack using almost any programming language (C, C++, Python, Perl...), or using Matlab.

Some other tools are included with the wrapper:

compute_results which analyses the results saved by the wrapper and computes the metrics used by the DPA contest
traces2text which converts a trace to a human-readable text file

Download

The current version of the wrapper is 2.2.0 (released on July 10, 2015). It can be downloaded:

For Unix (Linux, Mac OS...): attack_wrapper-2.2.0.tar.gz
For Windows: attack_wrapper-2.2.0_win.zip

To use the wrapper, you will also have to download some traces and the corresponding index file.

Requirements

In order to be able to install and use the tools, you need:

For Unix:
- A x86 or x86_64 machine (the wrapper is not yet portable to other architectures)
- A decent C++ compiler (for instance g++)
  - With Debian or Ubuntu, you need to install package: g++
  - For Mac OS, you need XCode (the integrated development environment from Apple) and its console development tools. XCode is freely available from the Mac App Store. Once it is installed, open it and go to Preferences / Downloads and install the Command Line Tools
- The libbz2 library and development files. To install them, refer to the package manager of your operating system:
  - With Debian or Ubuntu, you need to install packages: libbz2-1.0 and libbz2-dev
  - For Mac OS, it seems to be part of XCode
For Windows:
- A version of Windows greater than Windows 2000

Installation on Unix

To install the tools, open a terminal, go to the directory where you have downloaded the wrapper and type the following commands:

$ tar xzf attack_wrapper-2.2.0.tar.gz
$ cd attack_wrapper-2.2.0
$ ./configure
$ make

If everything went fine, three executable files (attack_wrapper, compute_results and traces2text) are available in the directory src. You can leave them and execute them from there or you can install them to a standard location on your system (you may need superuser privileges to perform this operation) by using the command make install.

Installation on Windows

To install the tools, you just have to unzip the archive where you want. The archive contains three pre-compiled binaries: attack_wrapper.exe, compute_results.exe and traces2text.exe.

Attack templates

Templates for developing attacks are available, for the different editions of the contest and for different languages (C, C#, Matlab...), inside the directory examples.

Use

The attack wrapper is a command line tool (even in Windows). To list all the available parameters, type (on Unix):

$ attack_wrapper --help

and on Windows:

$ attack_wrapper.exe --help

The following parameters are mandatory:

-e EDITION: Edition of the contest to use (see attack_wrapper --help for the list of available editions)
-d DIR: Path to the main directory containing the traces to use
-x FILENAME: Full path and name of the index file
The last parameter on the command line it either the filename (and path if necessary) of the attack program to launch (normal or fork mode) or the prefix of the FIFO filenames (in FIFO mode). On Windows, as only the FIFO mode is implemented, this parameter is the prefix of the FIFO filenames.

The following parameters are optional:

-i ITERATIONS: Number of traces to use (by default, the wrapper will use all the available traces for the selected key)
-k KEYNUM: Number of the key to use (refers to the list of keys in the index file, by default the wrapper use the first key available)
-o FILENAME: Name of the results file (by default: results
-t: Overwrite the results file if it exists (by default, the wrapper stops if the results file exists)
-f (Unix only): Use FIFO mode (by default, the wrapper uses the fork mode). In Windows, only the FIFO mode is implemented so it is selected by default.

Some options are specific to some editions of the contest:

--compatibility_v2 (only for edition v2): Allows the execution of attack designed for the first version of the wrapper (the number of traces is transferred using 2 bytes instead of 4)
--provide_offset_v4_rsm (only for edition v4_RSM): Provide the correct offset to the attack program (by default, the wrapper transmits 0 instead of the correct offset)
--provide_offsets_v4_2 (only for edition v4_2): Provide the correct offsets, shuffle0 and shuffle10 permutations to the attack program (by default, the wrapper transmits 0 instead of the correct offsets and permutations)
--no_float_format (only for edition v4_2): Transfer samples as integers instead of floats to the attack (this option is needed to restore the old behavior of the wrapper if you have developed attacks for DPA contest 4.2 using a version of the wrapper < 2.2.0)

Examples of use:

Unix only: DPA contest v2, 20,000 traces, key number 0, the results are written to file results_k0, the traces are read from directory DPA_contest2_public_base_diff_vcc_a128_2009_12_23, the index file is DPA_contest2_public_base_index_file and the attack program (fork mode) is attack_program:

$ attack_wrapper -i 20000 -k 0 -o results_k0 -d DPA_contest2_public_base_diff_vcc_a128_2009_12_23 -x DPA_contest2_public_base_index_file -e v2 ./attack_program

DPA contest v4, AES-256 RSM, all available traces for key number 0, the results are written to file results, the traces are read from directory DPA_contestv4_rsm, the index file is dpav4_rsm_index, FIFO mode, the two FIFOs will be named fifo_from_wrapper and fifo_to_wrapper:

$ attack_wrapper -d DPA_contestv4_rsm -x dpav4_rsm_index -e v4_RSM fifo

Once you have one or several results files, you can give them to the tool compute_results (provided with the attack wrapper) that computes the different evaluation metrics. The results are written to several files. (replace compute_results by compute_results.exe on Windows)

$ compute_results results_k0 results_k1

Communication protocol with the attack

The wrapper and the attack exchange data using the following protocol.

If the wrapper uses the fork mode (the default mode on Unix), the wrapper launches by itself the attack and redirects the attack's standard input (stdin or file descriptor 0) and standard output (stdout or file descriptor 1) to communicate. So, from the point of view of the attack, a read from its standard input retrieves information from the wrapper and a write to its standard output sends information to the wrapper.

If the wrapper uses the FIFO mode (if launches with -f or --fifo, or on Windows), the wrapper creates two special files (two fifos or pipes) to communicate with the attack. The attack must be launched manually and must open these two files (on Unix: xxx_from_wrapper in read-only mode and xxx_to_wrapper in write-only mode; on Windows: \\.\pipe\xxx_from_wrapper in read-only mode and \\.\pipe\xxx_to_wrapper in write-only mode). Next, to read data from the wrapper, the attack just have to read from the file xxx_from_wrapper (or \\.\pipe\xxx_from_wrapper on Windows) and to send data to the wrapper, the attack just have to write to the file xxx_to_wrapper (or \\.\pipe\xxx_to_wrapper on Windows). xxx is replace with the last argument on the command line of the wrapper.

For all data transfer, when the data to transfer is larger than a byte (8 bits), the endianness of the transfer is little-endian (i.e. the Least Significant Byte is transferred first).

When the attack starts, the wrapper first send 4 bytes (exact C type: uint32_t, i.e. unsigned integer) representing the number of traces that the wrapper will send to the attack during this execution. If the wrapper is launched with the option --compatibility_v2, the wrapper on sends 2 bytes instead of 4 (to keep the compatibility with the previous version of the protocol).

Next, when the attack is ready, it send the 3 following bytes to the wrapper: 0x0A 0x2E 0x0A.

Next, the wrapper sends a trace to the attack and the attack sends a result to the wrapper. This phase is repeated as many times as there are traces.

The exact representation of the traces and of the results depends on the edition of the contest (the wrapper is able to manage the different editions and implementations of the contest).

Edition	Trace structure	Results structure
v2	16 unsigned bytes representing the plaintext 16 unsigned bytes representing the ciphertext 2 * 3,253 signed byte representing the 3,253 samples of the trace, each sample is represented by two bytes (int16_t)	1 unsigned byte representing the subkey targeted by the attack (0 represents the subkey used during the first round of the AES, see the FAQ for more details) 256 unsigned bytes representing the 256 possible values for the first byte of the targeted subkey ranked from the most probable to the least probable 256 unsigned bytes representing the 256 possible values for the second byte of the targeted subkey ranked from the most probable to the least probable ... 256 unsigned bytes representing the 256 possible values for the 16th byte of the targeted subkey ranked from the most probable to the least probable
v4 RSM	16 unsigned bytes representing the plaintext 16 unsigned bytes representing the ciphertext 1 unsigned byte representing the offset (always 0 unless the wrapper is launched with the option --provide_offset_v4_rsm) 435,002 signed byte representing the 435,002 samples of the trace	1 unsigned byte representing the subkey targeted by the attack (0 represents the subkey used during the first round of the AES, see the FAQ for more details) 256 unsigned bytes representing the 256 possible values for the first byte of the targeted subkey ranked from the most probable to the least probable 256 unsigned bytes representing the 256 possible values for the second byte of the targeted subkey ranked from the most probable to the least probable ... 256 unsigned bytes representing the 256 possible values for the 16th byte of the targeted subkey ranked from the most probable to the least probable
v4 2	16 unsigned bytes representing the plaintext 16 unsigned bytes representing the ciphertext 16 unsigned bytes representing the Shuffle0 permutation (always 0...0 unless the wrapper is launched with the option --provide_offsets_v4_2) 16 unsigned bytes representing the Shuffle10 permutation (always 0...0 unless the wrapper is launched with the option --provide_offsets_v4_2) 16 unsigned bytes representing the offsets (always 0...0 unless the wrapper is launched with the option --provide_offsets_v4_2) 1,704,402 32-bit floats representing the 1,704,402 samples of the trace (1,704,402 signed bytes if the option --no_float_format is provided)	1 unsigned byte representing the subkey targeted by the attack (0 represents the subkey used during the first round of the AES, see the FAQ for more details) 256 unsigned bytes representing the 256 possible values for the first byte of the targeted subkey ranked from the most probable to the least probable 256 unsigned bytes representing the 256 possible values for the second byte of the targeted subkey ranked from the most probable to the least probable ... 256 unsigned bytes representing the 256 possible values for the 16th byte of the targeted subkey ranked from the most probable to the least probable