diff options
| -rw-r--r-- | README.md | 80 | ||||
| -rw-r--r-- | docs/api.rst | 12 | ||||
| -rw-r--r-- | docs/index.rst | 158 | ||||
| -rw-r--r-- | docs/installation.rst | 112 | ||||
| -rw-r--r-- | docs/libraries.rst | 6 | ||||
| -rw-r--r-- | docs/notebooks.rst | 21 | ||||
| -rw-r--r-- | docs/references.rst | 8 |
7 files changed, 172 insertions, 225 deletions
@@ -1,10 +1,10 @@ #  -[](https://neuromancer.sk/pyecsca/) [](https://github.com/J08nY/pyecsca/blob/master/LICENSE)   [](https://codecov.io/gh/J08nY/pyecsca)  [](https://deepsource.io/gh/J08nY/pyecsca/?ref=repository-badge) +[](https://pyecsca.org/) [](https://github.com/J08nY/pyecsca/blob/master/LICENSE)   [](https://codecov.io/gh/J08nY/pyecsca)  [](https://deepsource.io/gh/J08nY/pyecsca/?ref=repository-badge) **Py**thon **E**lliptic **C**urve cryptography **S**ide-**C**hannel **A**nalysis toolkit. -For more info, see the [](https://neuromancer.sk/pyecsca/). +For more info, see the [](https://pyecsca.org/). ## Functionality @@ -15,79 +15,21 @@ is to be able to reverse engineer the curve model, coordinate system, addition f multiplier and even finite-field implementation details. It currently provides: - - Enumeration of millions of possible ECC implementation configurations (see [notebook/configuration_space](https://neuromancer.sk/pyecsca/notebook/configuration_space.html)) - - Simulation and execution tracing of key generation, ECDH and ECDSA (see [notebook/simulation](https://neuromancer.sk/pyecsca/notebook/simulation.html)) - - Synthesis of C implementations of ECC for embedded devices, given any implementation configuration (see [notebook/codegen](https://neuromancer.sk/pyecsca/notebook/codegen.html)), - CPU-level simulation of implementations (see [notebook/simulator](https://neuromancer.sk/pyecsca/notebook/simulator.html)) - - Trace acquisition using PicoScope/ChipWhisperer oscilloscopes (see [notebook/measurement](https://neuromancer.sk/pyecsca/notebook/measurement.html)) - - Trace processing capabilities, e.g. signal-processing, filtering, averaging, cutting, aligning ([pyecsca.sca](https://neuromancer.sk/pyecsca/api/pyecsca.sca.html)) - - Trace visualization using holoviews and datashader (see [notebook/visualization](https://neuromancer.sk/pyecsca/notebook/visualization.html)) - - Communication via PCSC/LEIA with a smartcard target (see [notebook/smartcards](https://neuromancer.sk/pyecsca/notebook/smartcards.html)) + - Enumeration of millions of possible ECC implementation configurations (see [notebook/configuration_space](https://pyecsca.org/notebook/configuration_space.html)) + - Simulation and execution tracing of key generation, ECDH and ECDSA (see [notebook/simulation](https://pyecsca.org/notebook/simulation.html)) + - Synthesis of C implementations of ECC for embedded devices, given any implementation configuration (see [notebook/codegen](https://pyecsca.org/notebook/codegen.html)), + CPU-level simulation of implementations (see [notebook/simulator](https://pyecsca.org/notebook/simulator.html)) + - Trace acquisition using PicoScope/ChipWhisperer oscilloscopes (see [notebook/measurement](https://pyecsca.org/notebook/measurement.html)) + - Trace processing capabilities, e.g. signal-processing, filtering, averaging, cutting, aligning ([pyecsca.sca](https://pyecsca.org/api/pyecsca.sca.html)) + - Trace visualization using holoviews and datashader (see [notebook/visualization](https://pyecsca.org/notebook/visualization.html)) + - Communication via PCSC/LEIA with a smartcard target (see [notebook/smartcards](https://pyecsca.org/notebook/smartcards.html)) + - Reverse-engineering of black-box ECC via RPA-RE and ZVP-RE methods (see [notebook/re/rpa](https://pyecsca.org/notebook/re/rpa.html) and [notebook/re/zvp](https://pyecsca.org/notebook/re/zvp.html)) **pyecsca** consists of three packages: - the core: https://github.com/J08nY/pyecsca - the codegen package: https://github.com/J08nY/pyecsca-codegen - the notebook package: https://github.com/J08nY/pyecsca-notebook -## Requirements - - - [Numpy](https://www.numpy.org/) - - [Scipy](https://www.scipy.org/) - - [sympy](https://sympy.org/) - - [pandas](https://pandas.pydata.org/) - - [atpublic](https://public.readthedocs.io/) - - [fastdtw](https://github.com/slaypni/fastdtw) - - [asn1crypto](https://github.com/wbond/asn1crypto) - - [h5py](https://www.h5py.org/) - - [holoviews](https://holoviews.org) - - [bokeh](https://bokeh.org) - - [datashader](https://datashader.org) - - [matplotlib](https://matplotlib.org/) - - [xarray](https://xarray.pydata.org/en/stable/) - - [astunparse](https://astunparse.readthedocs.io/) - - [numba](https://numba.pydata.org/) - - **Optionally**: - - **Oscilloscope support:** - - [picosdk](https://github.com/picotech/picosdk-python-wrappers/) - - [picoscope](https://github.com/colinoflynn/pico-python) - - [chipwhisperer](https://github.com/newaetech/chipwhisperer) - - **Smartcard support:** - - [pyscard](https://pyscard.sourceforge.io/) - - **LEIA support:** - - [smartleia](https://pypi.org/project/smartleia/) - - **Faster arithmetic:** - - [gmpy2](https://gmpy2.readthedocs.io/) (and also GMP library) - - [cypari2](https://cypari2.readthedocs.io/) (and also PARI library) - -*pyecsca* contains data from the [Explicit-Formulas Database](https://www.hyperelliptic.org/EFD/index.html) by Daniel J. Bernstein and Tanja Lange. -The data was partially changed, to make working with it easier. It is available on Github at [crocs-muni/efd](https://github.com/crocs-muni/efd). - -It uses [ChipWhisperer](https://chipwhisperer.com) as one of its targets. It also supports working with [Riscure](https://www.riscure.com) Inspector -trace sets, which are of a proprietary format. - -### Testing & Development - -See the [Makefile](Makefile) for tests, performance measurement, codestyle and type checking commands. -Use [black](https://github.com/psf/black) for code-formatting. - - - [pytest](https://pytest.org) - - [mypy](http://mypy-lang.org/) - - [flake8](https://flake8.pycqa.org/) - - [coverage](https://coverage.readthedocs.io/) - - [interrogate](https://interrogate.readthedocs.io/) - - [pyinstrument](https://github.com/joerick/pyinstrument/) - - [pre-commit](https://pre-commit.com/) at `.pre-commit-config.yaml` - - [black](https://github.com/psf/black) - -### Docs - - - [sphinx](https://www.sphinx-doc.org/) - - [sphinx-autodoc-typehints](https://pypi.org/project/sphinx-autodoc-typehints/) - - [nbsphinx](https://nbsphinx.readthedocs.io/) - - [sphinx-paramlinks](https://pypi.org/project/sphinx-paramlinks/) - - [sphinx-design](https://sphinx-design.readthedocs.io/) - - ## License MIT License diff --git a/docs/api.rst b/docs/api.rst new file mode 100644 index 0000000..b9e6700 --- /dev/null +++ b/docs/api.rst @@ -0,0 +1,12 @@ +========================= +:fas:`code;fa-fw` API reference +========================= + +.. toctree:: + :titlesonly: + :maxdepth: 3 + + api/pyecsca.ec + api/pyecsca.misc + api/pyecsca.sca + api/pyecsca.codegen diff --git a/docs/index.rst b/docs/index.rst index 9680bb5..d51915b 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -55,6 +55,10 @@ It currently provides: Communication via PCSC/LEIA with a smartcard target (see :doc:`notebook/smartcards`) +.. card:: Reverse-engineering + + Reverse-engineering of black-box ECC via RPA-RE and ZVP-RE methods (see :doc:`notebook/re/rpa` and :doc:`notebook/re/zvp`) + **pyecsca** consists of three repositories: .. grid:: 3 @@ -74,123 +78,18 @@ It currently provides: The `notebook <https://github.com/J08nY/pyecsca-notebook>`_ repository contains example notebooks that showcase functionality of the toolkit. - -:fas:`book` Notebooks -========================= -The notebooks below contain a showcase of what is possible using **pyecsca** and -are the best source of documentation on how to use **pyecsca**. - .. toctree:: - :caption: Notebooks + :hidden: :titlesonly: - :maxdepth: 1 - - notebook/configuration_space - notebook/simulation - notebook/codegen - notebook/emulator - notebook/measurement - notebook/visualization - notebook/smartcards - notebook/re/formulas - notebook/re/rpa - notebook/re/zvp - notebook/re/epa - - -:fas:`code` API reference -========================= - -.. toctree:: - :caption: API reference - :titlesonly: - :maxdepth: 3 - - api/pyecsca.ec - api/pyecsca.misc - api/pyecsca.sca - api/pyecsca.codegen - -:fas:`file` Miscellaneous -========================= - -.. toctree:: - :caption: Miscellaneous - :titlesonly: - :maxdepth: 1 + :maxdepth: 2 + installation + notebooks + api libraries references -Requirements -============ - -.. dropdown:: General - - - Numpy_ - - Scipy_ - - sympy_ - - pandas_ - - atpublic_ - - fastdtw_ - - asn1crypto_ - - h5py_ - - holoviews_ - - bokeh_ - - datashader_ - - matplotlib_ - - xarray_ - - astunparse_ - - numba_ - - - **Optionally**: - - - **Oscilloscope support:** - - - picosdk_ - - picoscope_ - - chipwhisperer_ - - **Smartcard support:** - - - pyscard_ - - **LEIA support:** - - - leia_ - - **Faster arithmetic:** - - - gmpy2_ (and also GMP library) - - cypari2_ (and also PARI library) - - *pyecsca* contains data from the `Explicit-Formulas Database`_ by Daniel J. Bernstein and Tanja Lange. - The data was partially changed, to make working with it easier. It is available on Github at `crocs-muni/efd`_. - - It uses `ChipWhisperer`_ as one of its targets. It also supports working with Riscure_ Inspector trace sets, which are of a proprietary format. - - -.. dropdown:: Testing & Development - - See the Makefile for tests, performance measurement, codestyle and type checking commands. - Use black_ for code-formatting. - - - pytest_ - - mypy_ - - flake8_ - - coverage_ - - interrogate_ - - pyinstrument_ - - pre-commit_ - - black_ - - -.. dropdown:: Docs - - - sphinx_ - - sphinx-autodoc-typehints_ - - nbsphinx_ - - sphinx-paramlinks_ - - sphinx-design_ - License ======= @@ -222,42 +121,3 @@ Thanks alot to contributors: Tomas Jusko, Andrej Batora, Vojtech Suchanek and to ChipWhisperer/NewAE. Development was supported by the Masaryk University grant `MUNI/C/1707/2018 <https://www.muni.cz/en/research/projects/46834>`_. - -.. _Numpy: https://www.numpy.org -.. _Scipy: https://www.scipy.org -.. _sympy: https://sympy.org/ -.. _pandas: https://pandas.pydata.org/ -.. _matplotlib: https://matplotlib.org/ -.. _atpublic: https://public.readthedocs.io/ -.. _fastdtw: https://github.com/slaypni/fastdtw -.. _asn1crypto: https://github.com/wbond/asn1crypto -.. _h5py: https://www.h5py.org/ -.. _holoviews: https://holoviews.org -.. _bokeh: https://bokeh.org -.. _datashader: https://datashader.org -.. _xarray: https://xarray.pydata.org/en/stable/ -.. _astunparse: https://astunparse.readthedocs.io/ -.. _numba: https://numba.pydata.org/ -.. _picosdk: https://github.com/picotech/picosdk-python-wrappers/ -.. _picoscope: https://github.com/colinoflynn/pico-python -.. _pyscard: https://pyscard.sourceforge.io/ -.. _leia: https://pypi.org/project/smartleia/ -.. _gmpy2: https://gmpy2.readthedocs.io/ -.. _cypari2: https://cypari2.readthedocs.io/ -.. _pytest: https://pytest.org -.. _mypy: http://mypy-lang.org/ -.. _flake8: https://flake8.pycqa.org/ -.. _coverage: https://coverage.readthedocs.io/ -.. _interrogate: https://interrogate.readthedocs.io/ -.. _pyinstrument: https://github.com/joerick/pyinstrument/ -.. _pre-commit: https://pre-commit.com -.. _black: https://github.com/psf/black -.. _sphinx: https://www.sphinx-doc.org/ -.. _sphinx-autodoc-typehints: https://pypi.org/project/sphinx-autodoc-typehints/ -.. _nbsphinx: https://nbsphinx.readthedocs.io/ -.. _sphinx-paramlinks: https://pypi.org/project/sphinx-paramlinks/ -.. _sphinx-design: https://pypi.org/project/sphinx_design/ -.. _Explicit-Formulas Database: https://www.hyperelliptic.org/EFD/index.html -.. _crocs-muni/efd: https://github.com/crocs-muni/efd -.. _ChipWhisperer: https://chipwhisperer.com -.. _Riscure: https://www.riscure.com/ diff --git a/docs/installation.rst b/docs/installation.rst new file mode 100644 index 0000000..d973a02 --- /dev/null +++ b/docs/installation.rst @@ -0,0 +1,112 @@ +============================================ +:fas:`screwdriver-wrench;fa-fw` Installation +============================================ + +Requirements +============ + +.. dropdown:: General + :open: + + - Numpy_ + - Scipy_ + - sympy_ + - pandas_ + - atpublic_ + - fastdtw_ + - asn1crypto_ + - h5py_ + - holoviews_ + - bokeh_ + - datashader_ + - matplotlib_ + - xarray_ + - astunparse_ + - numba_ + + - **Optionally**: + + - **Oscilloscope support:** + + - picosdk_ + - picoscope_ + - chipwhisperer_ + - **Smartcard support:** + + - pyscard_ + - **LEIA support:** + + - leia_ + - **Faster arithmetic:** + + - gmpy2_ (and also GMP library) + - cypari2_ (and also PARI library) + + *pyecsca* contains data from the `Explicit-Formulas Database`_ by Daniel J. Bernstein and Tanja Lange. + The data was partially changed, to make working with it easier. It is available on Github at `crocs-muni/efd`_. + + It uses `ChipWhisperer`_ as one of its targets. It also supports working with Riscure_ Inspector trace sets, which are of a proprietary format. + + +.. dropdown:: Testing & Development + + See the Makefile for tests, performance measurement, codestyle and type checking commands. + Use black_ for code-formatting. + + - pytest_ + - mypy_ + - flake8_ + - coverage_ + - interrogate_ + - pyinstrument_ + - pre-commit_ + - black_ + + +.. dropdown:: Docs + + - sphinx_ + - sphinx-autodoc-typehints_ + - nbsphinx_ + - sphinx-paramlinks_ + - sphinx-design_ + + +.. _Numpy: https://www.numpy.org +.. _Scipy: https://www.scipy.org +.. _sympy: https://sympy.org/ +.. _pandas: https://pandas.pydata.org/ +.. _matplotlib: https://matplotlib.org/ +.. _atpublic: https://public.readthedocs.io/ +.. _fastdtw: https://github.com/slaypni/fastdtw +.. _asn1crypto: https://github.com/wbond/asn1crypto +.. _h5py: https://www.h5py.org/ +.. _holoviews: https://holoviews.org +.. _bokeh: https://bokeh.org +.. _datashader: https://datashader.org +.. _xarray: https://xarray.pydata.org/en/stable/ +.. _astunparse: https://astunparse.readthedocs.io/ +.. _numba: https://numba.pydata.org/ +.. _picosdk: https://github.com/picotech/picosdk-python-wrappers/ +.. _picoscope: https://github.com/colinoflynn/pico-python +.. _pyscard: https://pyscard.sourceforge.io/ +.. _leia: https://pypi.org/project/smartleia/ +.. _gmpy2: https://gmpy2.readthedocs.io/ +.. _cypari2: https://cypari2.readthedocs.io/ +.. _pytest: https://pytest.org +.. _mypy: http://mypy-lang.org/ +.. _flake8: https://flake8.pycqa.org/ +.. _coverage: https://coverage.readthedocs.io/ +.. _interrogate: https://interrogate.readthedocs.io/ +.. _pyinstrument: https://github.com/joerick/pyinstrument/ +.. _pre-commit: https://pre-commit.com +.. _black: https://github.com/psf/black +.. _sphinx: https://www.sphinx-doc.org/ +.. _sphinx-autodoc-typehints: https://pypi.org/project/sphinx-autodoc-typehints/ +.. _nbsphinx: https://nbsphinx.readthedocs.io/ +.. _sphinx-paramlinks: https://pypi.org/project/sphinx-paramlinks/ +.. _sphinx-design: https://pypi.org/project/sphinx_design/ +.. _Explicit-Formulas Database: https://www.hyperelliptic.org/EFD/index.html +.. _crocs-muni/efd: https://github.com/crocs-muni/efd +.. _ChipWhisperer: https://chipwhisperer.com +.. _Riscure: https://www.riscure.com/ diff --git a/docs/libraries.rst b/docs/libraries.rst index 63a8c66..abee51b 100644 --- a/docs/libraries.rst +++ b/docs/libraries.rst @@ -1,6 +1,6 @@ -================ -ECC in Libraries -================ +============================== +:fas:`server;fa-fw` ECC in Libraries +============================== .. contents:: Table of Contents :backlinks: none diff --git a/docs/notebooks.rst b/docs/notebooks.rst new file mode 100644 index 0000000..e4d3466 --- /dev/null +++ b/docs/notebooks.rst @@ -0,0 +1,21 @@ +===================== +:fas:`hand-pointer;fa-fw` Notebooks +===================== +The notebooks below contain a showcase of what is possible using **pyecsca** and +are the best source of documentation on how to use **pyecsca**. + +.. toctree:: + :titlesonly: + :maxdepth: 1 + + notebook/configuration_space + notebook/simulation + notebook/codegen + notebook/emulator + notebook/measurement + notebook/visualization + notebook/smartcards + notebook/re/formulas + notebook/re/rpa + notebook/re/zvp + notebook/re/epa diff --git a/docs/references.rst b/docs/references.rst index 675a13a..c5ae1e1 100644 --- a/docs/references.rst +++ b/docs/references.rst @@ -1,6 +1,6 @@ -========== -References -========== +========================== +:fas:`asterisk;fa-fw` References +========================== .. [STD] Standard Curve Database, https://neuromancer.sk/std/ .. [EFD] Explicit Formulas Database, https://hyperelliptic.org/EFD/ @@ -17,4 +17,4 @@ References .. [DJB02] D.J. Bernstein: Pippenger's Exponentiation Algorithm, https://cr.yp.to/papers/pippenger.pdf .. [SG14] Shay Gueron & Vlad Krasnov. Fast prime field elliptic-curve cryptography with 256-bit primes, https://link.springer.com/article/10.1007/s13389-014-0090-x .. [B51] Andrew D. Booth. A signed binary multiplication technique. -.. [M61] O. L. Macsorley. High-speed arithmetic in binary computers. +.. [M61] O.L. Macsorley. High-speed arithmetic in binary computers. |