Skip to content

Improve docs about the Rust crypto integration #9035

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Jun 2, 2025
Merged

Improve docs about the Rust crypto integration #9035

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -70,6 +70,8 @@ Note that if the templates are modified, the only things to do is to restart And

For now, the Matrix SDK and the Element application are in the same project. So there is no specific thing to do, this project should compile without any special action.

See [docs/rust_crypto_integration.md](./docs/rust_crypto_integration.md#testing-with-a-local-rust-aar) for notes on building against a custom version of the Rust `matrix-sdk-crypto`.

## I want to help translating Element

If you want to fix an issue with an English string, please submit a PR.
Expand Down
55 changes: 14 additions & 41 deletions docs/rust_crypto_integration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,31 +1,18 @@
## Overview

Until the final migration to [rust crypto sdk](https://github.com/matrix-org/matrix-rust-components-kotlin), the Element Android project will support two
different SDK as a product flavor.

The `matrix-sdk-android` module is defining a new flavor dimension `crypto`, with two flavors `kotlinCrypto` and `rustCrypto`.
The crypto module cannot be changed at runtime, it's a build time configuration. The app supports migration from kotlinCrypto to rustCrypto but not the other
way around.

The code that is not shared between the flavors is located in dedicated source sets (`src/kotlinCrypto/`, `src/rustCrypto/`). Some tests are also extracted
in different source sets because they were accessing internal API and won't work with the rust crypto sdk.

## Noticeable changes

As a general rule, if you stick to the `kotlinCrypto` the app should behave as it was before the integration of favours.
There is a noticeable exception though:
In order to integrate the rust crypto several APIs had to be migrated from callback code to suspendable code. This change
impacted a lot the key verification engine (user and device verification), so this part has been refactored for `kotlinCrypto`. The UI is also impacted,
the verification flows now match the web experience.

TLDR; Verification UI and engine has been refactored.
Element Android [now](https://github.com/element-hq/element-android/pull/8656) only supports the [rust crypto SDK](https://github.com/matrix-org/matrix-rust-sdk/tree/main/crates/matrix-sdk-crypto).

## Testing with a local rust aar

In order to run a custom rust SDK branch you can follow the direction in the [bindings repository](https://github.com/matrix-org/matrix-rust-components-kotlin)
in order to build the `matrix-rust-sdk-crypto.aar`.
In order to run a custom rust SDK branch you can follow the directions in the
[bindings repository](https://github.com/matrix-org/matrix-rust-components-kotlin?tab=readme-ov-file#testing-locally)
in order to build the AAR for the crypto crate.

Install the resulting file as `./library/rustCrypto/matrix-rust-sdk-crypto.aar`. For example:

Copy this lib in `library/rustCrypto/`, and rename it `matrix-rust-sdk-crypto.aar`.
```sh
ln -s <path_to_matrix-rust-components-kotlin>/crypto/crypto-android/build/outputs/aar/crypto-android-debug.aar ./library/rustCrypto/matrix-rust-sdk-crypto.aar
```

Then go to `matrix-sdk-android/build.gradle` and toggle the comments between the following lines.

Expand All @@ -34,30 +21,16 @@ Then go to `matrix-sdk-android/build.gradle` and toggle the comments between the
// rustCryptoApi project(":library:rustCrypto")
````

## Changes in CI

The workflow files have been updated to use the `kotlinCrypto` flavor, e.g

`assembleGplayNightly` => `assembleGplayKotlinCryptoNightly`

So building the unsigned release kotlin crypto apk is now:

`> ./gradlew assembleGplayKotlinCryptoRelease`

An additional workflow has been added to build the `rustCrypto` flavor (elementr.yml, ` Build debug APKs ER`).


## Database migration from kotlin to rust

With the kotlin flavor, the crypto information are persisted in the crypto realm database.
With the rust flavor, the crypto information are in a sqllite database.
Crypto information is now persisted in a SQLite database.

The migration is handled when injecting `@SessionRustFilesDirectory` in the olmMachine.
The migration from the old Realm database is handled when injecting `@SessionRustFilesDirectory` in the olmMachine.
When launching the first time after migration, the app will detect that there is no rust data repository and it will
create one. If there is an existing realm database, the data will then migrated to rust. See `ExtractMigrationDataUseCase`.
This will extract your device keys, account secrets, active olm and megolm sessions.

There is no inverse migration for now, as there is not yet rust pickle to olm pickle support in the sdk.

If you migrate your app to rust, and want to revert to kotlin you have to logout then login again.
There is no inverse migration. If you migrate to a version of the app that uses
the Rust library, and want to revert to a Kotlin-crypto version, you will have
to logout then login again.

Loading