SICAK: SIde-Channel Analysis toolKit 1.1

User's Guide

Contents

  1. Introduction
  2. meas (Usage, Oscilloscope configuration, Character device configuration, Examples)
  3. prep (Usage, Examples)
  4. stan (Usage, Examples)
  5. correv (Usage, Examples)
  6. visu (Usage, Examples)
  7. chardevice (meas) plug-ins (serialport, smartcard)
  8. oscilloscope (meas) plug-ins (keysight3000, ps6000)
  9. measurement (meas) plug-ins (random128co, ttest128co, random128apdu, ttest128apdu)
  10. blockprocess (prep) plug-ins (predictaes128back, predictaes128front)
  11. tracesprocess (prep) plug-ins
  12. cpaengine (stan) plug-ins (cpa, oclcpa)
  13. ttestengine (stan) plug-ins (ttest)
  14. cpacorreval (correv) plug-ins (maxabscoef, maxcoef, maxedge, mincoef)
  15. cpakeyeval (correv) plug-ins (aes128back, plainchar)
  16. Tips
  17. License
  18. Contact
back to top ↑

1. Introduction

Sicak is a side-channel analysis toolkit, consisting of following text-based utilities:

These utilities are moreless interfaces for different types of plug-in modules:

Following sections document usage of the utilities and currently available plug-in modules.

back to top ↑

2. meas

meas is a measurement utility. It runs a measurement scenario module, which may produce different output files.

The Measurement scenario gets an Oscilloscope and Character Device instances, if they are set. Most of the measurement scenarios is expected to require both modules to be set. Both oscilloscope and character device need to be initialized (appropriate device id must be set), and may be configured (if configuration file is set).

back to top ↑

Usage

Brief usage is also printed when the program is run with -h option.

./meas [options] config

Options

-I, --id {string}

The ID string will be used in output files' filenames. Default value is current datetime.

-Q, --query

Query available traces and block data preprocessing plug-in modules (-M, -O, -C).

-M, --measurement-module {string}

ID of measurement scenario plug-in module to use.

-O, --oscilloscope-module {string}

ID of oscilloscope plug-in module to use.

-R, --oscilloscope-device {string}

ID of oscilloscope device to use.

-S, --oscilloscope-config {filepath}

Oscilloscope JSON configuration file.

See below for config file format.

-C, --chardevice-module {string}

ID of character device plug-in module to use.

-D, --chardevice-device {string}

ID of character device to use.

-E, --chardevice-config {filepath}

Character device JSON configuration file.

See below for config file format.

-n, --measurements {positive integer}

Number of measurements to make.

--param {param}

Optional measurement plug-in module parameters. Module specific option.

-h, --help

Displays help.

-v, --version

Displays version information.

Arguments

config

JSON configuration file(s) with Options.

The JSON configuration file may contain key:string pairs, where key is a long option name and string is the value.

For example: { "id":"myMeasurement" }

back to top ↑

Oscilloscope configuration file

The utility expects a JSON config file.

Format

JSON document may contain following objects, with following key:vals.

When an object is defined (e.g. "channel1"), all it's settings must be set.

Example of a JSON config file

{

    "channel1": {
        "enabled": true,
        "coupling": "DC",
        "impedance": "50",
        "rangemV": 50,
        "offsetmV": 0,
        "bwLimit": "25MHz"
    },

    "channel2": {
        "enabled": false,
        "coupling": "DC",
        "impedance": "1M",
        "rangemV": 50,
        "offsetmV": 0,
        "bwLimit": "FULL"
    },

    "channel3": {
        "enabled": true,
        "coupling": "DC",
        "impedance": "1M",
        "rangemV": 1000,
        "offsetmV": 0,
        "bwLimit": "FULL"
    },

    "channel4": {
        "enabled": false,
        "coupling": "DC",
        "impedance": "1M",
        "rangemV": 50,
        "offsetmV": 0,
        "bwLimit": "FULL"
    },

    "trigger": {
        "enabled":true,
        "channel": 3,
        "level": 0.7,
        "slope": "rising"
    },

    "timing": {
        "preTriggerRange": 0.0,
        "postTriggerRange": 3.2e-6,
        "samples": 2000,
        "captures": 1
    }

}
back to top ↑

Character device configuration file

The utility expects a JSON config file.

These are the values that may be set. Not all the Character Device modules have to consider them. Read module documentation to find out more.

Format

JSON document may contain following key:vals.

Example of a JSON config file

{
    "baudrate": 115200,
    "parity": 0,
    "stopbits": 1
}
back to top ↑

Examples

Query available plug-ins

$ ./meas -Q

Found following measurement scenario plug-ins:

* Plug-in ID: 'random128co', name: 'AES-128 random (command oriented)'
    Description: 'Sends 0x01 followed by cipher key, then N times {0x02 followed by 128 bits of random data}, receives back every cipher text, and captures the power consumption.'

* Plug-in ID: 'ttest128co', name: 'AES-128 t-test (command oriented)'
    Description: 'Sends 0x01 followed by cipher key, then N times {0x02 followed by 128 bits of either random or constant data}, receives back every cipher text, and captures the power consumption'


Found following oscilloscope plug-ins:

* Plug-in ID: 'keysight3000', name: 'Keysight 3000 series oscilloscope (formerly Agilent)'
    * Device ID: 'FILEPATH', where FILEPATH is path to a usbtmc device, e.g. "/dev/usbtmc0"
     Make sure you have permissions to access the file, and the usbtmc module loaded.

* Plug-in ID: 'ps6000', name: 'PicoScope 6000 series oscilloscope'
    * Device ID: 'SERIALNO', where SERIALNO is a serial number of the oscilloscope. Leave empty to let driver automatically select first device found.
     On Linux, make sure you have permissions to access the device (/dev/usb/...).


Found following character device plug-ins:

* Plug-in ID: 'serialport', name: 'Win32/POSIX Serial Port'
    * Device ID: 'FILEPATH', where FILEPATH is path to a terminal device, e.g. "/dev/ttyUSB0"

Launch measurement

This command launches the ttest128co measurement scenario using ps6000 oscilloscope and serialport chardevice modules. $ ./meas -I id -M ttest128co -O keysight3000 -R /dev/usbtmc0 -S ./conf.json -C serialport -D /dev/ttyUSB0 -E ./conf.json -n 1000
SICAK MEASurements 1.0
* 20.12.2018 18:25:01 Starting...
* Measurement scenario module loaded: 'AES-128 t-test (command oriented)'
* Oscilloscope module loaded: 'Keysight 3000 series oscilloscope (formerly Agilent)'
* Oscilloscope successfully opened: '/dev/usbtmc0'
* Oscilloscope configuration file found: './conf.json'
    * Requesting oscilloscope channel settings:
        * Channel: '1'
        * Enabled: 'true'
        * Coupling: 'DC'
        * Impedance: '50'
        * Range: -+'50mV'
        * Offset: '0mV'
        * Bandwidth Limit: '25MHz'
    * Real oscilloscope channel settings (after setup):
        * Channel: '1'
        * Enabled: 'true'
        * Coupling: 'DC'
        * Impedance: '50'
        * Range: -+'50mV'
        * Offset: '0mV'
        * Bandwidth Limit: '25MHz'
    * Requesting oscilloscope channel settings:
        * Channel: '3'
        * Enabled: 'true'
        * Coupling: 'DC'
        * Impedance: '1M'
        * Range: -+'1000mV'
        * Offset: '0mV'
        * Bandwidth Limit: 'FULL'
    * Real oscilloscope channel settings (after setup):
        * Channel: '3'
        * Enabled: 'true'
        * Coupling: 'DC'
        * Impedance: '1M'
        * Range: -+'1000mV'
        * Offset: '0mV'
        * Bandwidth Limit: 'FULL'
    * Requesting oscilloscope trigger settings:
        * Enabled: 'true'
        * Source channel: '3'
        * Trigger level: '0.7' for channel range 0..1
        * Edge slope: 'either'
    * Real oscilloscope trigger settings (after setup):
        * Enabled: 'true'
        * Source channel: '3'
        * Trigger level: '0.7' for channel range 0..1
        * Edge slope: 'either'
    * Requesting oscilloscope timing settings:
        * Pre-trigger time range: '0s'
        * Post-trigger time range: '3.2e-06s'
        * Samples: '2000'
        * Captures per run: '100'
    * Real oscilloscope timing settings (after setup):
        * Pre-trigger time range: '0s'
        * Post-trigger time range: '3.2e-06s'
        * Samples: '30000'
        * Captures per run: '1'
* Character device module loaded: 'Win32/POSIX Serial Port'
* Character device configuration file found: ./conf.json
* Character device successfully opened: '/dev/ttyUSB0'
    * Using following settings:
        * Baudrate: '115200'
        * Parity: 'no parity'
        * Stop bits: 'one'
* Character device timeout set: '5000ms'
* Launching 1000 measurements...
0% done... remaining time not yet available

conf.json: (input)

{
    "channel1": {
        "enabled": true,
        "coupling": "DC",
        "impedance": "50",
        "rangemV": 50,
        "offsetmV": 0,
        "bwLimit": "25MHz"
        },

    "channel3": {
        "enabled": true,
        "coupling": "DC",
        "impedance": "1M",
        "rangemV": 1000,
        "offsetmV": 0,
        "bwLimit": "FULL"
        },

    "trigger": {
        "enabled":true,
        "channel": 3,
        "level": 0.7,
        "slope": "either"
        },

    "timing": {
        "preTriggerRange": 0.0,
        "postTriggerRange": 3.2e-6,
        "samples": 2000,
        "captures": 100
        },

    "baudrate": 115200,
    "parity": 0,
    "stopbits": 1
}

id.json: (output)

{
    "blocks-count": "643",
    "blocks-length": "16",
    "constant-traces": "constant-traces-id.bin",
    "constant-traces-count": "357",
    "random-traces": "random-traces-id.bin",
    "random-traces-count": "643",
    "samples-per-trace": "2000"
}
back to top ↑

3. prep

prep is a data preprocessing utility.

It loads either blocks of (char) data and processes them using Block Preprocessing Module, or it loads power traces containing (int16_t) samples and processes them using Traces Preprocessing Module.

back to top ↑

Usage

Brief usage is also printed when the program is run with -h option.

./prep [options] config

Options

-I, --id {string}

The ID string will be used in output files' filenames. Default value is current datetime.

-Q, --query

Query available traces and block data preprocessing plug-in modules (-T, -B).

-T, --traces-preprocess-module {string}

ID of traces preprocessing plug-in module to use. Select either -T or -B.

-B, --block-preprocess-module {string}

ID of block data preprocessing plug-in module to use. Select either -T or -B.

-t, --traces {filepath}

File containing -n traces, each of which containing -s samples (int16).

-n, --traces-count {positive integer}

Number of power traces in -t file.

-s, --samples-per-trace {positive integer}

Number of samples per trace.

-b, --blocks {filepath}

File containing -m blocks of data, each of which -k bytes long.

-m, --blocks-count {positive integer}

Number of blocks of data in -b file.

-k, --blocks-length {positive integer}

Length of data block in -b file, in bytes.

--param {param}

Optional plug-in module parameters. Module specific option.

-h, --help

Displays help.

-v, --version

Displays version information.

Arguments

config

JSON configuration file(s) with Options.

The JSON configuration file may contain key:string pairs, where key is a long option name and string is the value.

For example: { "blocks-length":"16" }

back to top ↑

Examples

Query available plug-ins

$ ./prep -Q

Found following traces preprocessing plug-ins:

* No traces preprocessing plug-in found!

Found following block data preprocessing plug-ins:

* Plug-in ID: 'predictaes128back', name: 'Create AES-128 byte power predictions using last round working register Hamming distance'
* Plug-in ID: 'predictaes128front', name: 'Create AES-128 byte power predictions using first round S-Box Hamming weight'

Create power predictions for CPA attack on AES-128 first round S-box

$ ./prep -B predictaes128front -b ciphertext-id.bin -m 100000 -k 16 -I id
SICAK PREProcessing 1.0
Preprocessing block data...
100% done... 3s elapsed.
Created 16 power prediction sets, each containing 256 power predictions for each of 100000 data blocks,
and saved to 'aes128front-id.16prd'.

id.json: (output)

{
    "prediction-candidates-count": "256",
    "prediction-sets-count": "16",
    "predictions": "aes128front-id.16prd",
    "random-traces-count": "100000"
}
back to top ↑

4. stan

stan is a statistical processing utility.

The utility loads one of the two different types of plug-in modules (CPA, t-test) and runs one of the tasks:

It loads either CPA module or t-test module. Then it runs one of the functions (create, merge, finalize) on a specified computational device.

back to top ↑

Usage

Brief usage is also printed when the program is run with -h option.

./stan [options] config

Options

-I, --id {string}

The ID string will be used in output files' filenames. Default value is current datetime.

-Q, --query

Query available CPA and t-test plug-in modules (-C, -T), platforms (-P) and devices (-D).

-C, --cpa-module {string}

ID of a CPA plug-in module to launch. Select either -C or -T.

-T, --ttest-module {string}

ID of a t-test plug-in module to launch. Select either -C or -T.

-P, --platform {positive integer}

Platform from which to choose a device (-D). Default is 0.

-D, --device {positive integer}

Device from a platform (-P) to run computation on. Default is 0.

-F, --function {create|merge|finalize}

Select a function:

-r, --random-traces {filepath}

File containing -n random data traces, each of which containing -s samples (int16).

-n, --random-traces-count {positive integer}

Number of random data power traces in -r file.

-c, --constant-traces {filepath}

File containing -m constant data traces, each of which containing -s samples (int16).

-m, --constant-traces-count {positive integer}

Number of constant data power traces in -c file.

-s, --samples-per-trace {positive integer}

Number of samples per trace.

-p, --predictions {filepath}

File containing -q power prediction sets, each of which containing -k power predictions (uint8) for every random trace in -r file.

-q, --prediction-sets-count, --contexts-count {positive integer}

Number of power prediction sets/number of contexts. E.g. attacking AES-128 key, this value would be 16.

-k, --prediction-candidates-count {positive integer}

Number of power predictions for each power trace in -p file. E.g. attacking AES-128 key, this value would be 256.

-a, --context-a {filepath}

Context file A, for use in Finalize or Merge functions.

-b, --context-b {filepath}

Context file B, for use in Merge function.

--param {param}

Optional plug-in module parameters. Module specific option.

-h, --help

Displays help.

-v, --version

Displays version information.

Arguments

config

JSON configuration file(s) with Options.

The JSON configuration file may contain key:string pairs, where key is a long option name and string is the value.

For example: { "random-traces-count":"10000" }

Output

stan produces following files:

where ID is stan given parameter or default, and Q is number of power prediction sets/contexts created (when Q=1, it's omitted).

.Qcor files contain Q correlation matrices, each SxK large, where Q is number of power prediction sets, S is number of samples per trace and K is number of key candidates.

.tvals file contain Sx2 matrix, where S is number of samples per trace, where in the first row there are t-values, in the second row there are degrees of freedom.

back to top ↑

Examples

Query available plug-ins

$ ./stan -Q

Found following CPA plug-ins, platforms and devices:

* Plug-in ID: 'cpa', name: 'First Order Univariate CPA'
    * Platform ID: '0', name: 'localcpu'
        * Device ID: '0', name: 'localcpu'

* Plug-in ID: 'oclcpa', name: 'OpenCL accelerated First Order Univariate CPA'
    * Platform ID: '0', name: 'Intel(R) OpenCL' (OpenCL 1.2 LINUX)
        * Device ID: '0', name: 'Intel(R) Core(TM) i5-3230M CPU @ 2.60GHz'


Found following t-test plug-ins, platforms and devices:

* Plug-in ID: 'ttest', name: 'First Order Non-Specific Univariate Welch's t-test'
    * Platform ID: '0', name: 'localcpu'
        * Device ID: '0', name: 'localcpu'

Create Univariate First-Order CPA context

$ ./stan -I ug -C cpa -F create -r random-traces-id.bin -n 10000 -s 2000 -p aes128back-10k.16prd -q 16 -k 256
SICAK STatistical ANalysis 1.0
Creating new CPA contexts...
100% done... 1m, 19s elapsed.
Created 16 new CPA contexts using
* 10000 power traces with 2000 samples per trace, from 'random-traces-id.bin',
* 16 prediction sets containing 256 power predictions for each of these power traces, from 'aes128back-10k.16prd'
and saved to 'cpa-ug.16ctx'.

ug.json: (output)

{
    "context-a": "cpa-ug.16ctx",
    "contexts-count": "16",
    "prediction-sets-count": "16"
}

Create correlation matrices from Univariate First-Order CPA contexts

$ ./stan -I ugc -C cpa -F finalize ug.json
SICAK STatistical ANalysis 1.0
Finalizing CPA context...
100% done... 1s elapsed.
Created 16 correlation matrices (2000x256) using
* 16 contexts based on 10000 from 'cpa-ug.16ctx'
and saved to 'cpa-ugc.16cor'.

ugc.json: (output)

{
    "contexts-count": "16",
    "correlations": "cpa-ugc.16cor",
    "correlations-candidates-count": "256",
    "correlations-sets-count": "16",
    "prediction-candidates-count": "256",
    "prediction-sets-count": "16",
    "samples-per-trace": "2000"
}
back to top ↑

5. correv

correv is a correlation evaluation utility. It loads correlation matrices from a file and evaluates them using specified modules.

back to top ↑

Usage

Brief usage is also printed when the program is run with -h option.

./correv [options] config

Options

-Q, --query

Query available CPA correlation matrix evaluation and keyguess evaluation plug-in modules (-E, -K).

-E, --correlations-eval-module {string}

ID of a CPA correlation matrix evaluation plug-in module to use.

-K, --keyguess-eval-module {string}

ID of a CPA keyguess evaluation plug-in module to use.

-c, --correlations {filepath}

File containing -q correlation matrices, each of which -s wide and -k tall (double).

-q, --prediction-sets-count, --contexts-count {positive integer}

Number of correlation matrices. E.g. attacking AES-128 key, this value would be 16.

-k, --prediction-candidates-count {positive integer}

Number of key candidates, i.e. rows of correlation matrix. E.g. attacking AES-128 key, this value would be 256.

-s, --samples-per-trace {positive integer}

Number of samples per trace, i.e. cols of correlation matrix.

--param {param}

Optional plug-in module parameters. Module specific option.

-h, --help

Displays help.

-v, --version

Displays version information.

Arguments

config

JSON configuration file(s) with Options.

The JSON configuration file may contain key:string pairs, where key is a long option name and string is the value.

For example: { "samples-per-trace":"2000" }

back to top ↑

Examples

Query available plug-ins

$ ./correv -Q

Found following CPA correlation matrix evaluation plug-ins:

* Plug-in ID: 'maxabscoef', name: 'Maximum absolute value correlation coefficient'
* Plug-in ID: 'maxcoef', name: 'Maximum correlation coefficient'
* Plug-in ID: 'maxedge', name: 'Maximum correlation trace derivative (param="d;sigma", e.g. param="23;8.0")'
* Plug-in ID: 'mincoef', name: 'Minimum correlation coefficient'

Found following CPA keyguess evaluation plug-ins:

* Plug-in ID: 'aes128back', name: 'AES-128 last round CPA key evaluation: last round key gets reversed to the cipher key'
* Plug-in ID: 'plainchar', name: 'Simple key evaluation for byte-based CPA: no transformation after correlation evaluation (e.g. AES first round)'

Evaluate correlation matrices from previous stan example

$ ./correv -E maxcoef -K plainchar ugc.json
SICAK CORRelations EValuation 1.0
Evaluating CPA correlation matrices...
100% done... <1s elapsed.
Obtained key (hex): '36d024461d84b8375fc0f9c04cbab6bb'
$ ./correv -E maxcoef -K aes128back ugc.json
SICAK CORRelations EValuation 1.0
Evaluating CPA correlation matrices...
100% done... <1s elapsed.
Obtained key (hex): '00112233445566778899aabbccddeeff'
back to top ↑

6. visu

visu is a visualisation utility. It allows to plot power traces, correlation traces or t-values and show in graphical window or save in raster format (jpg, png) or vector format (svg).

back to top ↑

Usage

Brief usage is also printed when the program is run with -h option.

./visu [options] config series

Options

-D, --display

Display the chart in a graphical window.

-S, --save {filename}

Save the chart to file.

The output image format is automatically selected by the filename extension (jpg, png, svg).

-W, --width {positive integer}

Width of the saved chart.

-H, --height {positive integer}

Height of the saved chart.

-T, --title {string}

Chart title

-t, --traces {filepath}

File containing -n traces, each of which containing -s samples (int16).

-n, --traces-count {positive integer}

Number of power traces in -t file.

-r, --traces-real-range {positive integer}

Maximum positive value of a power sample in mV, e.g. 2000 for range -2V to +2V.

-a, --t-values {filepath}

File containing -s t-test values (double).

-c, --correlations {filepath}

File containing -q correlation matrices, each of which -s wide and -k tall (double).

-q, --correlations-sets-count {positive integer}

Number of correlation matrices. E.g. attacking AES-128 key, this value would be 16.

-k, --correlations-candidates-count {positive integer}

Number of key candidates, i.e. rows of correlation matrix. E.g. attacking AES-128 key, this value would be 256.

-s, --samples-per-trace {positive integer}

Number of samples per trace.

-b, --samples-real-range {float number}

Time of a single power/correlation trace. Given sampling period T and -s samples, this value would be T*(s-1).

-h, --help

Displays help.

-v, --version

Displays version information.

Arguments

config

JSON configuration file(s) with Options.

The JSON configuration file may contain key:string pairs, where key is a long option name and string is the value.

For example: { "samples-real-range":"3e-6" }

series

Time series to plot. For example:

"t,25,blue" plots 26th power trace from traces file in blue

"c,0,255,red" plots 255th correlation trace from the 1st correlation matrix in red

"c,1,all,#bbbbbb" plots all correlation traces from 2nd correlation matrix in grey

"v,pink" plots t-values from t-values file in pink

Color is optional. When not set, color is selected automatically. Hex RGB codes or svg1.0 color names are allowed.

back to top ↑

Examples

Plot correlation traces

$ ./visu -c cpa-ugc.16cor -q 16 -k 256 -s 2000 c,0,all,grey c,0,54 -S plot.png -W 600 -H 400
SICAK VISUalisation 1.0
File successfully saved.

plot.png:

visu example plot

back to top ↑

7. chardevice (meas) plug-ins

Every plug-in receives Device ID a configuration from Character Device Configuration File which may contain timeout, baudrate, parity and stopbits settings.

serialport

serialport is a plug-in providing access to the system's serial port. It takes advantage of all the parameters set: device id, baudrate, parity, stopbits. Flow control is disabled and no flow control (hardware, software, Xon) is supported.

Following baudrate values are supported:

Furthermore, on Windows following baudrates are available:

Furthermore, on Linux, following baudrates are available:

Following parity values are supported:

Following stopbits values are supported:

timeoutms is a value of timeout in milliseconds.

smartcard

smartcard is a plug-in providing communication with a SmartCard reader using Win32 API. This plug-in does currently not operate under any other platform.

It is opened using a Device ID, which is a number of SmartCard reader as displayed when queried.

Only a valid APDU message must be send using the send() function. Given the nature of the SmartCard command-response communication, the send() function blocks until the response is received back from the card. The receive() function then returns data received during the last send() call. These are not processed in any way (i.e. they usually contain response trailer).

The T=1 block protocol is used.

Baudrate, parity, stopbits and timeout parameters are ignored. The timeout is 5 seconds.

back to top ↑

8. oscilloscope (meas) plug-ins

Every plug-in receives Device ID a configuration from Oscilloscope Configuration File which may contain channel, trigger and timing settings.

Note: Oscilloscope plug-ins may require third-party software to link against and to run properly. Make sure all dependencies are installed on the system.
When all the dependencies are not met, the plug-in won't be found by any utility's --query.

keysight3000

keysight3000 is a Keysight 3000 series oscilloscope (formerly Agilent) plug-in.

On Windows, plug-in requires VISA library (e.g. Keysight IO Suite) to link against (which is why it is not included directly in the release bundle) and to run.

Use VISA address as Device ID (e.g. "USBInstrument1" or e.g. "TCPIP::128.121.240.130::INSTR")

On Linux, plug-in takes advantage of the USBTMC kernel module. Make sure the module is properly loaded before use.

Use usbtmc device filepath as Device ID (e.g. "/dev/usbtmc0"). Make sure you have appropriate permissions to access this file.

The oscilloscope supports only 1 capture per run.

ps6000

ps6000 is a PicoScope 6000 series oscilloscope plug-in.

On both Windows and Linux, the plug-in requires PicoScope Drivers/SDK to link against (which is why it is not included directly in the release bundle) and to run.

Use oscilloscope serial number as Device ID. When Device ID is left blank, the plug-in opens the first found device on the system.

On Linux, make sure you have permission to access the oscilloscope device (it should be placed somewhere in /dev/usb/...).

This oscilloscope may support more than 1 capture per run (i.e. rapid block mode).

back to top ↑

9. measurement (meas) plug-ins

Users are encouraged to write their own measurement scenarios. In such cases, please let me (the author) know :-).

Measurement scenarios obtain the configuration string given using meas's --param option. The configuration string has the following format: "key1=val1;key2=val2...".

For example, to launch a measurement downloading power traces from channel 2, use: --param="ch=2"

Accepted parameters are scenario specific. See below.

random128co

random128co is a measurement scenario primarily used for AES-128 implementations CPA attack.

The scenario goes as follows:

while capturing power traces after every trigger.

It produces following files:

where ID is meas given parameter or default.

Parameters

ttest128co

ttest128co is a measurement scenario primarily used for AES-128 implementations t-tests.

The scenario goes as follows:

while capturing power traces after every trigger.

It produces following files:

where ID is meas given parameter or default.

Parameters

random128apdu

ttest128apdu

Both random128apdu and ttest128apdu work similar as random128co and ttest128co.

First difference is that prior to the encryption, the cipher key is not being set in this scenario.

Second, the data are send and received using APDU format as described in ISO/IEC 7816-4:2005 with fields set as follows:

Besides this, the scenarios work identical and produce same output files.

Parameters

These APDU scenarios are compatible with devices requesting APDU format, such as those provided by the smartcard plug-in. Example of a typical usage: (use -Q to find out the number of the smartcard reader, when needed)

./meas -M random128apdu -O keysight3000 -R USBInstrument1 -C smartcard -n 100 --param="ch=2;cla=80;ins=60" back to top ↑

10. blockprocess (prep) plug-ins

predictaes128back

predictaes128back is a block data processing plug-in module.

It processes M data blocks of data, each block 16 bytes long. I.e. AES-128 cipher text.

It creates 16 power prediction sets from AES-128 cipher text, one for every byte of the cipher key.

Each power prediction set contains 256 power predictions (for every possible byte value), for every measurement taken.

I.e. overall it creates a file containing 16 matrices, each 256xM large, where M is number blocks / of measurements taken.

The power predictions are based on the last round working register Hamming distance. This power model is applicable e.g. to FPGA implementations.

It produces following files:

where ID is prep given parameter or default.

predictaes128front

predictaes128front is a block data processing plug-in module.

It processes M data blocks of data, each block 16 bytes long. I.e. AES-128 plain text.

It creates 16 power prediction sets from AES-128 cipher text, one for every byte of the cipher key.

Each power prediction set contains 256 power predictions (for every possible byte value), for every measurement taken.

I.e. overall it creates a file containing 16 matrices, each 256xM large, where M is number blocks / of measurements taken.

The power predictions are based on the first round S-box Hamming weight. This power model is applicable e.g. to MCU implementations.

It produces following files:

where ID is prep given parameter or default.

back to top ↑

11. tracesprocess (prep) plug-ins

There are currently no tracesprocess plug-in modules implemented.

back to top ↑

12. cpaengine (stan) plug-ins

cpaengine is a computational plug-in module type for stan. Difference between various plug-in modules here is not only in functionality, but also in the implementation of the computation.

cpa

cpa is a computational plug-in module for stan.

It performs Univariate First-Order CPA "create, merge, finalize" context stan functions. The "create" function, which is by far the most time demanding, is accelerated on multi-core CPU using OpenMP.

oclcpa

oclcpa is a computational plug-in module for stan.

It performs Univariate First-Order CPA "create, merge, finalize" context stan functions. The "create" function, which is by far the most time demanding, is accelerated using OpenCL (e.g. nVidia GPUs, AMD/ATi GPUs, Intel GPUs, but theoretically also FPGA accelerators etc.).

back to top ↑

13. ttestengine (stan) plug-ins

ttestengine is a computational plug-in module type for stan. Difference between various plug-in modules here is not only in functionality, but also in the implementation of the computation.

ttest

ttest is a computational plug-in module for stan.

It performs Univariate First-Order Non-Specific Welch's t-test "create, merge, finalize" context stan functions.

back to top ↑

14. cpacorreval (correv) plug-ins

maxabscoef

maxabscoef is a correlation matrix evaluation plug-in module for correv.

It searches for maximum absolute value of correlation coefficient in the correlation matrices given.

Its output is an array of selected key candidates, which is further processed by cpakeyeval module.

maxcoef

maxcoef is a correlation matrix evaluation plug-in module for correv.

It searches for maximum value of correlation coefficient in the correlation matrices given.

Its output is an array of selected key candidates, which is further processed by cpakeyeval module.

maxedge

maxedge is a correlation matrix evaluation plug-in module for correv.

It searches for largest edge (i.e. the maximum absolute value of derivative of correlation traces) in the correlation traces in correlation matrices given.

The edge detection is performed by convolving the correlation traces with the Gaussian first derivative kernel. This kernel takes two parameters:

To set the parameters, use correv --param option. E.g. setting a diameter=23 and sigma=8.0:

./correv -E maxedge --param="23;8.0"

This kind of correlation matrix evaluation may be useful when working with power traces obtained from noisy environment. Find out more.

Its output is an array of selected key candidates, which is further processed by cpakeyeval module.

mincoef

mincoef is a correlation matrix evaluation plug-in module for correv.

It searches for minimum value of correlation coefficient in the correlation matrices given.

Its output is an array of selected key candidates, which is further processed by cpakeyeval module.

back to top ↑

15. cpakeyeval (correv) plug-ins

aes128back

aes128back is a keyguess evaluation plug-in module for correv. It processed cpacorreval module's output array.

It requires a 16-part keyguess.

It constructs a cipher key by mapping every byte of the key to keyguess bytes and reverses the last round key.

plainchar

plainchar is a keyguess evaluation plug-in module for correv. It processed cpacorreval module's output array.

It constructs a cipher key simply by mapping every byte of the key to keyguess bytes. I.e. it does no transformation.

back to top ↑

16. Tips

back to top ↑

17. License

Software license

SICAK - SIde-Channel Analysis toolKit
Copyright (C) 2018 Petr Socha, FIT, CTU in Prague

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program. If not, see https://www.gnu.org/licenses/.

User's Guide license

To the extent possible under law, Petr Socha has waived all copyright
and related or neighboring rights to "SICAK 1.0 User's Guide, ver. 1.0".
I.e., this document is available under CC0 license (public domain).

back to top ↑

18. Contact

This project is a result of pursuing a master's degree at Faculty of Information Technology,
Czech Technical University in Prague.

Author: Petr Socha, petrsocha(at)petrsocha.cz, sochapet(at)fit.cvut.cz

Supervisor: Vojtěch Miškovský, miskovoj(at)fit.cvut.cz