GitHub-Mirror/riotX-android
1
0
Fork 1
mirror of https://github.com/vector-im/riotX-android synced 2025-10-05 15:52:47 +02:00
Code Issues Releases Wiki Activity

Improve docs about the Rust crypto integration (#9035)

Browse Source
This commit is contained in:
Richard van der Hoff
2025-06-02 13:56:58 +01:00
committed by GitHub
parent 333783ff2f
commit c3b923c27d
2 changed files with 16 additions and 41 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
CONTRIBUTING.md
View File

@@ -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. 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 ## I want to help translating Element
If you want to fix an issue with an English string, please submit a PR. If you want to fix an issue with an English string, please submit a PR.

55
docs/rust_crypto_integration.md
View File

@@ -1,31 +1,18 @@
## Overview ## 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 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).
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.
## Testing with a local rust aar ## 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 run a custom rust SDK branch you can follow the directions in the
in order to build the `matrix-rust-sdk-crypto.aar`. [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.
Copy this lib in `library/rustCrypto/`, and rename it `matrix-rust-sdk-crypto.aar`. Install the resulting file as `./library/rustCrypto/matrix-rust-sdk-crypto.aar`. For example:
```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. Then go to `matrix-sdk-android/build.gradle` and toggle the comments between the following lines.
@@ -34,30 +21,16 @@ Then go to `matrix-sdk-android/build.gradle` and toggle the comments between the
// rustCryptoApi project(":library:rustCrypto") // 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 ## Database migration from kotlin to rust
With the kotlin flavor, the crypto information are persisted in the crypto realm database. Crypto information is now persisted in a SQLite database.
With the rust flavor, the crypto information are in a sqllite 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 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`. 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. 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. 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
If you migrate your app to rust, and want to revert to kotlin you have to logout then login again. to logout then login again.