Skip to content

data-encryption.mdx

Latest commit

 

History

History
226 lines (168 loc) · 9.36 KB

data-encryption.mdx

File metadata and controls

226 lines (168 loc) · 9.36 KB
title Data Encryption

In Transit Encryption

Data is always encrypted in transit using TLS — both between the client and PowerSync, and between PowerSync and the source database.

At Rest Encryption

The client-side database can be encrypted at rest. This is currently available for:

The PowerSync SDK supports SQLite3MultipleCiphers on all native platforms and the web, which can be used to encrypt databases.

Setting up encryption has changed in version 2.0 of the PowerSync SDK. When upgrading, follow these steps and remove dependencies on powersync_sqlcipher.

To enable encryption, pass an instance of EncryptionOptions to a PowerSyncDatabase constructor:

final db = PowerSyncDatabase(
  schema: schema,
  path: path,
  encryption: EncryptionOptions(
    key: 'my secret key',
  ),
);

Additionally, encryption needs to be enabled for your target platforms. For native platforms, add this snippet to your pubspec.yaml:

hooks:
  user_defines:
    sqlite3:
      # Bundle and load SQLite3MultipleCiphers instead of SQLite for encryption.
      source: sqlite3mc

If you're using pub workspaces, this needs to be added to the root pubspec.yaml, not the one for your app.

On the web, enabling encryption requires SQLite3MultipleCiphers as well. PowerSync releases have a sqlite3mc.wasm file attached to them, which can be downloaded to web/sqlite3.wasm to add encryption support.

You can also run dart run powersync:setup_web --encryption to download the correct binary into your web/ directory.

[SQLCipher](https://www.zetetic.net/sqlcipher/) support is available for PowerSync's React Native SDK through the `@powersync/op-sqlite` package. See usage details in the package README:

The Web SDK uses the [ChaCha20 cipher algorithm by default](https://utelle.github.io/SQLite3MultipleCiphers/docs/ciphers/cipher_chacha20/). See usage details in the package README:

Additionally, a minimal example demonstrating encryption of the web database is available here.

Encryption support is available for PowerSync's Node.js SDK using [`better-sqlite3-multiple-ciphers`](https://www.npmjs.com/package/better-sqlite3-multiple-ciphers). See usage details and code examples in the [Node.js SDK reference](/client-sdks/reference/node#encryption-and-custom-sqlite-drivers). Encryption support is available for PowerSync's Kotlin SDK (since version 1.9.0) using [`SQLite3MultipleCiphers`](https://utelle.github.io/SQLite3MultipleCiphers/) via the [`com.powersync:sqlite3multipleciphers`](https://central.sonatype.com/artifact/com.powersync/sqlite3multipleciphers) package. This allows you to encrypt your local SQLite database with various cipher algorithms.

Setup:

  1. Replace your dependency on com.powersync:core with com.powersync:common of the same version.

  2. Add a dependency on com.powersync:sqlite3multipleciphers.

  3. Since :core includes a Ktor client implementation, you'll need to add one manually if you're not already using Ktor:

    • Android/JVM: io.ktor:ktor-client-okhttp
    • Apple targets (Kotlin/Native): io.ktor:ktor-client-darwin

  4. Use the appropriate encrypted database factory when creating your PowerSyncDatabase:

// Android
val database = PowerSyncDatabase(
    factory = AndroidEncryptedDatabaseFactory(
        context,
        Key.Passphrase("your encryption key")
    ),
    schema = yourSchema,
    dbFilename = "your_database"
)

// JVM
val database = PowerSyncDatabase(
    factory = JavaEncryptedDatabaseFactory(
        Key.Passphrase("your encryption key")
    ),
    schema = yourSchema,
    dbFilename = "your_database"
)

// Kotlin/Native (Apple targets)
val database = PowerSyncDatabase(
    factory = NativeEncryptedDatabaseFactory(
        Key.Passphrase("your encryption key")
    ),
    schema = yourSchema,
    dbFilename = "your_database"
)
Store encryption keys securely rather than hardcoding them in your code.

For more details, see the sqlite3multipleciphers README in the PowerSync Kotlin SDK repository.

Using encryption with Room:

When using PowerSync with Room, PowerSync wraps the Room database instead of opening its own connection. To use an encrypted database with Room, wrap an encrypted PersistentConnectionFactory in a SQLiteDriver and pass it to RoomDatabase.Builder.setDriver:

class PowerSyncConnectionFactoryAsSqliteDriver(
    private val powersyncFactory: PersistentConnectionFactory
) : SQLiteDriver {
    override fun open(fileName: String): SQLiteConnection {
        if (fileName == ":memory:") {
            return powersyncFactory.openInMemoryConnection()
        }

        return powersyncFactory.openConnection(fileName, null, false)
    }
}

Depending on your target platform, pass an AndroidEncryptedDatabaseFactory, JavaEncryptedDatabaseFactory, or NativeEncryptedDatabaseFactory to the wrapper. The factory automatically installs the SQLite3MultipleCiphers extension — no manual setup required.

val driver = PowerSyncConnectionFactoryAsSqliteDriver(
    AndroidEncryptedDatabaseFactory(context, Key.Passphrase("your encryption key"))
)

val roomDb = Room.databaseBuilder<MyDatabase>(context, "your_database")
    .setDriver(driver)
    .build()
Encryption support is available for PowerSync's Swift SDK (since version 1.10.0) using [`SQLite3MultipleCiphers`](https://utelle.github.io/SQLite3MultipleCiphers/). Encryption keys are configured with the `initialStatements` parameter on `PowerSyncDatabase()` which allows running `PRAGMA key` statements.

Setup requirements:

The PowerSync Swift SDK depends on CSQLite to build and link SQLite. That package can be configured to optionally link SQLite3 Multiple Ciphers by enabling the Encryption trait. Due to SwiftPM limitations, we can't directly expose that trait on the Swift SDK.

Instead, we recommend directly depending on CSQLite with the encryption trait, which will enable the same for the SDK (since each package can only appear in a build once). Since Xcode doesn't support specifying package traits when adding dependencies, you first need to add a local Swift package as a workaround.

  1. Create a local Package.swift in your project that depends on CSQLite with the Encryption trait:
// swift-tools-version: 6.2
import PackageDescription

let package = Package(
    name: "helper",
    products: [
        .library(name: "helper", targets: ["helper"]),
    ],
    dependencies: [
        .package(url: "https://github.com/powersync-ja/CSQLite.git", exact: "3.51.2", traits: ["Encryption"]),
    ],
    targets: [
        .target(name: "helper", dependencies: [.product(name: "CSQLite", package: "CSQLite")]),
    ]
)

  1. Add a dependency to this local package from Xcode and resolve packages. This enables sqlite3mc for your entire app, including the PowerSync framework.

  2. Configure encryption when opening the database:

let db = PowerSyncDatabase(
    schema: yourSchema,
    initialStatements: ["pragma key = 'your encryption key'"]
)
Store encryption keys securely (e.g., in Keychain) rather than hardcoding them in your code.

For a complete working example, see the SwiftEncryptionDemo in the PowerSync Swift SDK repository.

Support for encryption on other platforms is planned. In the meantime, let us know your needs and use cases on [Discord](https://discord.gg/powersync).

End-to-end Encryption

For end-to-end encryption, the encrypted data can be synced using PowerSync. The data can then either be encrypted and decrypted directly in memory by the application, or a separate local-only table can be used to persist the decrypted data — allowing querying the data directly.

Raw SQLite Tables can be used for full control over the SQLite schema and managing tables for the decrypted data. We have a React & Supabase example app that demonstrates this approach. See also the accompanying blog post.

See Also