Release v2.0.0 (#224)

* refactor: Base sage docstrings migration to python * fix: doctests using ^ instead of ** * refactor: include Base doctests in makefile * Fix command docker-pytest-doctests-fast * fix: docstrings from PR comments * fix: remove TODO comments * fix: docstrings HTML generation * fix: make docker-pytest-doctests-fast * refactor: rename makefile testing commands * fix: CI jobs * fix: Make command with non-existent file * refactor: custom sphinx extension in docs * Remove html files * Refactor:Update docker-doctests-fast command * Refactor: update Makefile * Refactor: update Makefile * Refactor: update Makefile * Refactor:Update Makefile * Reactor:Update Makefile * Refactor:Update Makefile * Refactor:Update Makefile * Fix docker-doctest command * Fix: mayo estimator missing import pytest * Fix: BIKEEstimator missing import pytest * Fix: UOVE missing import pystes * Fix: missing import pytest in LEEstimator * Fix: missing import pytest in PKEstimator * Fix: missing import pytest in PEEstimator * Refactor: Adding missing reference in UOVEstimator * Refactor: Update Makefile * Refactor: removing very long tests from MAYOEstimator * refactor: remove leon KAT test Reasoning for this removal can be found at: #181 (comment) * fix: add important flag for kat * refactor: remove sage from mr estimator - Replace the usage of power series for minors_series related operations by using Sympy polynomials and matrices. - Migration of any other Sage function into the python native ones. * Refactor: Update documentation base estimator * fix: le_beullens kat tests * Fix: add missing make file commands * fix: le_bpps first issues * Update le.py * Refacto: Update kat.yaml file * Refactor:Kat files * fix: CI and clean tests directory * refactor: remove remaining Sage imports * refactor: Implementation of pyproject.toml - Implementation of an equivalent pyproject.toml for the old setup.py, as pyproject.toml is the new python standard. - Update of a dummy dockerfile optimizing layer caching while not hardcoding dependencies. * refactor: update and improve Makefile - Creation of an equivalent local command for every docker-based command in the Makefile - Improve general readability and maintainability. * Refactor:add percentage couting in doctests * Refactor: reduce time of short doctests in MREstimator * fix: KAT types casting to python float * refactor: final docker/makefile and .toml * Refactor: use pip3 instead of pip * Fix: adding sympy dependency * Fix: doctest MQEstimator * fix: EstimationRenderer rounding values * fix: remove sage from CI jobs * fixxed warning from numpy (#202) Co-authored-by: Floyd <[email protected]> * Update Makefile Add percentage counting for doctests * Fix:set_parameters functionality in Crossbred * Refactor: fix doc crossbred * revert * Fix: memory complexity and reafacto MinRank Estimator * Refactor:minors algorithm in MinRank * Refactor:update readme * Add links to the schemes' webpages in Readme * Feature: add input dictionary of MAYO * feat: A new set of classes for RSDProblem * adds some validations and changes some names * adding more features * More combinatorial algorithms * More combinatorial algorithms * feat: some new algorithms added to RSDEstimator * feat: Adding more algorithms * feat: some deletions * refactor: some deletions * feat: adding memory complexity * Docs: Adding comments to the code * docs: adding some tests and comments * refactor: Delete some code * refactor some code * docs: Added comments to algorithm classes * docs: Added comments to algorithm classes * docs: Added comments to algorithm classes * README changes * docs: updated some docs * fix: Fixing some errors * refactor: renaming of classes * refactor: addressing comments by reviewers * docs: Documentation only changes * fix: support multiline kwargs parameters * Adds RankSD to the imput_dictionary.json * fix: SM memory estimate * docs: revamp documentation * refactor: improve kwargs formatting code * refactor: cleanup * Refactor some code and add a new algorithm (HL) * Refactor: references.rst file in alphabetic order by first author last name * Refactor:remove warnings of missing references, todos, unexpected indentention etc * feat: initial structure * docs: Identation of kwargs, format of references and comments * feat: time_complexity hashimoto * feat: memory_complexity hashimoto * feat: update mq_estimator tests * fix: minnor fix in the doctests * docs: improve docs * fix: update UOV/MAYO doctests * fix: update uov_estimator doctests * refactor: add comments for the kwargs_formatter extension * refactor: replace "serie" by "series" on series-related signatures * Refactor: docs, examples and tests * Fix: Adding missing validations and fixing some comments * Refactor:edit README * Refactor: updated user_guide * Update doc link in user_guide * Refactor:docstring in add_new_estimator guide * Refactor: currently we use relative imports * Refactor: small edit in docs/github/contributing * Fix: Validating some corner cases * adjusting a plus * Refactor: increase repetitions beullens algo in PEEstimator * refactor: Minor Changes * Add underfined condition to Hashimoto * Refactors: updates MQ doctests for updated Hashimoto * refactor: improve kat test prompting on fail * docs: removing some unused imports and a doctest * refactor: Arranging some imports * Refector order of inputs in references.rst * fix: remove MQEstimator from mayo direct_attack * fix: update doctests in mayo_estimator and mayo direct_attack * Speed up hashimoto and add mayo direct_attack optimal params * feat: added bike perliminary gui * Refactor: update test in UOV * fix: remove duplicate estimator entry * Fix: degree regulairty Minors in MREstimator * feat: release v2.0.0 --------- Co-authored-by: Dioprz <[email protected]> Co-authored-by: Javierverbel <[email protected]> Co-authored-by: javier.verbel <[email protected]> Co-authored-by: FloydZ <[email protected]> Co-authored-by: Floyd <[email protected]> Co-authored-by: Floyd <[email protected]> Co-authored-by: ricardovp85 <[email protected]> Co-authored-by: fmerino21 <[email protected]> Co-authored-by: Memphisd <[email protected]>
Crypto-TII · Dec 20, 2024 · 0d9bd3f · 0d9bd3f
1 parent 9637e57
commit 0d9bd3f
Show file tree

Hide file tree

Showing 615 changed files with 57,190 additions and 104,393 deletions.
diff --git a/.github/workflows/build-and-test.yml b/.github/workflows/build-and-test.yml
@@ -4,26 +4,22 @@ on:
     types: [opened, synchronize, reopened, edited]
     branches:
       - develop
-
 jobs:
   build-and-run-tests:
     runs-on: ubuntu-22.04
     concurrency: ci-${{github.ref}}
     steps:
       - name: Checkout
         uses: actions/checkout@v3
-
       - name: Set up Docker Buildx
         uses: docker/setup-buildx-action@v2
-
       - name: Cache Docker layers
         uses: actions/cache@v3
         with:
           path: /tmp/.buildx-cache
           key: ${{ runner.os }}-buildx-${{ github.sha }}
           restore-keys: |
             ${{ runner.os }}-buildx-
-
       - name: Build
         uses: docker/build-push-action@v4
         id: built-image
@@ -34,11 +30,9 @@ jobs:
           tags: estimators-lib:latest
           cache-from: type=local,src=/tmp/.buildx-cache
           cache-to: type=local,dest=/tmp/.buildx-cache-new,mode=max
-
       - name: Move cache
         run: |
           rm -rf /tmp/.buildx-cache
           mv /tmp/.buildx-cache-new /tmp/.buildx-cache
-
-      - name: Run tests
-        run: make docker-test
+      - name: Run functional, doctests and KAT tests
+        run: make docker-tests-all
diff --git a/Dockerfile b/Dockerfile
@@ -1,9 +1,13 @@
 FROM ubuntu:22.04
 ENV DEBIAN_FRONTEND=noninteractiv
-RUN apt update && apt install -y sagemath
-RUN sage -python3 -m pip install prettytable scipy sphinx==5.3.0 furo pytest pytest-cov python-flint
+ENV SAGE_PKGS=/usr/share/sagemath/installed
 WORKDIR "/home/cryptographic_estimators/"
+RUN apt update && apt install -y sagemath && pip install toml
+# Avoid the download and installation of dependencies on rebuild; 
+# but without harcoding them
+COPY ./pyproject.toml ./
+COPY ./scripts/generate_requirements.py ./scripts/
+RUN python3 scripts/generate_requirements.py
+RUN sage -python3 -m pip install -r requirements.txt && rm -r ./*
 COPY . .
-ENV SAGE_PKGS=/usr/share/sagemath/installed
-RUN sage setup.py install
-RUN sage -python3 -m pip install .
+RUN sage -python3 -m pip install --no-deps .
diff --git a/Makefile b/Makefile
@@ -1,41 +1,34 @@
-# Docker variables
-image_name=estimators-lib:latest
-documentation_path=$(shell pwd)
-container_name="container-for-docs"
-SAGE=sage
-PACKAGE=cryptographic_estimators
-UNAME:=$(shell uname -m)
+## Docker variables
+IMAGE_NAME = estimators-lib:latest
+DOCUMENTATION_PATH = $(shell pwd)
+PACKAGE = cryptographic_estimators
+MACHINE_ARCHITECTURE := $(shell uname -m)
 
-tools:
-	@sage -python -m pip install setuptools==63.0 wheel==0.38.4 sphinx==5.3.0 furo prettytable scipy pytest python-flint
+DOCTESTS_COMMAND = pytest --doctest-modules -n auto -vv $(PACKAGE)/
+DOCTESTS_FAST_COMMAND = pytest --skip-long-doctests  --doctest-modules -n auto -vv $(PACKAGE)/
+KAT_TESTS_COMMAND = pytest -n auto -vv tests/test_kat.py
+FUNCTIONAL_TESTS_COMMAND = pytest --doctest-modules -n auto -vv \
+													 tests/test_sd.py \
+													 tests/test_mq.py
 
-lib:
-	@python3 setup.py install && sage -python -m pip install .
 
+## Local commands
 install:
-	@make tools && make lib
+	@pip3 install -e .
 
-docker-build-x86:
-	@docker build -t ${image_name} .
-
-docker-build-m1:
-	@docker buildx build -t ${image_name} --platform linux/x86_64 .
+doctests-fast:
+	@${DOCTESTS_FAST_COMMAND}
 
-docker-build:
-ifeq ($(UNAME), arm64)
-	@make docker-build-m1
-else
-	@make docker-build-x86
-endif 
+doctests:
+	@${DOCTESTS_COMMAND}
 
-docker-run:
-	@docker run -it --rm ${image_name}
+kat-tests:
+	@${KAT_TESTS_COMMAND}
 
-testfast:
-	@sage setup.py testfast
+functional-tests:
+	@${FUNCTIONAL_TESTS_COMMAND}
 
-testall: install
-	@sage setup.py testall
+tests-all: functional-tests doctests kat-tests
 
 clean-docs:
 	@rm -rf docs/build docs/source docs/make.bat docs/Makefile
@@ -52,35 +45,84 @@ create-html-docs:
 doc:
 	@make clean-docs && make create-sphinx-config && make create-rst-files && make create-html-docs
 
+add-copyright:
+	@python3 scripts/create_copyright.py
+
 add-estimator:
 	@python3 scripts/create_new_estimator.py && make add-copyright
 
 append-new-estimator:
 	@python3 scripts/append_estimator_to_input_dictionary.py
 
-stop-container-and-remove:
-	@docker stop $(container_name) && docker rm $(container_name)
-
+### Docker commands
 generate-documentation:
 	@docker exec container-for-docs make doc
 
 mount-volume-and-run: 
-	@docker run --name container-for-docs --mount type=bind,source=${documentation_path}/docs,target=/home/cryptographic_estimators/docs -d -it ${image_name} sh
+	@docker run --name container-for-docs --mount type=bind,source=${DOCUMENTATION_PATH}/docs,target=/home/cryptographic_estimators/docs -d -it ${IMAGE_NAME} sh
 
-docker-doc: docker-build
-	@make mount-volume-and-run && make generate-documentation && make stop-container-and-remove container_name="container-for-docs"
+docker-build-x86:
+	@docker build -t ${IMAGE_NAME} .
 
-docker-test: docker-build
-	@docker run --name container-for-test -d -it ${image_name} sh && docker exec container-for-test sage -t --long -T 3600 --force-lib cryptographic_estimators && docker stop container-for-test && docker rm container-for-test
+docker-build-m1:
+	@docker buildx build -t ${IMAGE_NAME} --platform linux/x86_64 .
 
-docker-testfast: docker-build
-	@docker run --name container-for-test -d -it ${image_name} sh && docker exec container-for-test sage -t cryptographic_estimators && make stop-container-and-remove container_name="container-for-test"
+docker-build:
+ifeq ($(MACHINE_ARCHITECTURE), arm64)
+	@make docker-build-m1
+else
+	@make docker-build-x86
+endif 
 
-add-copyright:
-	@python3 scripts/create_copyright.py
+docker-run: docker-build
+	@docker run -it --rm ${IMAGE_NAME}
 
-docker-pytest:
-	@docker run --name pytest-estimators -d -it ${image_name} sh && docker exec pytest-estimators sh -c "sage --python3 -m pytest -vv --cov-report xml:coverage.xml --cov=${PACKAGE} && ${SAGE} tests/test_sdfq.sage && ${SAGE} tests/test_le_beullens.sage && ${SAGE} tests/test_le_bbps.sage && ${SAGE} tests/test_pe.sage && ${SAGE} tests/test_pk.sage"  && make stop-container-and-remove container_name="pytest-estimators"
+stop-container-and-remove:
+	@echo "Cleaning any previous container...."
+	@docker stop $(container_name) || true
+	@docker rm $(container_name) || true
+
+docker-doc: docker-build
+	@make stop-container-and-remove container_name="container-for-docs" \
+		|| true
+	@make mount-volume-and-run && make generate-documentation && make stop-container-and-remove container_name="container-for-docs"
+
+docker-doctests: CONTAINER_NAME := "pytest-container"
+docker-doctests: docker-build
+	@make stop-container-and-remove container_name=${CONTAINER_NAME} \
+		|| true
+	@echo "Running doctests..."
+	@docker run --name ${CONTAINER_NAME} --rm ${IMAGE_NAME} sh -c "${DOCTESTS_COMMAND}"
+
+docker-doctests-fast: CONTAINER_NAME := "pytest-container"
+docker-doctests-fast: docker-build
+	@make stop-container-and-remove container_name=${CONTAINER_NAME} \
+	    || true
+	@echo "Running short doctests..."
+	@docker run --name ${CONTAINER_NAME} --rm -it ${IMAGE_NAME} sh -c "${DOCTESTS_FAST_COMMAND}"
+
+docker-kat-tests: CONTAINER_NAME := "pytest-container"
+docker-kat-tests: docker-build
+	@make stop-container-and-remove container_name=${CONTAINER_NAME} \
+		|| true
+	@echo "Running KAT..."
+	@docker run --name ${CONTAINER_NAME} --rm ${IMAGE_NAME} sh -c "${KAT_TESTS_COMMAND}"
+
+docker-functional-tests: CONTAINER_NAME := "pytest-container"
+docker-functional-tests: docker-build
+	@make stop-container-and-remove container_name=${CONTAINER_NAME} \
+		|| true
+	@echo "Running functional tests..."
+	@docker run --name ${CONTAINER_NAME} --rm ${IMAGE_NAME} sh -c "${FUNCTIONAL_TESTS_COMMAND}"
+
+docker-tests-all: CONTAINER_NAME := "pytest-container"
+docker-tests-all: docker-functional-tests docker-doctests docker-kat-tests
 
 docker-pytest-cov:
 	pytest -v --cov-report xml:coverage.xml --cov=${PACKAGE} tests/
+
+docker-generate-kat: docker-build
+	@docker run --name kat-container -v ./tests:/home/cryptographic_estimators/tests --rm ${IMAGE_NAME} sh -c \
+		"sage tests/external_estimators/generate_kat.py"
+	@make docker-build
+
diff --git a/README.md b/README.md
@@ -1,3 +1,7 @@
+<div align="center">
+    <img src="https://github.com/user-attachments/assets/bbe49f32-5e62-49a7-bb41-b28f1864833d" alt="estimators-logo" width=100 height=100></img>
+</div>
+
 # CryptographicEstimators
 
 [![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=Crypto-TII_CryptographicEstimators&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=Crypto-TII_CryptographicEstimators)
@@ -9,85 +13,105 @@
 
 ## Introduction 🎉
 
-This library provides bit security estimators and asymptotic complexity estimators for cryptographic problems. Some of the implemented estimators are:
+This library provides bit complexity estimators for cryptographic problems, as
+well as some cryptographic schemes. Currently, the implemented estimators are:
 
-- ### Problem Estimators  
+- ### Problem Estimators
   - Multivariate Quadratic
   - Binary Syndrome Decoding
   - Syndrome Decoding over Fq
   - Permuted Kernel
   - Permutation Equivalence
   - Linear Equivalence
-  - MinRank 
+  - MinRank
   - Regular Syndrome Decoding
+  - Rank Syndrome Decoding
 
 - ### Scheme Estimators
-  - UOV
+  - [BIKE](https://bikesuite.org)
+  - [MAYO](https://pqmayo.org)
+  - [UOV](https://www.uovsig.org)
 
-You can also access the estimators through [this](https://estimators.crypto.tii.ae/) user friendly and installation-free web application.
+## Getting Started 🚀
 
+This project is designed to be run through a terminal as a Python package. You
+can also access the estimators through [this](https://estimators.crypto.tii.ae/)
+user friendly and installation-free web application.
 
-## Getting Started 🚀
-This project is meant to be run through a terminal or inside a docker container.
+### Prerequisites ✔️
 
----
-## Pre-requisites ✔️
-### Local
-You would need to have Sage installed in your machine. For this follow the instructions described [here](https://www.sagemath.org/). 
-### Docker
-You would need to have Docker installed in your machine. For this follow the instructions described [here](https://www.docker.com/products/docker-desktop/).
+You need to have `python3`, `make` and `git` installed on your machine.
 
----
-## Installation 🛠
-### Local
-Once you've Sage installed you can go to this project folder and run `make install` in a terminal. This will install `cryptographic_estimators` library globally. If you encounter some permission error please try again adding `sudo` as a prefix.
+**Optional:** If you want to install the package in an isolated
+[Python virtual environment](https://docs.python.org/3/library/venv.html), run
+the next commands before the installation process:
 
-### Docker
-If you don’t have sage installed in your machine you can start with our dockerized app. First you will need to have running the DockerDesktop app, then open a new terminal, go to the project folder and run `make docker-build` or if you have Apple Silicon M1 Chip `make docker-build-m1`.
+```shell
+python3 -m venv .venv
+source .venv/bin/activate
+```
 
-> Note: This process may take up to 15 or 20 minutes depending on your bandwith and  computer capacity.
+### Installation 🛠
 
+- Clone and `cd` into the project directory.
+
+- Run `make install` to install the `cryptographic_estimators` library locally.
+
+  _Note:_ If you encounter some permission error, please try creating a virtual
+  environment with the steps mentioned in the
+  Prerequisites section in this document, so you don't need
+  to use `sudo` to interact with python/pip related commands.
+
+### Running the project ✈️
+
+Open the Python interpreter in a terminal and import the library as shown in the
+following example:
 
----
-## Running the project ✈️
-### Local
-Open the Sage interpreter in a terminal and try importing the library as the following example.
-```python
-sage: from cryptographic_estimators.SDEstimator import SDEstimator                                                                
-sage: sd = SDEstimator(15,10,5)                                                                                                   
-sage: sd.estimate() 
-```
-### Docker
-Open a terminal and execute `make docker-run` to start the container, then you can run `sage` as if it were in local
 ```python
-root@31d20617c222:/home/cryptographic_estimators# sage
-┌────────────────────────────────────────────────────────────────────┐
-│ SageMath version 9.0, Release Date: 2020-01-01                     │
-│ Using Python 3.8.10. Type "help()" for help.                       │
-└────────────────────────────────────────────────────────────────────┘
-sage: from cryptographic_estimators.SDEstimator import SDEstimator                                                                                                                 
-sage:  
+>>> from cryptographic_estimators.SDEstimator import SDEstimator
+>>> SD = SDEstimator(n=15, k=10, w=5)
+>>> SD.table()
 ```
 
----
 ## Documentation 📝
 
-You can either generate the documentation through docker via running `make docker-doc`
-open `docs/build/html/index.html` to view it, or you can find it online [here](https://crypto-tii.github.io/CryptographicEstimators/)
+- A user guide can be found [here](./docs/github/user_guide.md).
 
-Additionally, we provide a User Guide [here](https://github.com/Crypto-TII/CryptographicEstimators/blob/main/docs/User_Guide.ipynb).
+- Reference documentation for the library estimators can be found online
+  [here](https://crypto-tii.github.io/CryptographicEstimators/), or be generated
+  locally with the command `make doc` or `make docker-doc` (see at
+  `docs/build/html/index.html` after successful generation).
 
----
-## Contributing 🖊️
-The aim of this project is to be maintained by the community. We want you to help us grow this library, so please feel free to submit your pull request following the [CONTRIBUTING.md](./docs/CONTRIBUTING.md) document. 
-
----
-## Contact 🖊️
-If you need any help about contributing to this project feel free to contact us 
-at `cryptographic_estimators at tii.ae`
+## Contributing 🤝
+
+Thank you for considering contributing to our project. We thrive on community
+involvement and warmly welcome your contributions.
+
+### Where to begin 🌱
+
+1. **Explore Open Issues**: If you're looking for a place to start, check out
+   our [open issues](https://github.com/Crypto-TII/CryptographicEstimators/issues). There might be something that catches your
+   interest!
 
----
+2. **Read the Contribution Guide**: Before submitting a pull request, please
+   take a moment to review our
+   [Contribution Documentation](./docs/github/contributing.md). It contains
+   important information about our development guidelines and process.
 
-<!--### Usage -->
+3. **Ask for Help**: Stuck on something? Don't hesitate to reach out! You can:
 
+- Start a
+  [new discussion](https://github.com/Crypto-TII/CryptographicEstimators/discussions)
+- Open a
+  [new issue](https://github.com/Crypto-TII/CryptographicEstimators/issues)
+- [Contact us directly](https://github.com/Crypto-TII/CryptographicEstimators?tab=readme-ov-file#contact-%EF%B8%8F)
 
+Every contribution, big or small, is valued and appreciated. Whether you're
+fixing a typo, improving documentation, or adding a new feature, your efforts
+help make this library better for everyone. We look forward to collaborating
+with you!
+
+## Contact 🖊️
+
+If you need any help about contributing to this project feel free to contact us
+at `cryptographic_estimators at tii.ae`