Merge pull request #87 from tomato42/stable-api

mark the ML-KEM API as stable

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

src/kyber_py/ml_kem/default_parameters.py

@@ -22,18 +22,24 @@
 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"])
 """
 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"])
 """
 Key exchange object that uses ML-KEM-1024 parameters internally.
 
 Provides about 256 bit level of security.
+
+Part of stable API.
 """

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: