Deprecate the KyberAgreement class to streamline encapsulation and de…

…capsulation
ronhombre · Aug 30, 2024 · 8187ba1 · 8187ba1
1 parent 61167b7
commit 8187ba1
Show file tree

Hide file tree

Showing 3 changed files with 34 additions and 0 deletions.
diff --git a/src/commonMain/kotlin/asia/hombre/kyber/KyberAgreement.kt b/src/commonMain/kotlin/asia/hombre/kyber/KyberAgreement.kt
@@ -39,6 +39,7 @@ import kotlin.jvm.JvmSynthetic
  */
 @OptIn(ExperimentalJsExport::class)
 @JsExport
+@Deprecated("This class is redundant. It will be removed in 1.0.0 release.")
 class KyberAgreement(private val decapsulationKey: KyberDecapsulationKey) {
     /**
      * The [KyberParameter] of this agreement.
@@ -267,6 +268,10 @@ class KyberAgreement(private val decapsulationKey: KyberDecapsulationKey) {
          */
         @JvmStatic
         @JsName("encapsulate")
+        @Deprecated("KyberAgreement is a redundant class.",
+            ReplaceWith("kyberEncapsulationKey.encapsulate()",
+                "asia.hombre.kyber.KyberEncapsulationKey.encapsulate"),
+            DeprecationLevel.WARNING)
         fun encapsulate(kyberEncapsulationKey: KyberEncapsulationKey): KyberEncapsulationResult {
             return encapsulate(kyberEncapsulationKey, SecureRandom().nextBytesOf(KyberConstants.N_BYTES))
         }
@@ -281,6 +286,11 @@ class KyberAgreement(private val decapsulationKey: KyberDecapsulationKey) {
      * @return [ByteArray] - The generated Secret Key, which is the same one generated by the sender.
      */
     @JsName("decapsulate")
+    @Deprecated("KyberAgreement is a redundant class.",
+        ReplaceWith("kyberCipherText.decapsulate(kyberDecapsulationKey)",
+            "asia.hombre.kyber.KyberCipherText.decapsulate",
+            "asia.hombre.kyber.KyberDecapsulationKey"),
+        DeprecationLevel.WARNING)
     fun decapsulate(kyberCipherText: KyberCipherText): ByteArray {
         return Companion.decapsulate(secureDecapsulationKey, kyberCipherText)
     }

diff --git a/src/commonMain/kotlin/asia/hombre/kyber/KyberCipherText.kt b/src/commonMain/kotlin/asia/hombre/kyber/KyberCipherText.kt
@@ -160,6 +160,18 @@ class KyberCipherText internal constructor( //TODO: Copy parameter variables
         return KyberCipherText(this.parameter, encodedCoefficients.copyOf(), encodedTerms.copyOf())
     }
 
+    /**
+     * Decapsulates this [KyberCipherText] and recovers the Secret Key.
+     *
+     * This method is the ML-KEM.Decaps() specified in NIST FIPS 203.
+     *
+     * @param decapsulationKey your [KyberDecapsulationKey].
+     * @return [ByteArray] - The generated Secret Key, which is the same one generated by the sender.
+     */
+    fun decapsulate(decapsulationKey: KyberDecapsulationKey): ByteArray {
+        return KyberAgreement.decapsulate(decapsulationKey, this)
+    }
+
     /**
      * Convert [KyberCipherText] into a String.
      *

diff --git a/src/commonMain/kotlin/asia/hombre/kyber/KyberEncapsulationKey.kt b/src/commonMain/kotlin/asia/hombre/kyber/KyberEncapsulationKey.kt
@@ -20,6 +20,7 @@ package asia.hombre.kyber
 
 import asia.hombre.kyber.exceptions.UnsupportedKyberVariantException
 import asia.hombre.kyber.interfaces.KyberKEMKey
+import org.kotlincrypto.SecureRandom
 import kotlin.io.encoding.Base64
 import kotlin.io.encoding.ExperimentalEncodingApi
 import kotlin.js.ExperimentalJsExport
@@ -137,6 +138,17 @@ class KyberEncapsulationKey internal constructor(
         return KyberEncapsulationKey(key.copy())
     }
 
+    /**
+     * Encapsulates this [KyberEncapsulationKey] into a [KyberCipherText] and generates a Secret Key.
+     *
+     * This method is the ML-KEM.Encaps() specified in NIST FIPS 203.
+     *
+     * @return [KyberEncapsulationResult] - Contains the Cipher Text and the generated Secret Key.
+     */
+    fun encapsulate(): KyberEncapsulationResult {
+        return KyberAgreement.encapsulate(this, SecureRandom().nextBytesOf(KyberConstants.N_BYTES))
+    }
+
     /**
      * Convert [KyberEncapsulationKey] into a String.
      *