Merge pull request #120 from GuilhemN/main

Comment difference rough vs estimate

README.rst

@@ -14,7 +14,21 @@ The main purpose of this estimator is to give designers an easy way to choose pa
 Quick Start
 -----------
 
-- Usage
+We currently provide evaluators for the security of the `LWE`, `NTRU`, and `SIS` problems. 
+Our estimator integrates simulators for the best known attacks against these problems, and provides
+bit-security estimates relying on heuristics to predict the cost and shape of lattice reduction algorithms. The default
+models are configured in `conf.py <https://github.com/malb/lattice-estimator/blob/main/estimator/conf.py>`.
+
+It is possible to evaluate attacks cost individually, or using the helper functions:
+- `*.estimator.rough`: fast routine that evaluates the security of the problem only against the usually most efficient
+   attacks. Note that it uses a non-default cost model for lattice reduction, most often used in the literature for ease of 
+   comparison, and will thus return different numbers than the rest of the API. Refer to 
+   `its documentation <https://lattice-estimator.readthedocs.io/en/latest/_apidoc/estimator.lwe/estimator.lwe.Estimate/estimator.lwe.Estimate.rough.html>` 
+   for details.
+- `*.estimator`: extended routine that evaluates the security of the problem against all supported attacks. This uses the
+   default cost and shape model for lattice reduction.
+
+Usage examples:
 
   .. code-block:: python
     

docs/algorithms/lwe-dual.rst

@@ -22,6 +22,6 @@ Further improvements are possible using a meet-in-the-middle approach [EPRINT:CH
 
    dual_hybrid(params, mitm_optimization=True)
 
-We consider the variant fron [MATZOV22]_::
+We consider the variant from [MATZOV22]_::
 
    matzov(params)

docs/algorithms/sis-lattice.rst

@@ -32,5 +32,5 @@ Another option is to simulate a rerandomization of the basis, such that the q-ve
 
     SIS.lattice(params.updated(length_bound=70), red_shape_model=Simulator.LGSA)
 
-**Note:** Currently, lattice attack estimation is only avalailable for euclidean (``2``) and infinity (``oo``) norms. ``SIS.lattice()`` will return a ``NotImplementedError`` if one of these two norms are not selected.
+**Note:** Currently, lattice attack estimation is only available for euclidean (``2``) and infinity (``oo``) norms. ``SIS.lattice()`` will return a ``NotImplementedError`` if one of these two norms are not selected.
 

estimator/conf.py

@@ -7,10 +7,15 @@
 from .reduction import RC
 from sage.all import exp
 
+"""
+Default models used to evaluate the cost and shape of lattice reduction.
+This influences the concrete estimated cost of attacks.
+"""
 red_cost_model = RC.MATZOV
 red_cost_model_classical_poly_space = RC.ABLR21
 red_shape_model = "gsa"
 red_simulator = GSA
+
 mitm_opt = "analytical"
 max_n_cache = 10000
 

estimator/lwe.py

@@ -25,11 +25,15 @@ class Estimate:
 
     def rough(self, params, jobs=1, catch_exceptions=True):
         """
-        This function makes the following somewhat routine assumptions:
+        This function makes the following (non-default) somewhat routine assumptions to evaluate the cost of lattice
+        reduction, and to provide comparable numbers with most of the literature:
 
         - The GSA holds.
         - The Core-SVP model holds.
 
+        Provided numbers are notably not directly comparable with the rest of our API, when using the default cost
+        models.
+
         This function furthermore assumes the following heuristics:
 
         - The primal hybrid attack only applies to sparse secrets.
@@ -93,7 +97,7 @@ def __call__(
         catch_exceptions=True,
     ):
         """
-        Run all estimates.
+        Run all estimates, based on the default cost and shape models for lattice reduction.
 
         :param params: LWE parameters.
         :param red_cost_model: How to cost lattice reduction.

estimator/ntru.py

@@ -22,11 +22,15 @@ class Estimate:
 
     def rough(self, params, jobs=1, catch_exceptions=True):
         """
-        This function makes the following somewhat routine assumptions:
+        This function makes the following (non-default) somewhat routine assumptions to evaluate the cost of lattice
+        reduction, and to provide comparable numbers with most of the literature:
 
         - The ZGSA holds.
         - The Core-SVP model holds.
 
+        Provided numbers are notably not directly comparable with the rest of our API, when using the default cost
+        models.
+
         This function furthermore assumes the following heuristics:
 
         - The primal hybrid attack only applies to sparse secrets.
@@ -91,7 +95,7 @@ def __call__(
         catch_exceptions=True,
     ):
         """
-        Run all estimates.
+        Run all estimates, based on the default cost and shape models for lattice reduction.
 
         :param params: NTRU parameters.
         :param red_cost_model: How to cost lattice reduction.

estimator/sis.py

@@ -19,11 +19,15 @@
 class Estimate:
     def rough(self, params, jobs=1, catch_exceptions=True):
         """
-        This function makes the following somewhat routine assumptions:
+        This function makes the following (non-default) somewhat routine assumptions to evaluate the cost of lattice
+        reduction, and to provide comparable numbers with most of the literature:
 
         - The LGSA holds.
         - The Core-SVP model holds.
 
+        Provided numbers are notably not directly comparable with the rest of our API, when using the default cost
+        models.
+
         This function furthermore assumes the following heuristics:
         - None at the moment. May change as more algorithms are added.
 
@@ -74,7 +78,7 @@ def __call__(
         catch_exceptions=True,
     ):
         """
-        Run all estimates.
+        Run all estimates, based on the default cost and shape models for lattice reduction.
 
         :param params: SIS parameters.
         :param red_cost_model: How to cost lattice reduction.