Key reset for EX

[pmaier1]

Story

As a user I have to be able to reset my encryption ("crypto identity") for that I am able to use the app when I sign-in a new session and have no other device or recovery key to verify the device with.

Concept

As we have two authentication modes today (legacy password auth / OIDC), we have to support two different flows for key reset that are outlined in the technical concept below.

• https://docs.google.com/document/d/1GERrb9v4QZjRMrnHdx3ahi0YVfAfN_ZwlG6uj36EeIQ/edit#heading=h.5wj7kc9kjciz
• Step 1: Implement solution for password-authed accounts, non-MAS ("Legacy user reset")
• Step 2: Implement solution for MAS-enabled deployments ("OIDC user reset")

Priority should be on 1 as MAS has not been rolled-out widely yet and most users fall into this category.

Leads

Tech: @stefanceriu Design: @americanrefugee / @amshakal

Designs

• iOS https://www.figma.com/design/jvZ7TIyd7V9Vn8sIDB9vMd/Compound-iOS-Templates?node-id=0-1&t=E1oOio3ohHTHX0dL-0
• Android https://www.figma.com/design/pDlJZGBsri47FNTXMnEdXB/Compound-Android-Templates?node-id=0-1&t=wg42wGm8YFka17WZ-0

Remarks

As per document and designs above the entry point for crypto identity reset is the session verification screen from where the user can chose to use the "Can't confirm" option to proceed with the reset.

The session verification screen:

• Should not show the Use another device option if this is the last session
• It should not show the Use recovery key option if recovery hasn't been previously set up
• It should directly proceed to reset if neither of the 2 options are available

Resetting itself can be done in 2 different ways based on the session type:

• for MAS-based sessions
  • the user will be presented with the account management webpage on which they would need to confirm the reset
  • while that's happening the client will try uploading keys in the background until it eventually succeeds
• for username/password based sessions
  • try uploading the keys, if it works then there's nothing else to do
  • it it fails then request permissions to upload new keys
  • upload the keys and complete the reset

For both flows the following stand:

• if the keys never get uploaded and app gets restarted, or for any other unforseen state, the user should be forcefully signed out
• once keys get uploaded the onboarding/FTUE flow continues with the next normal step (analytics permission, push notifications etc.)
• during the reset previously setup recovery will be reset and the user will be prompted to set it up again once gaining access to the app (as if it was never setup to being with)
• a new key backup will be created as well (if backups weren't previously manually disabled)
• any other existing session will become unverified and will prompt the user to verify again, either interactive or using the newly setup recovery key (if any)

Scope

### Android

### iOS
- [ ] https://github.com/element-hq/element-x-ios/issues/3102

### Web

### Rust
- [ ] matrix-org/matrix-rust-sdk#3670
- [ ] https://github.com/matrix-org/matrix-rust-sdk/pull/3759

[BillCarsonFr]

Note to make the reset less destructive as possible we should ensure that all clients have a local copy of what is in the backup (import all in background at least once) https://github.com/element-hq/element-meta/issues/2446

[manuroe]

The proposal looks sane to me. We need to estimate the work. What is the expected time for this?

Should we wait for https://github.com/element-hq/element-meta/issues/2446 to be landed to be as less destructive as possible?

Should we add this reset flow to the app backup settings?

[pmaier1]

Note to make the reset less destructive as possible we should ensure that all clients have a local copy of what is in the backup (import all in background at least once) https://github.com/element-hq/element-meta/issues/2446

Generally speaking, yes, all clients should have a copy of all the secrets. But the scenario we are mainly looking at right now is that you're trying to sign-in an EX device but you don't have other devices to verify with and have lost your recovery key. In this case this doesn't help, does it?

We should therefore not wait for it landing. Priority should be on the non-MAS flow as this is what most users are confronted with today.

What is the expected time for this?

As we've already made device verification mandatory on EX, we'd like to see this land as soon as possible. The designs are expected to be finished this week.

[pmaier1]

I have updated the OP. The designs are now final and this is ready for engineering.

[pmaier1]

Heads-up, the designs for this feature have just been update to reflect the latest thinking on terminology.

[poljar]

SDK PR is here: https://github.com/matrix-org/matrix-rust-sdk/pull/3670

[richvdh]

Question: what should happen if the client already has a copy of the secure backup key? It is not obvious to me that we should delete the existing key backup in that case, since it will mean that all existing room keys have to be re-backed-up.

(Possibly it depends on the reason for the reset: if it is simply that the user has forgotten the 4S recovery key, then there is no need to reset the key backup. OTOH if the user suspects that the key backup is compromised in some way, then the existing backup should be deleted too.)

[richvdh]

Also: it seems like this issue is specific to the pre-verification flow, in which the client can be assumed not to have any of the secrets (backup decryption key, secret cross-signing keys) -- or at least, not the secret cross-signing keys.

There is a second potential flow, in which a client may have some or all of those secrets, but the user wants to reset their Key storage (4S) because they have forgotten their passphrase. In this case, we should not reset the cross-signing keys if we can avoid it, because it will undo any user or device verifications that have taken place.

EA classic (at least) does expose this second flow. I don't think EW does, despite the presence of two ill-defined "Reset" buttons on its setting page, though as https://github.com/element-hq/element-web/issues/27841 points out, arguably it should.

[stefanceriu]

This has now been implemented on iOS in https://github.com/element-hq/element-x-ios/pull/3107 based on the Rust FFI API exposed in https://github.com/matrix-org/matrix-rust-sdk/pull/3759

We had to make few changes from the original designs though (see videos attached to the iOS PR):

1. The backend might or might not choose to ask for interactive authentication and part of the reset flow needs to happen before resetting the cross-signing keys. As such the reset popup confirmation will be displayed before starting the process
2. The MAS authentication page is different than the designs so the Legacy flow root screen has been used here as well.

[pmaier1]

Nice one, looks great, thanks!

The MAS authentication page is different than the designs so the Legacy flow root screen has been used here as well.

Please stick to the designs. The MAS screen will be adopted soon.

cc @sandhose

[pmaier1]

The backend might or might not choose to ask for interactive authentication and part of the reset flow needs to happen before resetting the cross-signing keys. As such the reset popup confirmation will be displayed before starting the process

Good catch. For the legacy flow this is fine. For the OIDC flow we intentionally didn't add yet another confirmation dialog as you already confirm it on the MAS screen. In this case I don't think we should show it.

[pmaier1]

The MAS authentication page is different than the designs so the Legacy flow root screen has been used here as well.

Please don't consider this a blocker. The next MAS release (before the EX launch) will have the new design. You can just go ahead and adopt the flow assuming that the new design is already available.

[stefanceriu]

This PR will take care of the tweaks we talked about yesterday, including adding a logout button on the identity confirmation screen.

[manuroe]

@pmaier1 can we consider this feature complete? All the tasks are done

[manuroe]

Everything seems ok. I am closing this issue. Thanks all. The feature is going to be useful in an EX world.

[pmaier1]

Yep, the feature looks and works nicely, IMO. Thanks everybody, great work :clap:

[poljar]

Question: what should happen if the client already has a copy of the secure backup key? It is not obvious to me that we should delete the existing key backup in that case, since it will mean that all existing room keys have to be re-backed-up.

(Possibly it depends on the reason for the reset: if it is simply that the user has forgotten the 4S recovery key, then there is no need to reset the key backup. OTOH if the user suspects that the key backup is compromised in some way, then the existing backup should be deleted too.)

I think that this is feature is specifically for the case where you forgot things and don't have any secrets on your current device.

There is a second potential flow, in which a client may have some or all of those secrets, but the user wants to reset their Key storage (4S) because they have forgotten their passphrase. In this case, we should not reset the cross-signing keys if we can avoid it, because it will undo any user or device verifications that have taken place.

AFAIK that flow is exposed as just disabling "recovery" and re-enabling it, which will not delete your cross-signing identity, though it will delete your room key backup.