@@ -5,81 +5,56 @@ description: Use drift on encrypted databases
55
66---
77
8-
9-
108There are two ways to use drift on encrypted databases.
119The ` encrypted_drift ` package is similar to ` drift_sqflite ` and uses a platform plugin written in
1210Java.
13- Alternatively, you can use the ffi-based implementation with the ` sqlcipher_flutter_libs ` package .
11+ Alternatively, you can use the ffi-based implementation with regular ` package:drift/native.dart ` APIs .
1412
15- For new apps, we recommend using ` sqlcipher_flutter_libs ` with a ` NativeDatabase `
16- from drift.
13+ For new apps, we recommend using a ` NativeDatabase ` with encrypted databases.
1714An example of a Flutter app using the new encryption package is available
1815[ here] ( https://github.com/simolus3/drift/tree/develop/examples/encryption ) .
1916
2017## Encrypted version of a ` NativeDatabase `
2118
22- You can also use the new ` drift/native ` library with an encrypted executor.
23- This allows you to use an encrypted drift database on more platforms, which is particularly
24- interesting for Desktop applications.
19+ You can use the ` drift/native ` library with an encrypted executor.
20+ This allows you to use an encrypted drift database on all native platforms, including Desktop.
2521
2622### Setup
2723
28- To use ` sqlcipher ` , add a dependency on ` sqlcipher_flutter_libs ` :
24+ The ` sqlite3 ` package uses build hooks to bundle a version of SQLite with your app.
25+ It can be configured to bundle [ SQLite3MultipleCiphers] ( https://utelle.github.io/SQLite3MultipleCiphers/ )
26+ instead, which provides encryption support.
27+ To enable encryption, add this to the pubspec of your pub workspace root (or your app's pubspec if you're
28+ not using pub workspaces):
2929
3030``` yaml
31- dependencies :
32- sqlcipher_flutter_libs : ^0.6.0
31+ hooks :
32+ user_defines :
33+ sqlite3 :
34+ source : sqlite3mc
3335` ` `
3436
35- If you already have a dependency on ` sqlite3_flutter_libs`, __drop that dependency__.
36- ` sqlite3_flutter_libs` and `sqlcipher_flutter_libs` are not compatible
37- as they both provide a (different) set of `sqlite3` native apis.
38-
39- On Android, you also need to adapt the opening behavior of the `sqlite3` package to use the encrypted library instead
40- of the regular `libsqlite3.so` :
37+ For more information on configuring hooks, see [the documentation](https://pub.dev/documentation/sqlite3/latest/topics/hook-topic.html).
4138
42- <Snippet href="/lib/src/snippets/platforms/encryption.dart" name="setup" />
43-
44- When using drift on a background database, you need to call `setupSqlCipher` on the background isolate
45- as well. With `NativeDatabase.createInBackground`, which are using isolates internally, you can use
46- the `setupIsolate` callback to do this - the examples on this page use this as well.
47- Since `applyWorkaroundToOpenSqlCipherOnOldAndroidVersions()` invokes a platform channel, one needs
48- to install a `BackgroundIsolateBinaryMessenger` on the isolate as well.
49-
50- On iOS, macOS and Windows, no additional setup is necessary - simply depend on `sqlcipher_flutter_libs`.
51- For Linux builds, note that OpenSSL is linked statically by default. If you want to compile your app to use
52- a dynamically-linked distribution of OpenSSL, see [this](https://github.com/simolus3/sqlite3.dart/issues/186#issuecomment-1742110933)
53- issue comment.
39+ Previous versions of the ` sqlite3` package required a dependency on `sqlcipher_flutter_libs`. That package is no longer necessary
40+ after upgrading to drift 2.32.0 and can be removed.
5441
5542# ## Using
5643
57- SQLCipher implements sqlite3's C api , which means that you can continue to use the `sqlite3` package
58- or `drift/ffi ` without changes. They're both fully compatible with `sqlcipher_flutter_libs` .
44+ SQLite3MultipleCiphers implements the SQLite C API , which means that you can continue to use the `sqlite3` package
45+ or `package: drift/native.dart ` without code changes .
5946
60- To actually encrypt a database, you must set an encryption key before using it.
47+ To actually encrypt a database though , you must set an encryption key before using it.
6148A good place to do that in drift is the `setup` parameter of `NativeDatabase`, which runs before drift
6249is using the database in any way :
6350
6451<Snippet href="/lib/src/snippets/platforms/encryption.dart" name="encrypted1" />
6552
66- ??? note "Disabling double-quoted string literals"
67-
68- In `sqlite3_flutter_libs`, sqlite3 is compiled to only accept single-quoted string literals.
69- This is a recommended option to avoid confusion - `SELECT "column" FROM tbl` is always a
70- column reference, `SELECT 'column'` is always a string literal.
71-
72- SQLCipher does not disable double-quoted string literals at compile-time. For consistency,
73- it is recommended to manually disable them for databases used with drift.
74-
7553# ## Important notice
7654
77- On the native side, `SQLCipher` and `sqlite3` stand in conflict with each other.
78- If your package depends on both native libraries, the one you will actually get may be undefined on some platforms.
79- In particular, if you depend on `sqlcipher_flutter_libs` and another package you use depends on say `sqflite`,
80- you could still be getting the regular `sqlite3` library without support for encryption!
81-
82- For this reason, it is recommended that you check that the `cipher_version` pragma is available at runtime :
55+ SQLite3MultipleCiphers is a fork of SQLite with added encryption support.
56+ To ensure you're using the right version in your app, it is recommended that you check for the `cipher`
57+ pragma at runtime (since that is not provided by upstream SQLite) :
8358
8459<Snippet href="/lib/src/snippets/platforms/encryption.dart" name="check_cipher" />
8560
@@ -88,25 +63,34 @@ Next, add an `assert(_debugCheckHasCipher(database))` before using the database.
8863
8964<Snippet href="/lib/src/snippets/platforms/encryption.dart" name="encrypted2" />
9065
91- If this check reveals that the encrypted variant is not available, please see [the documentation here](https://github.com/simolus3/sqlite3.dart/tree/master/sqlcipher_flutter_libs#incompatibilities-with-sqlite3-on-ios-and-macos) for advice.
66+ If this check reveals that the encrypted variant is not available, check your hook options
67+ or open an issue on [this repository](https://github.com/simolus3/sqlite3.dart/) for further advice.
9268
9369# ## Encrypting existing databases
9470
9571If you have an existing database which you now want to encrypt, there are a few steps to consider.
96- First, replace your dependencies on `drift_flutter` or `sqlite3_flutter_libs` with
97- ` sqlcipher_flutter_libs` as shown in the [setup](#setup).
72+ First, add hook options to link SQLite3MultipleCiphers as shown in [setup](#setup).
9873
9974Note however that you can't just apply the `pragma key = ` statement on existing databases!
100- To migrate existing databases to encryption, SQLCipher recommends [these steps ](https://discuss.zetetic.net/t/how-to-encrypt-a-plaintext-sqlite-database-to-use-sqlcipher-and-avoid-file-is-encrypted-or-is-not-a-database-errors/868 ) :
75+ To migrate existing databases to encryption, this creates a temporary copy that will be encrypted with [`pragma rekey` ](https://utelle.github.io/SQLite3MultipleCiphers/docs/configuration/config_sql_pragmas/#pragma-rekey--hexrekey ):
10176
102- 1. Opening your existing database.
103- 2. Attaching a new encrypted-variant.
104- 3. Calling the `sqcipher_export` function to copy the unencrypted database into the encrypted file.
105- 4. Closing and deleting the unencrypted database.
77+ <Snippet href="/lib/src/snippets/platforms/encryption.dart" name="migration" />
10678
107- In drift, you can run these steps in the `isolateSetup` callback when opening a `NativeDatabase` :
79+ # ## Migrating from SQLCipher to SQLite3MultipleCiphers
10880
109- <Snippet href="/lib/src/snippets/platforms/encryption.dart" name="migration" />
81+ Previous versions of this page suggested using `sqlcipher_flutter_libs` and custom code to enable
82+ SQLCipher. Starting from drift version 2.32.0 and version 3.x of the `sqlite3` package, using
83+ SQLite3MultipleCiphers is much easier.
84+
85+ SQLCipher is no longer supported with a straightforward setup. It is possible to use existing encrypted
86+ databases with SQLite3MultipleCiphers. To do that, run the following pragmas before `pragma key`
87+ after upgrading :
88+
89+ 1. `PRAGMA cipher = 'sqlcipher'`
90+ 2. `PRAGMA legacy = 4`.
91+
92+ Please carefully test that your app supports existing databases after upgrading to SQLite3MultipleCiphers.
93+ For more details, see [this issue](https://github.com/simolus3/sqlite3.dart/issues/302#issuecomment-3765247078).
11094
11195# # Using `encrypted_drift`
11296
0 commit comments