mylittlepwny
1 mylittlepwny
mylittlepwny is a small framework for side-channel analysis.
At the time I started writing this, it was difficult to find
published frameworks for side-channel analysis. Many people would
use Matlab, which was slooow. And the experts in the field would
not publish their tools.
Nowadays, several good alternatives have been published.
The main motivations for writing yet another framework were initially:
- scratch your own itch. Considering the use of Haskell for real-life programming tasks. Writing program for compute-intensive tasks in Haskell is quite challenging (probably not the best tool, but not the worst either). There are many ways the current implementation could be improved, but I learned a lot in this journey!
- I had to prepare a tutorial for side-channel analysis at SSPREW, 2018, and struggled at that time to find a framework that would fit the bill.
1.1 Setup, build, test
1.1.1 Get the source code
https://github.com/cogito-cea/mylittlepwny
1.1.2 Build that thing
Two options. Either build and run with stack, or using a docker
image.
1.1.2.1 Using stack
Install stack. Follow the documentation here.
Then run, from the root of the source directory:
stack setup stack build
You can install mylittlepwny locally in $HOME/.local/bin with:
stack install
1.1.2.2 With docker
Load the docker image:
$ docker load -i mylittlepwny-<VERSION>.tar.gz
Run it:
$ docker run -it --rm mylittlepwny bash Starting with UID : 9001 dockeruser@9e2f8654b323:/mylittlepwny$ mylittlepwny --help Usage: mylittlepwny [--version] COMMAND CPA from on-disk traces Available options: -h,--help Show this help text --version Show version Available commands: view View traces cpa CPA analysis ttest Non-specific t-test specific Specific t-test
1.1.3 Run that thing. Frow $PATH
Assuming that mylittlepwny is install somewhere in one of the
directories listed in $PATH (for exemple, in $HOME/.local/bin
after a stack install):
$ mylittlepwny --version 0.4.0.0
1.1.4 Run that thing. Using stack
$ stack exec mylittlepwny -- --version 0.4.0.0
You can install mylittlepwny locally in $HOME/.local/bin with:
stack install
Once $HOME/.local/bin is declared in your PATH variable:
$ mylittlepwny --version 0.4.0.0
1.1.5 Run that thing. Using the docker image
Suppose we want to use the tool on some traces located on the host
machine in the directory TRACES.
Either run commands from a docker container:
$ docker run -it --rm -v $(pwd)/tests/traces:/traces mylittlepwny bash Starting with UID : 9001 dockeruser@3971267adbab:/mylittlepwny$ mylittlepwny --version 0.4.0.0
Or instantiate a new container each time:
$ docker run -it --rm -v $(pwd)/tests/traces:/traces mylittlepwny mylittlepwny --version Starting with UID : 9001 0.4.0.0
1.2 Format of the side-channel traces
The preferred (and most efficient) format is raw.
1.2.1 Format of the side-channel traces: raw files
<nb of samples><sample size><sample><sample><sample> ... ^ ^ | +-- raw data +-- header
A raw file contains:
- a small header of 2 32-bit =unsigned int=s (little-endian):
<nb of samples>: number of samples per side-channel trace. A full file will probably contain more that one side-channel trace.<sample size>: byte size of each sample. Each sample value is expected to be encoded asunsigned intvalues (little-endian).
- the stream of samples
1.2.2 Format of the side-channel traces: text files
All files are located in the same directory, and each text file is expected to contain the samples of one side-channel trace. Sample values are represented with a textual, decimal representation.
<TRACEDIR>/trace_000000000.txt <TRACEDIR>/trace_000000001.txt <TRACEDIR>/trace_000000002.txt <TRACEDIR>/trace_000000003.txt <TRACEDIR>/trace_000000004.txt <TRACEDIR>/trace_000000005.txt <TRACEDIR>/trace_000000006.txt <TRACEDIR>/trace_000000007.txt <TRACEDIR>/trace_000000008.txt <TRACEDIR>/trace_000000009.txt
1.3 Tests
A small sample set of side-channel traces is provided with the source
code, for test purposes, in directory tests/traces.
1.3.1 Test: view traces
$ stack exec mylittlepwny -- view -f tests/traces/unprotected.raw -n 16 View Settings: average over: 16 tmin: 0 tmax: 1000 first trace: 0 Rendering the view plot in: tests/traces/Traces avg:16 n:0 tmin:00000 tmax:01000.png
1.3.2 Test: CPA
$ stack exec mylittlepwny -- cpa -f tests/traces/unprotected.raw -t tests/traces/plaintexts.txt -n 100 CPA Settings: number of traces: 100 tmin: 0 tmax: 1000 Max correlation value: 0.6940127611160278 found for key byte #1.0 Rendering the CPA plot in: tests/traces/CPA-T byte:0 n:100 tmin:00000 tmax:01000.png Rendering the CPA plot in: tests/traces/CPA-D byte:0 n:100 tmin:00000 tmax:01000.png
1.3.3 Test: non-specific t-test
This test would require a set of side-channel of trace that is different from
the set of traces provided in the tests directory.
1.3.4 Test: specific t-test
Caution note: you need more side-channel traces to get something interesting out of this.
$ stack exec mylittlepwny -- specific -f tests/traces/unprotected.raw -t tests/traces/plaintexts.txt -k tests/traces/key.txt -n 100 -b 0 Specific t-test. Settings: Total number of traces: 100 tmin: 0 tmax: 1000 Specific t-test on bit: 0 Rendering the TTest plot in: tests/traces/TTest-S n:100 tmin:00000 tmax:01000 b:000.png
1.4 Side-Channel Analysis
1.4.1 Tool usage #1
Getting help:
$ mylittlepwny --help Usage: mylittlepwny [--version] COMMAND CPA from on-disk traces Available options: -h,--help Show this help text --version Show version Available commands: view View traces cpa CPA analysis ttest Non-specific t-test specific Specific t-test
1.4.2 Tool usage #2
Getting help for a specific command:
$ mylittlepwny COMMAND --help
e.g.:
$ mylittlepwny view --help
Usage: mylittlepwny view ((-d|--traces-dir TRACES_DIR) |
(-f|--trace-rawfile TRACE_RAWFILE)) [--tmin TMIN]
[--tmax TMAX] [-n|--average-over AVG_SIZE]
[-m|--first-trace FIRST_TRACES]
View traces
Available options:
-d,--traces-dir TRACES_DIR
Location of the directory with traces files, in
textual format.
-f,--trace-rawfile TRACE_RAWFILE
Location of the trace files, in raw format.
--tmin TMIN Sample number for the start of the observation window
[default: 0].
--tmax TMAX Sample number for the end of the observation window
[default: full trace length].
-n,--average-over AVG_SIZE
Compute an average over AVG_SIZE traces [default: 1]
-m,--first-trace FIRST_TRACES
Number of the first trace to consider [default: 0]
-h,--help Show this help text
1.4.3 View traces
The command view plots traces for visual inspection.
$ mylittlepwny view --help
Usage: mylittlepwny view ((-d|--traces-dir TRACES_DIR) |
(-f|--trace-rawfile TRACE_RAWFILE)) [--tmin TMIN]
[--tmax TMAX] [-n|--average-over AVG_SIZE]
[-m|--first-trace FIRST_TRACES]
View traces
Available options:
-d,--traces-dir TRACES_DIR
Location of the directory with traces files, in
textual format.
-f,--trace-rawfile TRACE_RAWFILE
Location of the trace files, in raw format.
--tmin TMIN Sample number for the start of the observation window
[default: 0].
--tmax TMAX Sample number for the end of the observation window
[default: full trace length].
-n,--average-over AVG_SIZE
Compute an average over AVG_SIZE traces [default: 1]
-m,--first-trace FIRST_TRACES
Number of the first trace to consider [default: 0]
-h,--help Show this help text
Typical usage:
$ mylittlepwny view -f tests/traces/unprotected.raw -n 16
1.4.4 CPA
Run a correlation power analysis.
$ mylittlepwny cpa --help
Usage: mylittlepwny cpa ((-d|--traces-dir TRACES_DIR) |
(-f|--trace-rawfile TRACE_RAWFILE)) [--tmin TMIN]
[--tmax TMAX] (-t|--textfile TEXTFILE)
[-k|--keyfile KEYFILE] [-n|--nbtraces NSIWE]
[-b|--byte BYTE]
CPA analysis
Available options:
-d,--traces-dir TRACES_DIR
Location of the directory with traces files, in
textual format.
-f,--trace-rawfile TRACE_RAWFILE
Location of the trace files, in raw format.
--tmin TMIN Sample number for the start of the observation window
[default: 0].
--tmax TMAX Sample number for the end of the observation window
[default: full trace length].
-t,--textfile TEXTFILE Location of the plaintexts file
-k,--keyfile KEYFILE Location of the key file
-n,--nbtraces NSIWE Number of traces used for the CPA analysis [default:
512]
-b,--byte BYTE Number of the key byte to attack [default: 0]
-h,--help Show this help text
1.4.5 Non-specific t-test
$ mylittlepwny ttest --help
Usage: mylittlepwny ttest ((-d|--traces-dir TRACES_DIR) |
(-f|--trace-rawfile TRACE_RAWFILE)) [--tmin TMIN]
[--tmax TMAX] [-n|--nbtraces NSIWE]
(-c|--classesFile CLASSESFILE)
Non-specific t-test
Available options:
-d,--traces-dir TRACES_DIR
Location of the directory with traces files, in
textual format.
-f,--trace-rawfile TRACE_RAWFILE
Location of the trace files, in raw format.
--tmin TMIN Sample number for the start of the observation window
[default: 0].
--tmax TMAX Sample number for the end of the observation window
[default: full trace length].
-n,--nbtraces NSIWE Number of traces used for the CPA analysis [default:
512]
-c,--classesFile CLASSESFILE
Location of the 'classes file'
-h,--help Show this help text
1.4.6 Non-specific t-test
- Instead of a plaintext file, this test requires a ‘separation file’, i.e. a file that describes the population each trace belongs to.
- The separation is expected to follow the order of the traces in the traces file.
- This is a text file, containing either
0or1, respectively for the first and the second populations of traces used to build the t-test.
Example :
$ head separate-ttest-NS.txt 0 0 0 0 1 0 0 1 0 0
Example usage:
$ mylittlepwny -f ~/src/SSPREW/traces/testfull-NS/traces.raw \
-c ~/src/SSPREW/traces/separate-ttest-NS.txt \
-n 22000 --tmin 7500 --tmax 10000
1.4.7 Specific t-test
$ mylittlepwny specific --help
Usage: mylittlepwny specific ((-d|--traces-dir TRACES_DIR) |
(-f|--trace-rawfile TRACE_RAWFILE)) [--tmin TMIN]
[--tmax TMAX] [-n|--nbtraces NSIWE]
(-t|--textfile TEXTFILE) (-k|--keyfile KEYFILE)
(-b|--target-bit BIT)
Specific t-test
Available options:
-d,--traces-dir TRACES_DIR
Location of the directory with traces files, in
textual format.
-f,--trace-rawfile TRACE_RAWFILE
Location of the trace files, in raw format.
--tmin TMIN Sample number for the start of the observation window
[default: 0].
--tmax TMAX Sample number for the end of the observation window
[default: full trace length].
-n,--nbtraces NSIWE Number of traces used for the CPA analysis [default:
512]
-t,--textfile TEXTFILE Location of the plaintexts file
-k,--keyfile KEYFILE Location of the key file
-b,--target-bit BIT single-bit t-test on bit #BIT in the output of the
first SBOX
-h,--help Show this help text
1.4.8 Specific t-test
Run the t-test on the output of the first SubBytes operation.
Currently requires at least:
- a set of traces
- the list of input plaintexts
- the description of the secret key
1.5 FAQ
1.5.1 What is this error? Data.Binary.Get.runGet at position 0: not enough bytes
Issue:
mylittlepwny: Data.Binary.Get.runGet at position 0: not enough bytes CallStack (from HasCallStack): error, called at libraries/binary/src/Data/Binary/Get.hs:351:5 in binary-0.8.5.1:Data.Binary.Get
Solution: run with option -n | --nb
Explanation:
By default, the analysis are run with 512 traces if option -n is not
set. It may happen that the input set of traces contains less than
512 traces, which will lead to this error.
This behaviour should be fixed in the near future.
1.6 Limitations and known issues
1.6.1 Performance
mylittlepwnycan exploit all the processors available on your machine. Increasing the number of processors/cores used should reduce the processing time.- However, the performance is quite bad. It may happen that the execution time increases when all cores are used. It may also happen that the exection time is higher when running on all cores, as compared to running on one core only!
- To specify the number of cores used, run
mylittlepwnyas follows (here using 2 cores)
$ mylittlepwny +RTS -N2 -RTS <… here come other options …>
or:
$ mylittlepwny <… here come other options …> +RTS -N2
1.6.2 Format of trace files
Raw files: currently, 16-bit int samples are only supported.
1.6.3 CPA
Model: Currently only supports the Hamming Weight.
Hypothesis: can currently only target the output of the first SubBytes.
1.6.4 non-specific t-test
Target hypothesis: Currently only supports the output of the first SubBytes.
1.7 References
Paul Bottinelli and Joppe W. Bos. Computational aspects of correlation power analysis. J. Cryptographic Engineering, 7(3):167–181, 2017.
Other tools for side-channel analysis:
- https://github.com/Riscure/Jlsca
- https://github.com/newaetech/chipwhisperer-lint
- https://github.com/ikizhvatov/dpa-tools-benchmarking
- https://github.com/ikizhvatov/conditional-reduction
- https://github.com/Ledger-Donjon/lascar
2 cpa-hyps
2.0.1 Overview of program options
stack exec cpa-hyps -- --helpcpa-hyps: compute hypothesis values for CPA attacks on AES.
Usage: cpa-hyps [-o|--output FILE] [-n|--nb NUMBER] [-x|--seed SEED_VALUE]
COMMAND
cpa-hyps: a few bunch of things to perform side channel attacks. Use COMMAND
--help to see the list of options supported by each command.
Available options:
-h,--help Show this help text
-o,--output FILE Name of the output file (default: "output.txt")
-n,--nb NUMBER Size of the set of plaintexts
generated (default: 16384)
-x,--seed SEED_VALUE Seed of the random number generator (default: 0)
Available commands:
version Print program version
plaintexts Generate a list of random plaintexts
addrk Compute hypothesis values for the first AddRoundKey,
using a Hamming weight model.
sbox Compute hypothesis values for the first SBOX, using a
Hamming weight model.
ttest-fr Compute two populations of plaintexts for the
non-specific t-test (fixed vs. random), for the
output of the first SBOX. Generates two plaintext
files named after the contents of options
--population0 and --population1.
ttest-rr Compute two populations of plaintexts for the
specific t-test (random vs. random), for the output
of the first SBOX. Generates a list of plaintexts and
a list of values {0,1} to separate the two t-test
populations.
(org-babel-get-header)
2.0.2 command plaintexts
Use this command to generate a list of random plaintexts. This command has no specific option.
stack exec cpa-hyps -- plaintexts --helpUsage: cpa-hyps plaintexts Generate a list of random plaintexts
:
Available options: -h,--help Show this help text
2.0.3 command sbox
Use this command to generate the CPA correlation hypothesis at the output of the first SubBytes computation in AES. Currently we use the Hamming Weight to compute the power model.
stack exec cpa-hyps -- sbox --helpUsage: cpa-hyps sbox (-p|--plaintexts ARG) [-b|--byte ARG] Compute hypothesis values for the first SBOX, using a Hamming weight model.
:
Available options:
-p,--plaintexts ARG Name of the input file containing the plaintext
values
-b,--byte ARG Byte number in [0..15] used to compute CPA
correlation hypothesis (default: 0)
-h,--help Show this help text
2.0.3.0.0.0.0.1 TODO introduce the Hamming Distance model
2.0.4 command ttest-fr
Provides two input plaintext populations to perform a specific fixed vs. random t-test.
stack exec cpa-hyps -- ttest-fr --helpUsage: cpa-hyps ttest-fr [-p|--plaintexts ARG] [-s|--separate ARG]
Compute two populations of plaintexts for the non-specific t-test (fixed vs.
random), for the output of the first SBOX. Generates two plaintext files named
after the contents of options --population0 and --population1.
Available options:
-p,--plaintexts ARG Name of the output file containing the plaintext
values for the two
populations. (default: "plaintexts.txt")
-s,--separate ARG This generated files has the same length than the
plaintext file. It contains a list of integer values
either 0 or 1, in order to separate the plaintexts
between two populations '0' and
'1'. (default: "text-separate.txt")
-h,--help Show this help text
2.0.5 command ttest=rr
Provides two input plaintext populations to perform a specific random vs. random t-test.
stack exec cpa-hyps -- ttest-rr --helpUsage: cpa-hyps ttest-rr (-k|--key KEYFILE) [-b|--bit-number BIT_NUMBER]
[-p|--plaintexts ARG] [-s|--separate ARG]
[-c|--ciphers CIPHERS]
Compute two populations of plaintexts for the specific t-test (random vs.
random), for the output of the first SBOX. Generates a list of plaintexts and
a list of values {0,1} to separate the two t-test populations.
Available options:
-k,--key KEYFILE the input key file
-b,--bit-number BIT_NUMBER
number of the state bit observed (default: 0)
-p,--plaintexts ARG Name of the output file containing the plaintext
values for the two
populations. (default: "plaintexts.txt")
-s,--separate ARG This generated files has the same length than the
plaintext file. It contains a list of integer values
either 0 or 1, in order to separate the plaintexts
between two populations '0' and
'1'. (default: "text-separate.txt")
-c,--ciphers CIPHERS Generate the lists of expected cipher values in file
CIPHERS. The file is not generated if this option is
not used.
-h,--help Show this help text