Merge pull request #64 from tomato42/standard-names-for-mlkem

use the same names for ML-KEM parameters as the FIPS 203 document

README.md

@@ -101,9 +101,9 @@ The above example would also work with `ML_KEM192` and `ML_KEM256`.
 
 |  Params    |  keygen  |  keygen/s  |  encap  |  encap/s  |  decap  |  decap/s |
 |------------|---------:|-----------:|--------:|----------:|--------:|---------:|
-|ML_KEM128    |    3.87ms|      258.47|   6.59ms|     151.79|  10.97ms|    91.15 |
-|ML_KEM192    |    5.85ms|      170.84|   9.67ms|     103.43|  15.83ms|    63.15 |
-|ML_KEM256   |    8.52ms|       117.38|  13.31ms|      75.12|  21.58ms|    46.34 |
+|ML-KEM-512  |    3.87ms|      258.47|   6.59ms|     151.79|  10.97ms|    91.15 |
+|ML-KEM-768  |    5.85ms|      170.84|   9.67ms|     103.43|  15.83ms|    63.15 |
+|ML-KEM-1024 |    8.52ms|       117.38|  13.31ms|      75.12|  21.58ms|    46.34 |
 
 All times recorded using a Intel Core i7-9750H CPU and averaged over 1000 runs.
 

benchmarks/benchmark_ml_kem.py

@@ -1,4 +1,4 @@
-from kyber_py.ml_kem import ML_KEM128, ML_KEM192, ML_KEM256
+from kyber_py.ml_kem import ML_KEM_512, ML_KEM_768, ML_KEM_1024
 import cProfile
 from time import time
 
@@ -68,6 +68,6 @@ def benchmark_ml_kem(ML_KEM, name, count):
         "|  decap  |  decap/s"
     )
     print("-" * 80)
-    benchmark_ml_kem(ML_KEM128, "ML_KEM128", count)
-    benchmark_ml_kem(ML_KEM192, "ML_KEM192", count)
-    benchmark_ml_kem(ML_KEM256, "ML_KEM256", count)
+    benchmark_ml_kem(ML_KEM_512, "ML-KEM-512", count)
+    benchmark_ml_kem(ML_KEM_768, "ML-KEM-768", count)
+    benchmark_ml_kem(ML_KEM_1024, "ML-KEM-1024", count)

src/kyber_py/ml_kem/__init__.py

@@ -1 +1 @@
-from .default_parameters import ML_KEM128, ML_KEM192, ML_KEM256
+from .default_parameters import ML_KEM_512, ML_KEM_768, ML_KEM_1024

src/kyber_py/ml_kem/default_parameters.py

@@ -1,14 +1,39 @@
+"""
+The parameters defined in the FIPS 203 IPD document.
+
+Includes the ML-KEM-512, ML-KEM-768, and ML-KEM-1024 parameters
+and initialised objects with them.
+"""
+
 from .ml_kem import ML_KEM
 
 # TODO: we can only allow a user to select one of the following three
 # we should maybe put these into the class and only allow a user to
 # select 128, 192 or 256 bit security.
 DEFAULT_PARAMETERS = {
-    "ML128": {"k": 2, "eta_1": 3, "eta_2": 2, "du": 10, "dv": 4},
-    "ML192": {"k": 3, "eta_1": 2, "eta_2": 2, "du": 10, "dv": 4},
-    "ML256": {"k": 4, "eta_1": 2, "eta_2": 2, "du": 11, "dv": 5},
+    "ML512": {"k": 2, "eta_1": 3, "eta_2": 2, "du": 10, "dv": 4},
+    "ML768": {"k": 3, "eta_1": 2, "eta_2": 2, "du": 10, "dv": 4},
+    "ML1024": {"k": 4, "eta_1": 2, "eta_2": 2, "du": 11, "dv": 5},
 }
+"""Parameters for the :py:obj:`.ML_KEM` objects."""
+
+ML_KEM_512 = ML_KEM(DEFAULT_PARAMETERS["ML512"])
+"""
+Key exchange object that uses ML-KEM-512 parameters internally.
+
+Provides about 128 bit level of security.
+"""
+
+ML_KEM_768 = ML_KEM(DEFAULT_PARAMETERS["ML768"])
+"""
+Key exchange object that uses ML-KEM-768 parameters internally.
+
+Provides about 192 bit level of security.
+"""
+
+ML_KEM_1024 = ML_KEM(DEFAULT_PARAMETERS["ML1024"])
+"""
+Key exchange object that uses ML-KEM-1024 parameters internally.
 
-ML_KEM128 = ML_KEM(DEFAULT_PARAMETERS["ML128"])
-ML_KEM192 = ML_KEM(DEFAULT_PARAMETERS["ML192"])
-ML_KEM256 = ML_KEM(DEFAULT_PARAMETERS["ML256"])
+Provides about 256 bit level of security.
+"""

tests/test_ml_kem.py

@@ -1,7 +1,7 @@
 import unittest
 from itertools import islice
 import pytest
-from kyber_py.ml_kem import ML_KEM128, ML_KEM192, ML_KEM256
+from kyber_py.ml_kem import ML_KEM_512, ML_KEM_768, ML_KEM_1024
 from kyber_py.drbg.aes256_ctr_drbg import AES256_CTR_DRBG
 
 
@@ -50,14 +50,14 @@ def generic_test_ML_KEM(self, ML_KEM, count):
                 K_prime = ML_KEM.decaps(c, dk)
                 self.assertEqual(K, K_prime)
 
-    def test_ML_KEM128(self):
-        self.generic_test_ML_KEM(ML_KEM128, 5)
+    def test_ML_KEM_512(self):
+        self.generic_test_ML_KEM(ML_KEM_512, 5)
 
-    def test_ML_KEM192(self):
-        self.generic_test_ML_KEM(ML_KEM192, 5)
+    def test_ML_KEM_768(self):
+        self.generic_test_ML_KEM(ML_KEM_768, 5)
 
-    def test_ML_KEM256(self):
-        self.generic_test_ML_KEM(ML_KEM256, 5)
+    def test_ML_KEM_1024(self):
+        self.generic_test_ML_KEM(ML_KEM_1024, 5)
 
 
 # As there are 1000 KATs in the file, execution of all of them takes
@@ -88,9 +88,9 @@ def data_parse(filename):
     [
         (kem, seed, param)
         for kem, filename in [
-            (ML_KEM128, "assets/kat_MLKEM_512.rsp"),
-            (ML_KEM192, "assets/kat_MLKEM_768.rsp"),
-            (ML_KEM256, "assets/kat_MLKEM_1024.rsp"),
+            (ML_KEM_512, "assets/kat_MLKEM_512.rsp"),
+            (ML_KEM_768, "assets/kat_MLKEM_768.rsp"),
+            (ML_KEM_1024, "assets/kat_MLKEM_1024.rsp"),
         ]
         for seed, param in data_parse(filename)
     ],