MSC4312: Resetting cross-signing keys in the OAuth world

[Johennes]

Rendered

Implementations:

• Server
  • Synapse: Use custom stage UIA error for MAS cross-signing reset element-hq/synapse#17509 (July 2024)
  • MAS:
    • Allow users to temporarily allow cross-signing reset matrix-authentication-service#2142
    • Move the cross-signing reset to its own page matrix-authentication-service#2364
    • Iterate cross signing reset flows matrix-authentication-service#3102
• Client:
  • Element Web (supporting the new UIA stage): Add support for org.matrix.cross_signing_reset UIA stage flow element-hq/matrix-react-sdk#34
  • Example of client that doesn't support the UIA stage working using the fallback:

ScreenRecording_09-25-2025.16-32-30_2.mov

---

SCT Stuff:

FCP tickyboxes

MSC checklist

[hughns]

MAS lists the org.matrix.cross_signing_reset action in the account_management_actions_supported from MSC4191. e.g. in https://account.matrix.org/.well-known/openid-configuration

Does this need to be added to this MSC?

[Johennes]

MAS lists the org.matrix.cross_signing_reset action in the account_management_actions_supported from MSC4191. e.g. in https://account.matrix.org/.well-known/openid-configuration

Does this need to be added to this MSC?

Good point. I hadn't noticed that MSC4191 doesn't list this action. Have added it here with a781be5.

[hughns]

Following a discussion with @erikjohnston earlier it might be helpful to elaborate on this:

Suggested change

	An example of a potential mechanism that could help achieve this is the
	[RFC 9470 OAuth 2.0 Step Up Authentication Challenge Protocol](https://datatracker.ietf.org/doc/rfc9470/).
	Theoretically such a mechanism could act as full replacement for UIA in the CS API
	where protection is needed for sensitive actions.
	However, the is no proposal on how this would be applied to the CS API and therefore
	it is proposed to codify this present mechanism that does allow for the specific
	cross-signing reset action.

[clokep]

This feels like the correct solution?

[Johennes]

Yeah, it probably is. This proposal was originally only intended to document the status quo that I found on matrix.org so that it could be reused by other implementations in the interim. It doesn't feel great to add this into the spec. If the good solution is far away though, it might be better than the current situation where the spec renders the OAuth login APIs and cross-signing key reset incompatible.

I applied @hughns suggestion separately with d8649fb but will leave this thread open in case there's further input.

[Johennes]

It may not change the plan for this proposal but I have tried to adapt RFC9470 to Matrix in #4363.

[richvdh]

Given that this is already deployed on matrix.org ( 😢 ), and Element-Web implements support for it (cf element-hq/element-meta#2956), I think we had better spec what we have asap and leave the Correct Solution for another time.

[turt2live]

otherwise lgtm

[turt2live]

MSCs proposed for Final Comment Period (FCP) should meet the requirements outlined in the checklist prior to being accepted into the spec. This checklist is a bit long, but aims to reduce the number of follow-on MSCs after a feature lands.

SCT members: please check off things you check for, and raise a concern against FCP if the checklist is incomplete. If an item doesn't apply, prefer to check it rather than remove it. Unchecking items is encouraged where applicable.

MSC authors: feel free to ask in a thread on your MSC or in the#matrix-spec:matrix.org room for clarification of any of these points.

• Are appropriate implementation(s) specified in the MSC’s PR description?
• Are all MSCs that this MSC depends on already accepted?
• For each new endpoint that is introduced:
  • Have authentication requirements been specified?
  • Have rate-limiting requirements been specified?
  • Have guest access requirements been specified?
  • Are error responses specified?
    • Does each error case have a specified errcode (e.g. M_FORBIDDEN) and HTTP status code?
      • If a new errcode is introduced, is it clear that it is new?
• Will the MSC require a new room version, and if so, has that been made clear?
  • Is the reason for a new room version clearly stated? For example, modifying the set of redacted fields changes how event IDs are calculated, thus requiring a new room version.
• Are backwards-compatibility concerns appropriately addressed?
• Are the endpoint conventions honoured?
  • Do HTTP endpoints use_underscores_like_this?
  • Will the endpoint return unbounded data? If so, has pagination been considered?
  • If the endpoint utilises pagination, is it consistent with the appendices?
• An introduction exists and clearly outlines the problem being solved. Ideally, the first paragraph should be understandable by a non-technical audience.
• All outstanding threads are resolved
  • All feedback is incorporated into the proposal text itself, either as a fix or noted as an alternative
• While the exact sections do not need to be present, the details implied by the proposal template are covered. Namely:
  • Introduction
  • Proposal text
  • Potential issues
  • Alternatives
  • Dependencies
• Stable identifiers are used throughout the proposal, except for the unstable prefix section
  • Unstable prefixes consider the awkward accepted-but-not-merged state
  • Chosen unstable prefixes do not pollute any global namespace (use “org.matrix.mscXXXX”, not “org.matrix”).
• Changes have applicable Sign Off from all authors/editors/contributors
• There is a dedicated "Security Considerations" section which detail any possible attacks/vulnerabilities this proposal may introduce, even if this is "None.". See RFC3552 for things to think about, but in particular pay attention to the OWASP Top Ten.

[turt2live]

@mscbot fcp merge
@mscbot concern Requires evidence that fallback UIA support kinda mostly works well enough
@mscbot concern Include Step Up alternative in proposal

[mscbot]

Team member @mscbot has proposed to merge this. The next step is review by the rest of the tagged people:

• @clokep
• @dbkr
• @uhoreg
• @turt2live
• @ara4n
• @anoadragon453
• @richvdh
• @tulir
• @erikjohnston
• @KitsuneRal

Concerns:

• Requires evidence that fallback UIA support kinda mostly works well enough
• Include Step Up alternative in proposal
• Is not documenting the current in-the-wild implementation

Once at least 75% of reviewers approve (and there are no outstanding concerns), this will enter its final comment period. If you spot a major issue that hasn't been raised at any point in this process, please speak up!

See this document for information about what commands tagged team members can give me.

[dbkr]

@mscbot concern Is not documenting the current in-the-wild implementation

[turt2live]

@mscbot resolve Requires evidence that fallback UIA support kinda mostly works well enough
@mscbot resolve Include Step Up alternative in proposal

[dbkr]

@mscbot resolve Is not documenting the current in-the-wild implementation

[dbkr]

@mscbot resolve Is not documenting the current in-the-wild implementation

[clokep]

To write it out explicitly -- I'm pretty meh on this change (probably a -0.3), but not enough to block it.

[mscbot]

🔔 This is now entering its final comment period, as per the review above. 🔔

[mscbot]

The final comment period, with a disposition to merge, as per the review above, is now complete.

[Johennes]

Spec PR: matrix-org/matrix-spec#2234