2 files changed, 125 insertions, 0 deletions
diff --git a/analysis/countermeasures/README.md b/analysis/countermeasures/README.md
new file mode 100644
index 0000000..058725c
--- /dev/null
+++ b/analysis/countermeasures/README.md
@@ -0,0 +1,123 @@
+# ECTester: Reverse-engineering side-channel countermeasures of ECC implementations
+
+This directory contains supplementary material for the 
+*ECTester: Reverse-engineering side-channel countermeasures of ECC implementations* paper
+from CHES 2025.
+
+There are several Jupyter notebooks for data collection, simulation and analysis, as well
+as data collected from real-world smartcards.
+
+The general structure is as follows:
+
+ - The root ECTester repository (at `../../`) contains three compontents: the applet, the reader tool
+ and the standalone tool. This is the tool as described in Section 4.
+    - The applet is a JavaCard applet that is meant to be installed on the card under analysis. It
+    offers a very generic command interface for working with the ECC capabilities of the card.
+    - The reader tool is a CLI tool that is able to interact with the applet and test the ECC implementation
+    on the card. It contains the test data, test suites and individual test implementations as well as
+    a generic CLI interface for performing ECC operations on the card (e.g. keygen/ECDH/ECDSA).
+    - The standalone tool is a CLI tool that interacts with standalone (software) ECC libraries
+    and is able to test them. It contains the test data, test suites and individual test implementations
+    as well as a generic CLI interface for performing ECC operations on the card (e.g. keygen/ECDH/ECDSA).
+ - This analysis artifact (`analysis/countermeasures`) focuses on reverse-engineering the scalar
+   randomization countermeasures from smartcards (Section 6).
+    - `simulate.ipynb`: A Jupyter notebook that contains simulations of the behavior of different
+    scalar randomization countermeasures under our tests (Test 3n, Test composite, Test k=10, Test n + e).
+    This notebook also implements mask recovery for the two countermeasures where we are able to do so:
+    GSR and multiplicative.
+    - `measure.ipynb`: A Jupyter notebook that runs our tests on a given JavaCard by interacting with
+    the ECTester applet installed on it.
+    - `results.ipynb`: A Jupyter notebook that evaluates the results of tests run (by the `measure` notebook)
+    on a smartcard.
+    - `utils.py`: Various utility functions used by the notebooks.
+    - `tests/`: A directory that contains the test data (inputs) for our tests:
+    Test 3n, Test composite, Test k=10, Test n + e.
+    - `results/`: A directory that contains the test results for the cards tested.
+
+
+## Requirements
+
+What you need in terms of environment depends on what you want to do with ECTester and/or
+this artifact. If you want to build and use the tools from the root ECTester repository
+(applet, reader tool, standalone tool) then you need to setup Java with appropriate versions.
+If you want to run the Jupyter notebooks that analyze data from this artifact then you
+need to setup Python with some packages.
+
+Do not forget to check-out the repository with submodules before doing anything with it:
+```shell
+git submodule update --init --recursive
+```
+
+
+### Java
+
+The build process and requirements of the base ECTester tools (applet, reader, standalone)
+are described in the [main README](../../README.md) in section **Setup**. Please follow those
+steps to build ECTester components. Note that, the standalone tool has additional setup instructions
+in the README.
+
+
+### Python
+
+We use the [**pyecsca**](https://pyecsca.org/) toolkit heavily and implemented several parts of our work
+directly upstream (such as the countermeasures themselves). Furthermore, some of the analysis notebooks
+use the [cypari2](https://pypi.org/project/cypari2/) Python bindings to libpari, which you also need
+to have installed.
+
+To install the Python requirements in a new virtual environment do:
+```shell
+python -m venv virt
+. virt/bin/activate                    # Or {.fish,.csh,.ps1} depending on your shell
+pip install -r ../../requirements.txt  # Install base ECTester requirements
+pip install -r requirements.txt        # Install artifact requirements
+```
+
+
+## Evalutation
+
+Depending on your access to JavaCard smartcards (and willingness to possibly sacrifice them)
+you may be able to evaluate different parts of this artifact.
+
+1. You can run the simulation notebook to understand the behavior of scalar
+randomization countermeasures under our tests.
+2. If you have access to JavaCard smartcards with ECC support that allow you
+to install applets and are willing to possibly brick them you can run the
+data collection for our tests.
+3. You can run our results evaluation that takes in either our provided results
+from smartcards or those you produced in the previous step.
+4. You can "play around" with the standalone tool and observe test results
+on software ECC libraries.
+
+See subsections below for more details.
+
+
+### Simulation
+
+> This step supports *section 6* of the paper, mainly Table 4.
+
+1. Run the `simulation.ipynb` notebook.
+2. Examine the test results and how they correspond to Table 4.
+
+
+### Measurement on JavaCards
+
+> This step supports *subsection 6.6* of the paper.
+
+Note that, this step is not necessary, is time consuming and requires access
+to suitable JavaCard smartcards (which it may permanently destroy).
+
+1. Build applet for correct platform version.
+2. Install applet (e.g. gp-pro)
+3. Run measure notebook.
+
+### Evalution of results
+-> (Subsection 6.6)
+
+1. Run results notebook.
+
+### Playing around with libraries
+-> (Section 5)
+
+## Cards
+
+TODO: card summary identification
diff --git a/analysis/countermeasures/requirements.txt b/analysis/countermeasures/requirements.txt
new file mode 100644
index 0000000..9d3ea3e
--- /dev/null
+++ b/analysis/countermeasures/requirements.txt
@@ -0,0 +1,2 @@
+pyecsca
+cypari2