From 57231b72d2a5687a1585b8b3407a7441afeb299a Mon Sep 17 00:00:00 2001
From: iequidoo <dgreshilov@gmail.com>
Date: Sat, 22 Nov 2025 14:51:36 -0300
Subject: [PATCH] docs: Mark db encryption support as deprecated (#7403)

- Db encryption does nothing with blobs, so fs/disk encryption is recommended.
- Isolation from other apps is needed anyway.
- Experimental database encryption was removed on iOS and Android.
- Delta Touch is using CFFI API with a manually entered password because Ubuntu Touch does not offer
  filesystem or disk encryption, but we don't want new users of these APIs, such as bot developers.
---
 deltachat-ffi/deltachat.h | 13 ++++++++++---
 src/context.rs            | 30 ++++++++++--------------------
 2 files changed, 20 insertions(+), 23 deletions(-)

diff --git a/deltachat-ffi/deltachat.h b/deltachat-ffi/deltachat.h
index 539ae76fe7..9cec301586 100644
--- a/deltachat-ffi/deltachat.h
+++ b/deltachat-ffi/deltachat.h
@@ -247,7 +247,7 @@ typedef struct _dc_event_emitter dc_accounts_event_emitter_t;
 // create/open/config/information
 
 /**
- * Create a new context object and try to open it without passphrase. If
+ * Create a new context object and try to open it. If
  * database is encrypted, the result is the same as using
  * dc_context_new_closed() and the database should be opened with
  * dc_context_open() before using.
@@ -283,8 +283,13 @@ dc_context_t*   dc_context_new_closed        (const char* dbfile);
 
 
 /**
- * Opens the database with the given passphrase. This can only be used on
- * closed context, such as created by dc_context_new_closed(). If the database
+ * Opens the database with the given passphrase.
+ * NB: Nonempty passphrase (db encryption) is deprecated 2025-11:
+ * - Db encryption does nothing with blobs, so fs/disk encryption is recommended.
+ * - Isolation from other apps is needed anyway.
+ *
+ * This can only be used on closed context, such as
+ * created by dc_context_new_closed(). If the database
  * is new, this operation sets the database passphrase. For existing databases
  * the passphrase should be the one used to encrypt the database the first
  * time.
@@ -301,6 +306,8 @@ int             dc_context_open              (dc_context_t *context, const char*
 
 /**
  * Changes the passphrase on the open database.
+ * Deprecated 2025-11, see `dc_context_open()` for reasoning.
+ *
  * Existing database must already be encrypted and the passphrase cannot be NULL or empty.
  * It is impossible to encrypt unencrypted database with this method and vice versa.
  *
diff --git a/src/context.rs b/src/context.rs
index 7ccaf64a43..cfff416326 100644
--- a/src/context.rs
+++ b/src/context.rs
@@ -46,7 +46,7 @@ use crate::{chatlist_events, stats};
 ///
 /// # Examples
 ///
-/// Creating a new unencrypted database:
+/// Creating a new database:
 ///
 /// ```
 /// # let rt = tokio::runtime::Runtime::new().unwrap();
@@ -61,24 +61,6 @@ use crate::{chatlist_events, stats};
 /// drop(context);
 /// # });
 /// ```
-///
-/// To use an encrypted database provide a password.  If the database does not yet exist it
-/// will be created:
-///
-/// ```
-/// # let rt = tokio::runtime::Runtime::new().unwrap();
-/// # rt.block_on(async move {
-/// use deltachat::context::ContextBuilder;
-///
-/// let dir = tempfile::tempdir().unwrap();
-/// let context = ContextBuilder::new(dir.path().join("db"))
-///      .with_password("secret".into())
-///      .open()
-///      .await
-///      .unwrap();
-/// drop(context);
-/// # });
-/// ```
 #[derive(Clone, Debug)]
 pub struct ContextBuilder {
     dbfile: PathBuf,
@@ -150,9 +132,13 @@ impl ContextBuilder {
     }
 
     /// Sets the password to unlock the database.
+    /// Deprecated 2025-11:
+    /// - Db encryption does nothing with blobs, so fs/disk encryption is recommended.
+    /// - Isolation from other apps is needed anyway.
     ///
     /// If an encrypted database is used it must be opened with a password.  Setting a
     /// password on a new database will enable encryption.
+    #[deprecated(since = "TBD")]
     pub fn with_password(mut self, password: String) -> Self {
         self.password = Some(password);
         self
@@ -180,7 +166,7 @@ impl ContextBuilder {
 
     /// Builds the [`Context`] and opens it.
     ///
-    /// Returns error if context cannot be opened with the given passphrase.
+    /// Returns error if context cannot be opened.
     pub async fn open(self) -> Result<Context> {
         let password = self.password.clone().unwrap_or_default();
         let context = self.build().await?;
@@ -400,9 +386,12 @@ impl Context {
     }
 
     /// Opens the database with the given passphrase.
+    /// NB: Db encryption is deprecated, so `passphrase` should be empty normally. See
+    /// [`ContextBuilder::with_password()`] for reasoning.
     ///
     /// Returns true if passphrase is correct, false is passphrase is not correct. Fails on other
     /// errors.
+    #[deprecated(since = "TBD")]
     pub async fn open(&self, passphrase: String) -> Result<bool> {
         if self.sql.check_passphrase(passphrase.clone()).await? {
             self.sql.open(self, passphrase).await?;
@@ -413,6 +402,7 @@ impl Context {
     }
 
     /// Changes encrypted database passphrase.
+    /// Deprecated 2025-11, see [`ContextBuilder::with_password()`] for reasoning.
     pub async fn change_passphrase(&self, passphrase: String) -> Result<()> {
         self.sql.change_passphrase(passphrase).await?;
         Ok(())