From e2d832f37fa48b0f5eb12c3f9d4b155c6b9846c8 Mon Sep 17 00:00:00 2001 From: Hubert Kario Date: Tue, 23 Jul 2024 20:07:51 +0200 Subject: [PATCH] use the same names for ML-KEM parameters as the FIPS 203 document --- README.md | 6 ++-- benchmarks/benchmark_ml_kem.py | 8 ++--- src/kyber_py/ml_kem/__init__.py | 2 +- src/kyber_py/ml_kem/default_parameters.py | 37 +++++++++++++++++++---- tests/test_ml_kem.py | 20 ++++++------ 5 files changed, 49 insertions(+), 24 deletions(-) diff --git a/README.md b/README.md index edb87b2..c0cbb64 100644 --- a/README.md +++ b/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. diff --git a/benchmarks/benchmark_ml_kem.py b/benchmarks/benchmark_ml_kem.py index 4cc1871..e509a7e 100644 --- a/benchmarks/benchmark_ml_kem.py +++ b/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) diff --git a/src/kyber_py/ml_kem/__init__.py b/src/kyber_py/ml_kem/__init__.py index cf16c96..2b62e3f 100644 --- a/src/kyber_py/ml_kem/__init__.py +++ b/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 diff --git a/src/kyber_py/ml_kem/default_parameters.py b/src/kyber_py/ml_kem/default_parameters.py index cdd0c59..79ca23a 100644 --- a/src/kyber_py/ml_kem/default_parameters.py +++ b/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. +""" diff --git a/tests/test_ml_kem.py b/tests/test_ml_kem.py index 517dcdc..6398616 100644 --- a/tests/test_ml_kem.py +++ b/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) ],