From 69a57ef3bc0245bafe7deb8145ea6518213f2d95 Mon Sep 17 00:00:00 2001
From: Paul Schaub <vanitasvitae@fsfe.org>
Date: Thu, 22 Aug 2024 13:41:51 +0200
Subject: [PATCH] Deprecate addPassphrase()/addDecryptionPassphrase in favor of
 addMessagePassphrase()

---
 .../decryption_verification/ConsumerOptions.kt  | 17 ++++++++++++++++-
 .../encryption_signing/EncryptionOptions.kt     | 13 ++++++++++++-
 2 files changed, 28 insertions(+), 2 deletions(-)

diff --git a/pgpainless-core/src/main/kotlin/org/pgpainless/decryption_verification/ConsumerOptions.kt b/pgpainless-core/src/main/kotlin/org/pgpainless/decryption_verification/ConsumerOptions.kt
index 5007c8a5..39a4e8e4 100644
--- a/pgpainless-core/src/main/kotlin/org/pgpainless/decryption_verification/ConsumerOptions.kt
+++ b/pgpainless-core/src/main/kotlin/org/pgpainless/decryption_verification/ConsumerOptions.kt
@@ -196,7 +196,22 @@ class ConsumerOptions {
      * @param passphrase passphrase
      * @return options
      */
-    fun addDecryptionPassphrase(passphrase: Passphrase) = apply {
+    @Deprecated(
+        "Deprecated in favor of addMessagePassphrase",
+        ReplaceWith("addMessagePassphrase(passphrase)"))
+    fun addDecryptionPassphrase(passphrase: Passphrase) = addMessagePassphrase(passphrase)
+
+    /**
+     * Add a passphrase for message decryption. This passphrase will be used to try to decrypt
+     * messages which were symmetrically encrypted for a passphrase.
+     *
+     * See
+     * [Symmetrically Encrypted Data Packet](https://datatracker.ietf.org/doc/html/rfc4880#section-5.7)
+     *
+     * @param passphrase passphrase
+     * @return options
+     */
+    fun addMessagePassphrase(passphrase: Passphrase) = apply {
         decryptionPassphrases.add(passphrase)
     }
 
diff --git a/pgpainless-core/src/main/kotlin/org/pgpainless/encryption_signing/EncryptionOptions.kt b/pgpainless-core/src/main/kotlin/org/pgpainless/encryption_signing/EncryptionOptions.kt
index 3e232654..d26acc20 100644
--- a/pgpainless-core/src/main/kotlin/org/pgpainless/encryption_signing/EncryptionOptions.kt
+++ b/pgpainless-core/src/main/kotlin/org/pgpainless/encryption_signing/EncryptionOptions.kt
@@ -227,7 +227,18 @@ class EncryptionOptions(private val purpose: EncryptionPurpose) {
      * @param passphrase passphrase
      * @return this
      */
-    fun addPassphrase(passphrase: Passphrase) = apply {
+    @Deprecated(
+        "Deprecated in favor of addMessagePassphrase",
+        ReplaceWith("addMessagePassphrase(passphrase)"))
+    fun addPassphrase(passphrase: Passphrase) = addMessagePassphrase(passphrase)
+
+    /**
+     * Add a symmetric passphrase which the message will be encrypted to.
+     *
+     * @param passphrase passphrase
+     * @return this
+     */
+    fun addMessagePassphrase(passphrase: Passphrase) = apply {
         require(!passphrase.isEmpty) { "Passphrase MUST NOT be empty." }
         addEncryptionMethod(
             ImplementationFactory.getInstance().getPBEKeyEncryptionMethodGenerator(passphrase))