Add proper README.

2 files changed, 54 insertions, 363 deletions

diff --git a/README.md b/README.md
index ce7cf90..837c831 100644
--- a/README.md
+++ b/README.md
@@ -4,7 +4,60 @@
 
 **Py**thon **E**lliptic **C**urve cryptography **S**ide-**C**hannel **A**nalysis toolkit.
 
-Notebook package. See the [main repo](https://github.com/J08nY/pyecsca) for more information.
+Notebook package, see below for description of the notebooks showcasing the toolkit.
+See the [main repo](https://github.com/J08nY/pyecsca) for more information.
+
+## Notebooks
+
+### Configuration space
+
+The [configuration space](configuration_space.ipynb) notebook explores the size of the space of
+possible implementation configurations of ECC.
+
+### Simulation
+
+The [simulation](simulation.ipynb) notebook showcases the simulation and execution tracing capabilities
+of the toolkit.
+
+### Codegen & emulation
+
+The [codegen](codegen.ipynb) notebook demonstrates the process of generating and interacting with
+generated C implementations of ECC for micro-controllers. The generated implementations can either
+be run on compatible hardware or emulated (at CPU-level) using the
+[Rainbow](https://github.com/Ledger-Donjon/rainbow)-based emulator demonstrated in the
+[emulator](emulator.ipynb) notebook.
+
+### Measurement
+
+The [measurement](measurement.ipynb) notebook demonstrates the trace acquisition using
+PicoScope/ChipWhisperer scopes that can be used with the toolkit.
+
+### Visualization
+
+The [visualization](visualization.ipynb) notebook showcases the trace visualization capabilities
+of the toolkit.
+
+### Smartcards
+
+The [smartcards](smartcards.ipynb) notebook shows the options of communicating with smartcard
+targets using the toolkit.
+
+### Reverse-engineering
+
+#### RPA-RE
+
+The [RPA](re/rpa.ipynb) notebook uses the Refined Power Analysis attack-based technique to reverse-engineer
+the scalar multiplier of ECC implementations, given access to a power side-channel.
+
+#### EPA-RE
+
+The [EPA](re/epa.ipynb) notebook uses the ideas behind the Exceptional Procedure Attack to reverse-engineer
+the coordinate system and formulas of ECC implementations, given access to an error side-channel.
+
+#### Structural
+
+The [structural](re/structural.ipynb) notebook explores the structure of scalar multiplers and addition
+formulas for reverse-engineering purposes.
 
 ## License
 
diff --git a/leakage_assesment.ipynb b/leakage_assesment.ipynb
deleted file mode 100644
index 015a181..0000000
--- a/leakage_assesment.ipynb
+++ /dev/null
@@ -1,362 +0,0 @@
-{
- "cells": [
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "# Leakage assessment\n",
-    "\n",
-    "This notebook showcases usage of **pyecsca** to reverse-engineer an implementation\n",
-    "configuration utilizing a leakage assessment technique based on the Welch's t-test."
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "## Implementation and scope setup\n",
-    "\n",
-    "We will be reversing an implementation on the `STM32F3` board, using a PicoScope 5000 oscilloscope.\n",
-    "The implementation uses the left-to-right double and add multiplier, Short Weierstrass curve model,\n",
-    "projective coordinate system and the `add-1998-cmo`, `dbl-1998-cmo` formulas."
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "import tempfile\n",
-    "\n",
-    "from os.path import join\n",
-    "from pyecsca.codegen.common import Platform, DeviceConfiguration\n",
-    "from pyecsca.codegen.render import render_and_build\n",
-    "from pyecsca.ec.model import ShortWeierstrassModel\n",
-    "from pyecsca.ec.mult import LTRMultiplier\n",
-    "from pyecsca.ec.configuration import *\n",
-    "\n",
-    "platform = Platform.STM32F3\n",
-    "hash_type = HashType.SHA1\n",
-    "mod_rand = RandomMod.REDUCE\n",
-    "mult = Multiplication.BASE\n",
-    "sqr = Squaring.BASE\n",
-    "red = Reduction.BARRETT\n",
-    "inv = Inversion.GCD\n",
-    "\n",
-    "model = ShortWeierstrassModel()\n",
-    "coords = model.coordinates[\"projective\"]\n",
-    "add = coords.formulas[\"add-2016-rcb\"]\n",
-    "dbl = coords.formulas[\"dbl-2016-rcb\"]\n",
-    "formulas = [add, dbl]\n",
-    "scalarmult = LTRMultiplier(add, dbl, complete=True, always=True)\n",
-    "\n",
-    "config = DeviceConfiguration(model, coords, formulas, scalarmult, hash_type, mod_rand, mult, sqr, red, inv,\n",
-    "                             platform, True, True, True)\n",
-    "\n",
-    "tmpdir = tempfile.TemporaryDirectory()\n",
-    "directory, elf_file, hex_file, res = render_and_build(config, tmpdir.name)\n",
-    "fw = join(tmpdir.name, hex_file)\n",
-    "print(fw)"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "from pyecsca.sca.scope.picoscope_sdk import PS5000Scope\n",
-    "from pyecsca.sca.scope import SampleType\n",
-    "\n",
-    "scope = PS5000Scope()\n",
-    "scope.open()\n",
-    "scope.setup_channel(channel=\"A\", coupling=\"AC\", range=0.2, offset=0.0, enable=True)\n",
-    "scope.setup_channel(channel=\"B\", coupling=\"DC\", range=5.0, offset=0.0, enable=True)\n",
-    "scope.setup_frequency(frequency=5_161_290, pretrig=0, posttrig=16_000_000)\n",
-    "scope.setup_trigger(channel=\"B\", threshold=1.0, direction=\"rising\", delay=0, timeout=20000, enable=True)\n",
-    "scope.setup_capture(channel=\"A\", enable=True)\n",
-    "print(\"Scope\", scope.get_variant(), \"connected.\")"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "## Trace acquisition\n",
-    "\n",
-    "We will collect 200 traces of the target generating a keypair on the `secp128r1` curve."
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "from pyecsca.sca.trace import Trace\n",
-    "from pyecsca.ec.params import get_params\n",
-    "from pyecsca.codegen.client import DeviceTarget, Triggers\n",
-    "from pyecsca.sca.trace_set import HDF5TraceSet\n",
-    "from time import sleep, time\n",
-    "import gc"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "params = get_params(\"secg\", \"secp128r1\", \"projective\")\n",
-    "target = DeviceTarget(model=params.curve.model, coords=params.curve.coordinate_model, platform=config.platform, timeout=5000)\n",
-    "target.flash(fw)\n",
-    "\n",
-    "hdf5 = HDF5TraceSet.inplace(join(tmpdir.name, \"traces.h5\"))\n",
-    "\n",
-    "target.connect()\n",
-    "target.set_params(params)\n",
-    "target.set_trigger(Triggers.keygen)\n",
-    "for i in range(10):\n",
-    "    scope.arm()\n",
-    "    sleep(3)\n",
-    "    start = time()\n",
-    "    priv, pub = target.generate()\n",
-    "    end = time()\n",
-    "    print(end - start, priv, pub)\n",
-    "    scope.capture(5000)\n",
-    "    trace = scope.retrieve(\"A\", SampleType.Volt)\n",
-    "    trace.meta[\"priv\"] = priv\n",
-    "    trace.meta[\"pub\"] = pub\n",
-    "    hdf5.append(trace)\n",
-    "    %xdel trace\n",
-    "    gc.collect()\n",
-    "    sleep(0.5)\n",
-    "target.disconnect()\n",
-    "#hdf5.close()"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "## Cleanup"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "target.scope.dis()\n",
-    "scope.close()"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "## Analysis"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "from pyecsca.sca.trace.plot import plot_traces, plot_trace\n",
-    "import holoviews as hv\n",
-    "\n",
-    "hv.extension(\"bokeh\")"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "hdf5 = HDF5TraceSet.inplace(join(tmpdir.name, \"traces.h5\"))"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "from pyecsca.sca.trace.filter import filter_lowpass\n",
-    "\n",
-    "low1 = filter_lowpass(hdf5[0], 5_161_290, 9_000)\n",
-    "low2 = filter_lowpass(hdf5[1], 5_161_290, 9_000)\n",
-    "low3 = filter_lowpass(hdf5[2], 5_161_290, 9_000)"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "plot_traces(low1, low3).opts(width=950, height=600)"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "from scipy.signal import find_peaks"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "peaks1 = find_peaks(low1.samples, height=0.009)\n",
-    "peaks2 = find_peaks(low2.samples, height=0.009)"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "for i in range(len(peaks1[0])-1):\n",
-    "    print(peaks1[0][i+1] - peaks1[0][i])"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "from pyecsca.sca.trace import trim"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "l1peak1 = trim(low1, peaks1[0][2], peaks1[0][3])\n",
-    "l2peak1 = trim(low2, peaks2[0][3], peaks2[0][4])"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "from pyecsca.sca.trace import align_dtw"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "ts = align_dtw(l2peak1, l1peak1)"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "plot_traces(l2peak1, ts[1]).opts(width=950, height=600)"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": []
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": []
-  }
- ],
- "metadata": {
-  "@webio": {
-   "lastCommId": "02beaafccc8e44a58ca3713792d2a28b",
-   "lastKernelId": "a6e8a36e-c1a1-42a8-b785-d0f6e2db077f"
-  },
-  "hide_input": false,
-  "kernelspec": {
-   "display_name": "Python 3",
-   "language": "python",
-   "name": "python3"
-  },
-  "language_info": {
-   "codemirror_mode": {
-    "name": "ipython",
-    "version": 3
-   },
-   "file_extension": ".py",
-   "mimetype": "text/x-python",
-   "name": "python",
-   "nbconvert_exporter": "python",
-   "pygments_lexer": "ipython3",
-   "version": "3.8.2"
-  },
-  "latex_envs": {
-   "LaTeX_envs_menu_present": true,
-   "autoclose": false,
-   "autocomplete": true,
-   "bibliofile": "biblio.bib",
-   "cite_by": "apalike",
-   "current_citInitial": 1,
-   "eqLabelWithNumbers": true,
-   "eqNumInitial": 1,
-   "hotkeys": {
-    "equation": "Ctrl-E",
-    "itemize": "Ctrl-I"
-   },
-   "labels_anchors": false,
-   "latex_user_defs": false,
-   "report_style_numbering": false,
-   "user_envs_cfg": false
-  },
-  "pycharm": {
-   "stem_cell": {
-    "cell_type": "raw",
-    "metadata": {
-     "collapsed": false
-    },
-    "source": []
-   }
-  },
-  "toc": {
-   "base_numbering": 1,
-   "nav_menu": {},
-   "number_sections": true,
-   "sideBar": true,
-   "skip_h1_title": false,
-   "title_cell": "Table of Contents",
-   "title_sidebar": "Contents",
-   "toc_cell": false,
-   "toc_position": {},
-   "toc_section_display": true,
-   "toc_window_display": false
-  }
- },
- "nbformat": 4,
- "nbformat_minor": 4
-}