Implement optional passphrase debugging

- Displaying passphrase debugging information only when the `BORG_DEBUG_PASSPHRASE` environment variable is set to "YES".
- If the env var is not set or set to a value other than "YES", debugging info will not be displayed.

src/borg/crypto/key.py

@@ -364,20 +364,23 @@ def detect(cls, repository, manifest_data):
         target = key.find_key()
         prompt = "Enter passphrase for key %s: " % target
         passphrase = Passphrase.env_passphrase()
+        debug_enabled = os.environ.get("BORG_DEBUG_PASSPHRASE") == "YES"
         if passphrase is None:
             passphrase = Passphrase()
             if not key.load(target, passphrase):
                 for retry in range(0, 3):
                     passphrase = Passphrase.getpass(prompt)
                     if key.load(target, passphrase):
                         break
-                    else:
+                    elif debug_enabled:
                         Passphrase.display_debug_info(passphrase)
                 else:
                     raise PasswordRetriesExceeded
         else:
             if not key.load(target, passphrase):
-                raise PassphraseWrong(passphrase)
+                if debug_enabled:
+                    Passphrase.display_debug_info(passphrase)
+                raise PassphraseWrong
         key.init_ciphers(manifest_data)
         key._passphrase = passphrase
         return key

src/borg/helpers/passphrase.py

@@ -31,10 +31,6 @@ class PassphraseWrong(Error):
 
     exit_mcode = 52
 
-    def __init__(self, passphrase):
-        super().__init__(self)
-        Passphrase.display_debug_info(passphrase)
-
 
 class PasswordRetriesExceeded(Error):
     """exceeded the maximum password retries"""
@@ -113,37 +109,28 @@ def verification(cls, passphrase):
             retry=True,
             env_var_override="BORG_DISPLAY_PASSPHRASE",
         ):
-            print('Your passphrase (between double-quotes): "%s"' % passphrase, file=sys.stderr)
-            print("Make sure the passphrase displayed above is exactly what you wanted.", file=sys.stderr)
-            print(
-                "Your passphrase (UTF-8 encoding in hex): %s" % bin_to_hex(passphrase.encode("utf-8")), file=sys.stderr
-            )
-            print(
-                "It is recommended to keep the UTF-8 encoding in hex together with the passphrase at a safe place. "
-                "In case you should ever run into passphrase issues, it could sometimes help debugging them.\n",
-                file=sys.stderr,
-            )
-            try:
-                passphrase.encode("ascii")
-            except UnicodeEncodeError:
-                print(
-                    "As you have a non-ASCII passphrase, it is recommended to keep the "
-                    "UTF-8 encoding in hex together with the passphrase at a safe place.",
-                    file=sys.stderr,
-                )
+            pw_msg = f"""
+            Your passphrase (between double-quotes): "{passphrase}"
+            Make sure the passphrase displayed above is exactly what you wanted.
+            Your passphrase (UTF-8 encoding in hex): {bin_to_hex(passphrase.encode("utf-8"))}
+            It is recommended to keep the UTF-8 encoding in hex together with the passphrase at a safe place.
+            In case you should ever run into passphrase issues, it could sometimes help debugging them.
+            """
+            print(pw_msg, file=sys.stderr)
 
     @staticmethod
     def display_debug_info(passphrase):
-        print("Incorrect passphrase!", file=sys.stderr)
-        print(f'Passphrase used (between double-quotes): "{passphrase}"', file=sys.stderr)
-        print(f'Same, UTF-8 encoded, in hex: {bin_to_hex(passphrase.encode("utf-8"))}', file=sys.stderr)
-        print("Relevant Environment Variables:", file=sys.stderr)
-        for env_var in ["BORG_PASSPHRASE", "BORG_PASSCOMMAND", "BORG_PASSPHRASE_FD"]:
-            env_var_value = os.environ.get(env_var)
-            if env_var_value is not None:
-                print(f'{env_var} = "{env_var_value}"', file=sys.stderr)
-            else:
-                print(f"# {env_var} is not set", file=sys.stderr)
+        if os.environ.get("BORG_DEBUG_PASSPHRASE") == "YES":
+            print("Incorrect passphrase!", file=sys.stderr)
+            print(f'Passphrase used (between double-quotes): "{passphrase}"', file=sys.stderr)
+            print(f'Same, UTF-8 encoded, in hex: {bin_to_hex(passphrase.encode("utf-8"))}', file=sys.stderr)
+            print("Relevant Environment Variables:", file=sys.stderr)
+            for env_var in ["BORG_PASSPHRASE", "BORG_PASSCOMMAND", "BORG_PASSPHRASE_FD"]:
+                env_var_value = os.environ.get(env_var)
+                if env_var_value is not None:
+                    print(f'{env_var} = "{env_var_value}"', file=sys.stderr)
+                else:
+                    print(f"# {env_var} is not set", file=sys.stderr)
 
     @classmethod
     def new(cls, allow_empty=False):

src/borg/testsuite/helpers_test.py

@@ -1408,12 +1408,14 @@ def test_passphrase_new_retries(self, monkeypatch):
     def test_passphrase_repr(self):
         assert "secret" not in repr(Passphrase("secret"))
 
-    def test_passphrase_wrong(self, capsys, monkeypatch):
+    def test_passphrase_wrong_debug_enabled(self, capsys, monkeypatch):
+        monkeypatch.setenv("BORG_DEBUG_PASSPHRASE", "YES")
         monkeypatch.setenv("BORG_PASSPHRASE", "wrong_passphrase")
         monkeypatch.setenv("BORG_PASSCOMMAND", "echo wrong_passphrase")
         monkeypatch.setenv("BORG_PASSPHRASE_FD", "123")
 
         with pytest.raises(PassphraseWrong) as exc_info:
+            Passphrase.display_debug_info("wrong_passphrase")
             raise PassphraseWrong("wrong_passphrase")
 
         out, err = capsys.readouterr()
@@ -1428,6 +1430,17 @@ def test_passphrase_wrong(self, capsys, monkeypatch):
             "passphrase supplied in BORG_PASSPHRASE, by BORG_PASSCOMMAND or via BORG_PASSPHRASE_FD is incorrect."
         )
 
+    def test_passphrase_wrong_debug_disabled(self, capsys, monkeypatch):
+        monkeypatch.delenv("BORG_DEBUG_PASSPHRASE", raising=False)
+
+        with pytest.raises(PassphraseWrong):
+            Passphrase.display_debug_info("wrong_passphrase")
+            raise PassphraseWrong("wrong_passphrase")
+
+        out, err = capsys.readouterr()
+        assert "Incorrect passphrase!" not in err
+        assert 'Passphrase used (between double-quotes): "wrong_passphrase"' not in err
+
     def test_verification(self, capsys, monkeypatch):
         passphrase = "test_passphrase"
 
@@ -1451,6 +1464,7 @@ def test_verification(self, capsys, monkeypatch):
 
     def test_display_debug_info(self, capsys, monkeypatch):
         passphrase = "debug_test"
+        monkeypatch.setenv("BORG_DEBUG_PASSPHRASE", "YES")
         monkeypatch.setenv("BORG_PASSPHRASE", "debug_env_passphrase")
         monkeypatch.setenv("BORG_PASSCOMMAND", "command")
         monkeypatch.setenv("BORG_PASSPHRASE_FD", "fd_value")
@@ -1461,9 +1475,17 @@ def test_display_debug_info(self, capsys, monkeypatch):
         assert "Incorrect passphrase!" in err
         assert 'Passphrase used (between double-quotes): "debug_test"' in err
         assert "64656275675f74657374" in err  # UTF-8 hex encoding of 'debug_test'
-        assert "BORG_PASSPHRASE" in err
-        assert "BORG_PASSCOMMAND" in err
-        assert "BORG_PASSPHRASE_FD" in err
+        assert 'BORG_PASSPHRASE = "debug_env_passphrase"' in err
+        assert 'BORG_PASSCOMMAND = "command"' in err
+        assert 'BORG_PASSPHRASE_FD = "fd_value"' in err
+
+        monkeypatch.delenv("BORG_DEBUG_PASSPHRASE", raising=False)
+
+        Passphrase.display_debug_info(passphrase)
+        out, err = capsys.readouterr()
+
+        assert "Incorrect passphrase!" not in err
+        assert 'Passphrase used (between double-quotes): "debug_test"' not in err
 
 
 @pytest.mark.parametrize(