From 6504ce42dafed3e22e1f602770761fdbdb441c4c Mon Sep 17 00:00:00 2001
From: Alicja Kario <hkario@redhat.com>
Date: Tue, 8 Oct 2024 20:01:33 +0200
Subject: [PATCH] mark the ML-KEM API as stable

---
 README.md                                 |  3 +++
 src/kyber_py/ml_kem/default_parameters.py |  6 ++++++
 src/kyber_py/ml_kem/ml_kem.py             | 10 ++++++++--
 3 files changed, 17 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 0d43e01..aabbebe 100644
--- a/README.md
+++ b/README.md
@@ -89,6 +89,9 @@ use:
 - `ML_KEM.encaps(ek)`: generate a key and ciphertext pair `(key, ct)`
 - `ML_KEM.decaps(dk, ct)`: generate the shared key `key`
 
+Those, together with the `ML_KEM_512`, `ML_KEM_768`, and `ML_KEM_1024`
+objects comprise the kyber-py library stable API.
+
 #### Example
 
 ```python
diff --git a/src/kyber_py/ml_kem/default_parameters.py b/src/kyber_py/ml_kem/default_parameters.py
index 3ae7304..7db9636 100644
--- a/src/kyber_py/ml_kem/default_parameters.py
+++ b/src/kyber_py/ml_kem/default_parameters.py
@@ -22,6 +22,8 @@
 Key exchange object that uses ML-KEM-512 parameters internally.
 
 Provides about 128 bit level of security.
+
+Part of stable API.
 """
 
 ML_KEM_768 = ML_KEM(DEFAULT_PARAMETERS["ML768"])
@@ -29,6 +31,8 @@
 Key exchange object that uses ML-KEM-768 parameters internally.
 
 Provides about 192 bit level of security.
+
+Part of stable API.
 """
 
 ML_KEM_1024 = ML_KEM(DEFAULT_PARAMETERS["ML1024"])
@@ -36,4 +40,6 @@
 Key exchange object that uses ML-KEM-1024 parameters internally.
 
 Provides about 256 bit level of security.
+
+Part of stable API.
 """
diff --git a/src/kyber_py/ml_kem/ml_kem.py b/src/kyber_py/ml_kem/ml_kem.py
index 8cfbe25..3154a68 100644
--- a/src/kyber_py/ml_kem/ml_kem.py
+++ b/src/kyber_py/ml_kem/ml_kem.py
@@ -279,6 +279,8 @@ def keygen(self):
         ``ek`` is encoded as bytes of length 384*k + 32
         ``dk`` is encoded as bytes of length 768*k + 96
 
+        Part of stable API.
+
         :return: Tuple with encapsulation key and decapsulation key.
         :rtype: tuple(bytes, bytes)
         """
@@ -324,8 +326,10 @@ def encaps(self, ek):
         ``K`` is the shared secret key of length 32 bytes
         ``c`` is the ciphertext of length 32(du*k + dv)
 
+        Part of stable API.
+
         :param bytes ek: byte-encoded encapsulation key
-        :return: a random key and an encapsulation of it
+        :return: a random key (``K``) and an encapsulation of it (``c``)
         :rtype: tuple(bytes, bytes)
         """
         # Create random tokens
@@ -395,9 +399,11 @@ def decaps(self, dk, c):
 
         ``K`` is the shared secret key of length 32 bytes
 
+        Part of stable API.
+
         :param bytes dk: decapsulation key
         :param bytes c: ciphertext with an encapsulated key
-        :return: shared secret key
+        :return: shared secret key (``K``)
         :rtype: bytes
         """
         try: