DiSSECT: Distinguisher of Standard & Simulated Elliptic Curves via Traits

DiSSECT is, to the best of our knowledge, the largest publicly available database of standardized elliptic curves (taken from our sister project) and offers generation of simulated curves according to the mentioned standards. The tool contains over 20 tests (which we call traits), each computing curve properties, ranging from classical algebraic ones to unconventional ones and those connected to implementations. After obtaining their empirical distributions, the traits allow us to compare the simulated curves to the standard ones. Finally, DiSSECT provides an easy-to-use interface for implementations of custom traits and their interactive visualization via Jupyter notebook.

DiSSECT is written in Python 3 and imports the SageMath library. The database of the standardized elliptic curves as well as the simulated ones with the results of the traits, including the visualization, can be found at https://dissect.crocs.fi.muni.cz/. DiSSECT is open-source and we welcome any collaborators who have an idea for a new trait, new simulation method, or just want to contribute in another way.

Authors

• Vladimír Sedláček
• Vojtěch Suchánek
• Antonín Dufka

Thanks to Ján Jančár for help with the curve database and CRoCS members for fruitful discussions. Computational resources were supplied by the project "e-Infrastruktura CZ" (e-INFRA LM2018140) provided within the program Projects of Large Research, Development and Innovations Infrastructures.

Installation

We recommend to use DiSSECT in Docker, as it avoids potential issues on the boundary of Sage and Python environments. If you still want to run DiSSECT locally, see the Local setup section.

Docker container

To run the analysis notebook in a container, use the following command and access the provided link in your web browser.

docker run -it -p 8888:8888 crocsmuni/dissect

To use advanced components of DiSSECT, access the container directly:

docker run -it crocsmuni/dissect bash

Local setup

Full (requires sage)

If you plan on computing traits, you need to perform full instalation of DiSSECT using Sage.

git clone --recurse-submodules https://github.com/crocs-muni/DiSSECT.git
cd DiSSECT
sage --python3 -m venv --system-site-packages venv
source venv/bin/activate
pip install .
python -m ipykernel install --user --name=venv
jupyter notebook dissect/analysis/playground.ipynb

Analysis-only

If you only need to access DiSSECT database, inspect the data, and perform analyses, Python-based installation will suffice.

git clone --recurse-submodules https://github.com/crocs-muni/DiSSECT.git
cd DiSSECT
python -m venv venv
source venv/bin/activate
pip install .
python -m ipykernel install --user --name=venv
jupyter notebook dissect/analysis/playground.ipynb

Commands

To run these commands, you need a working installation of DiSSECT – either in an interactive container or a local one. If you plan to share files between host and the docker container, you may want to use a bind mount (e.g., --mount type=bind,src=/tmp/dissect,dst=/data).

Computing traits

DiSSECT provides two ways of computing traits: a simple one suitable for working with just JSON files, and more complex one that supports parallelization but requires database, intended mainly for large-scale trait computation.

To compute traits on a JSON of curves, use:

dissect-compute-json -t TRAIT_NAME -i CURVES_JSON [-o OUTPUT_JSON]

To compute traits with database, use:

dissect-compute-db -t TRAIT_NAME --database DATABASE_URL

By default, the command uses all available curves. You can filter them using optional arguments, see the help menu (-h).

Performing the analysis

To run analysis notebook, use the following command and select the venv kernel.

jupyter notebook dissect/analysis/playground.ipynb

Alternatively, you may try using the notebook directly in your browser using Colab.

Automated analysis

In order to run automated analysis of trait results, feature vectors need to be constructed. They can be built from results of individual traits using repeated invocations of dissect-feature_builder. For example, the following sequence of commands builds set of feature vectors of torsion_extension and small_prime_order traits for 256-bit curves from the standard and simulated X9.62 categories.

dissect-feature_builder --trait torsion_extension --category x962 x962_sim --bits 256 --input features.csv --output features.csv
dissect-feature_builder --trait small_prime_order --category x962 x962_sim --bits 256 --input features.csv --output features.csv

By default, this command uses a dataset available from our database, but you may supply a different source using the --source option (url to a database).

The feature vectors output by the previous commands can be processed by the outlier detection script:

dissect-feature_outliers features.csv outliers.csv

If the outlier detection gave an interesting output, you may inspect features of a particular curve with:

dissect-feature_detail features.csv CURVE_NAME

Another approach to automated analysis implemented in DiSSECT is clustering. Clustering requires feature vectors curves of two distinct categories and running feature_builder with --keep-category option. Then, it can be run as:

dissect-feature_clusters features.csv outliers.csv

Database

Command dissect-database provides a simple interface for import/export of database data. To use this command you have to provide database URL which should be a string in format "mongodb://USERNAME:PASSWORD@HOST/" (e.g., "mongodb://root:password@mongo:27017/) and select whether you want to import or export data.

Curves can be imported from a JSON file with the following command:

dissect-database [DATABASE_URL] import -i <CURVE_JSON>

Trait results can be imported using the same command, but the file name has to start with trait_ prefix, for example, trait_cofactor.json:

dissect-database [DATABASE_URL] import -i <TRAIT_RESULTS_JSON>

To export curves, use:

dissect-database [DATABASE_URL] export --no-traits -o <CURVE_JSON>

To export a selected trait results, use:

dissect-database [DATABASE_URL] export --no-curves --trait <TRAIT_NAME> -o <TRAIT_RESULTS_JSON>

All records in the database can be exported and imported using the following commands.

dissect-database [DATABASE_URL] export [-o <DATABASE_TAR>]
dissect-database [DATABASE_URL] import [-i <DATABASE_TAR>]