https://github.com/cogito-cea/mylittlepwny
Two options. Either build and run with stack, or using a docker
image.
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
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
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
$ 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
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
# header: <number of samples> <sample size> # the stream of samples <sample> <sample> <sample>
A raw file contains:
- a small header of two 32-bit
unsigned int:- number of samples per side-channel trace
- byte size of each sample.
- the stream of samples
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
A small sample set of side-channel traces is provided with the source
code, for test purposes, in directory tests/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
$ 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
This test would require a set of side-channel of trace that is different from
the set of traces provided in the tests directory.
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
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
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
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
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
$ 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
- 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
$ 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
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
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.
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
Raw files: currently, 16-bit int samples are only supported.
Model: Currently only supports the Hamming Weight.
Hypothesis: can currently only target the output of the first SubBytes.
Target hypothesis: Currently only supports the output of the first SubBytes.
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)
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
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
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
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