|
| 1 | +# MSC4312: Resetting cross-signing keys in the OAuth world |
| 2 | + |
| 3 | +Matrix v1.15 added new [OAuth APIs] for authentication. As of writing, these APIs are not compatible |
| 4 | +with the existing [User-Interactive Authentication (UIA)] mechanism that is used on a number of |
| 5 | +endpoints. This is not problematic in most cases because these endpoints cover actions that can now |
| 6 | +be preformed in the authorization server's web UI. One notable exception, however, is |
| 7 | +[`/_matrix/client/v3/keys/device_signing/upload`] which clients use to publish their cross-signing |
| 8 | +keys. This endpoint requires UIA when previously uploaded keys are being replaced, for instance |
| 9 | +because the user lost their recovery key. OAuth knows nothing about cross-signing keys and, |
| 10 | +consequently, the spec labels this endpoint as unusable: |
| 11 | + |
| 12 | +> **WARNING:** When this endpoint requires User-Interactive Authentication, it cannot be used when |
| 13 | +> the access token was obtained via the OAuth 2.0 API. |
| 14 | +
|
| 15 | +This is obviously not practical and unofficial workarounds have been invented to enable resetting |
| 16 | +one's cross-signing keys in the client / homeserver / authorization server triangle. This proposal |
| 17 | +documents these workarounds as a low-effort interim workaround until better solutions are available. |
| 18 | + |
| 19 | +## Proposal |
| 20 | + |
| 21 | +Clients that have authenticated via the new [OAuth APIs] continue to use |
| 22 | +[`/_matrix/client/v3/keys/device_signing/upload`] to replace cross-signing keys. Homeservers |
| 23 | +continue to enforce UIA on the endpoint with a flow containing a single stage `m.oauth`[^1] together |
| 24 | +with a URL that points to the authorization server's account management UI. |
| 25 | + |
| 26 | +``` json5 |
| 27 | +{ |
| 28 | + "session": "$ARBITRARY", |
| 29 | + "flows": [{ |
| 30 | + "stages": ["m.oauth"] |
| 31 | + }], |
| 32 | + "params": { |
| 33 | + "m.oauth": { |
| 34 | + "url": "$AUTHORIZATION_SERVER_ACCOUNT_MANAGEMENT_URL" |
| 35 | + } |
| 36 | + } |
| 37 | +} |
| 38 | +``` |
| 39 | + |
| 40 | +The client then instructs the user to approve the reset of their cross-signing keys using the |
| 41 | +provided URL. How exactly that approval is achieved is an implementation detail between the |
| 42 | +authorization server and the homeserver[^2]. The required end result is that after approving, the |
| 43 | +client can complete the stage without further parameters. |
| 44 | + |
| 45 | +``` json5 |
| 46 | +{ |
| 47 | + "auth": { |
| 48 | + "session": "$FROM_ABOVE" |
| 49 | + }, |
| 50 | + "master_key": ... |
| 51 | + ... |
| 52 | +} |
| 53 | +``` |
| 54 | + |
| 55 | +To facilitate the navigation, a new action `org.matrix.cross_signing_reset` is introduced and MAY be |
| 56 | +used in the `account_management_actions_supported` authorization server metadata field from |
| 57 | +[MSC4191]. Servers SHOULD use this action to deep link the user if the authorization server supports |
| 58 | +it. |
| 59 | + |
| 60 | +## Potential issues |
| 61 | + |
| 62 | +Semantically, resetting cross-signing keys doesn't fall into the authorization server's domain. The |
| 63 | +scheme outlined above increases coupling between the authorization server and the homeserver and |
| 64 | +makes it more difficult to use off-the-shelve OAuth authorization servers. |
| 65 | + |
| 66 | +## Alternatives |
| 67 | + |
| 68 | +Rather than approving cross-signing reset specifically, the authorization server could provide |
| 69 | +mechanisms for temporary scope elevation. An example of a potential mechanism that could help |
| 70 | +achieve this is the [RFC 9470 OAuth 2.0 Step Up Authentication Challenge Protocol]. Theoretically |
| 71 | +such a mechanism could act as full replacement for UIA in the CS API where protection is needed for |
| 72 | +sensitive actions. [MSC4363] attempts to adapt this protocol to Matrix. This MSC is, however, |
| 73 | +nascent and more complex. Therefore it is proposed to codify this present mechanism into the spec. |
| 74 | + |
| 75 | +## Security considerations |
| 76 | + |
| 77 | +Since the details of how approval is communicated between the authorization server and the |
| 78 | +homeserver are left unspecified, implementations could introduce security risks through their |
| 79 | +concrete choice of protocol. The temporary lifting of UIA that happens between |
| 80 | +[matrix-authentication-service] and Synapse, for instance, creates a time window in which an |
| 81 | +attacker with an access token could take over the account. |
| 82 | + |
| 83 | +## Unstable prefix |
| 84 | + |
| 85 | +While this MSC is not considered stable, `m.oauth` should be referred to as |
| 86 | +`org.matrix.cross_signing_reset`. |
| 87 | + |
| 88 | +Since this proposal is already used in production, for instance, on matrix.org, some care is |
| 89 | +required by servers when migrating from the unstable to the stable identifier. To prevent breaking |
| 90 | +clients that have implemented the unstable identifier, servers SHOULD offer two flows (one with each |
| 91 | +of `m.oauth` and `org.matrix.cross_signing_reset`). |
| 92 | + |
| 93 | +## Dependencies |
| 94 | + |
| 95 | +This proposal doesn't strictly depend on but works better with [MSC4191]. |
| 96 | + |
| 97 | +[^1]: Previous versions of this proposal used `m.cross_signing_reset` for the stage name. This was |
| 98 | + generalised into `m.oauth` to enable future reuse of the mechanism for other endpoints. |
| 99 | + |
| 100 | +[^2]: [matrix-authentication-service], for instance, uses a [Synapse admin API] to temporarily lift |
| 101 | + UIA on the endpoint. |
| 102 | + |
| 103 | + [OAuth APIs]: https://spec.matrix.org/v1.15/client-server-api/#oauth-20-api |
| 104 | + [User-Interactive Authentication (UIA)]: https://spec.matrix.org/v1.15/client-server-api/#user-interactive-authentication-api |
| 105 | + [`/_matrix/client/v3/keys/device_signing/upload`]: https://spec.matrix.org/v1.15/client-server-api/#post_matrixclientv3keysdevice_signingupload |
| 106 | + [MSC4191]: https://github.com/matrix-org/matrix-spec-proposals/pull/4191 |
| 107 | + [RFC 9470 OAuth 2.0 Step Up Authentication Challenge Protocol]: https://datatracker.ietf.org/doc/rfc9470/ |
| 108 | + [MSC4363]: https://github.com/matrix-org/matrix-spec-proposals/pull/4363 |
| 109 | + [matrix-authentication-service]: https://github.com/element-hq/matrix-authentication-service |
| 110 | + [Synapse admin API]: https://element-hq.github.io/synapse/latest/admin_api/user_admin_api.html#allow-replacing-master-cross-signing-key-without-user-interactive-auth |
0 commit comments