From 835aaf27b0d19a22e753b060142aa992ebb648eb Mon Sep 17 00:00:00 2001 From: J08nY Date: Tue, 16 Jul 2024 17:21:44 +0200 Subject: Improve installation docs. --- docs/index.rst | 8 ++--- docs/installation.rst | 90 ++++++++++++++++++++++++++++++++++++++++++++++----- 2 files changed, 85 insertions(+), 13 deletions(-) (limited to 'docs') diff --git a/docs/index.rst b/docs/index.rst index 67fd929..34abac6 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -19,9 +19,7 @@ pyecsca [pɪɛtska] **pyecsca** aims to fill a gap in SCA tooling for Elliptic Curve Cryptography, it focuses on black-box implementations of ECC and presents a way to extract implementation information -about a black-box implementation of ECC through side-channels. The main goal of **pyecsca** -is to be able to reverse engineer the curve model, coordinate system, addition formulas, scalar -multiplier and even finite-field implementation details. +about a black-box implementation of ECC through side-channels. It currently provides: @@ -64,12 +62,12 @@ It currently provides: .. grid-item-card:: Core - The `core `_ package contains the core of the + The `core `_ repository contains the core of the functionality, except the code generation and notebooks. .. grid-item-card:: Codegen - The `codegen `_ package contains + The `codegen `_ repository contains the code generation functionality. .. grid-item-card:: Notebook diff --git a/docs/installation.rst b/docs/installation.rst index 55277a6..551fd5f 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -2,8 +2,64 @@ :fas:`screwdriver-wrench;fa-fw` Installation ============================================ +**pyecsca** consists of three repositories: + +.. grid:: 1 1 3 3 + + .. grid-item-card:: Core + + The `core `_ repository contains the core of the + functionality, except the code generation and notebooks. + + .. grid-item-card:: Codegen + + The `codegen `_ repository contains + the code generation functionality. + + .. grid-item-card:: Notebook + + The `notebook `_ repository contains + example notebooks that showcase functionality of the toolkit. + + +Core +==== + +The core package can be installed either from `pypi `__ or from the +`source repository `__. There are several extras that can be installed: + +- `picoscope_sdk` to enable support for PicoScope oscilloscopes using the picosdk_ package. +- `picoscope_alt` to enable support for PicoScope oscilloscopes using the picoscope_ package. +- `chipwhisperer` to enable support for ChipWhisperer_ targets and oscilloscopes. +- `smartcard` to enable support for smartcard targets using the pyscard_ package. +- `leia` to enable support for smartcard targets using the leia_ (smartleia) package. +- `gmp` to enable arithmetic via gmpy2_ (which may or may not be faster). +- `flint` to enable arithmetic via python-flint_ (which may or may not be faster). +- `pari` to enable faster division polynomial computation using cypari2_. +- `dev` to install several packages used in development. +- `test` to install several packages used for testing. +- `doc` to install several packages used for building documentation. + +You can install these extras like this: + +.. code-block:: shell + + pip install pyecsca[smartcard,gmp] + +.. note:: + + The core repository uses git submodules, make sure to check them out after cloning with: ``git submodule update --init``. + + +The core package 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. + +Optionally, you can Cythonize the ``pyecsca/ec/mod`` subpackage and sometimes gain a performance benefit, YMMV. + Requirements -============ +------------ .. dropdown:: General :open: @@ -43,13 +99,6 @@ Requirements - python-flint_ (and also Flint 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. - - Optionally, you can Cythonize the `pyecsca/ec/mod` subpackage and sometimes gain a performance benefit, YMMV. - .. dropdown:: Testing & Development See the Makefile for tests, performance measurement, codestyle and type checking commands. @@ -73,6 +122,31 @@ Requirements - sphinx-paramlinks_ - sphinx-design_ +Codegen +======= + +The codegen package requires (and bundles in ``ext/libtommath`` as a git submodule) a version +of the libtommath library. The package can be either installed from `pypi `__ or from the +`source repository `__. Note that currently, the pypi project +contains the built package for x86_64 Linux only. Thus, installation from source is preferable. + +Assuming you have ``make``, a C compiler and a C cross-compiler for ```arm-none-eabi`` you can just run: + +.. code-block:: shell + + pip install . + +inside the codegen repository and it should be built and installed automatically. + +.. note:: + + The codegen repository uses git submodules, make sure to check them out after cloning with: ``git submodule update --init``. + +Notebooks +========= + +The notebook repository is included as a submodule in the core repository. +However, this version can get outdated during active development. .. _Numpy: https://www.numpy.org .. _Scipy: https://www.scipy.org -- cgit v1.2.3-70-g09d2