MSC4161: Crypto terminology for non-technical users#4161
MSC4161: Crypto terminology for non-technical users#4161andybalaam wants to merge 60 commits intomainfrom
Conversation
uhoreg
added
e2e
proposal
turt2live
added
the
needs-implementation
Co-authored-by: Richard van der Hoff <[email protected]>
Co-authored-by: Richard van der Hoff <[email protected]>
…es to use Alice and Bob
Co-authored-by: Travis Ralston <[email protected]>
Co-authored-by: Travis Ralston <[email protected]>
Co-authored-by: Travis Ralston <[email protected]>
Co-authored-by: Travis Ralston <[email protected]>
Based on real-world feedback from Element clients, 'identity was changed', and especially 'identity appears to have been changed' were very confusing. Resetting an identity is something that the user can do themselves, so it is much clearer what we mean. They can ask the other user "did you reset your identity?" and it is easier for them to answer.
|
After watching Andy's conference (two passwords), these are my comments: Most of the users don't care whether they are linking/combining or whatever they are doing other than login and get the messages. So, from my point of view, it is all about how am I getting the messages from the server. This is really the login flow management and wordings. So the flow is:
My suggestion is 'Login Verification'. This means for the user, they are just verifying the new login. They can use either other logged in devices or 'Access Code'. 'Access Code' is the 'recovery key'. From a user point of view, this means to access the messages from the server (i.e. recover the key) they need the 'Access Code'. For the user verification, we can also use 'Contact Verification'. Summary:
And it is much easier to tell others 'Mate, if you lose your access code, then you will lose your access to the messages 😄' 
One more thought: What if the verification from other logins is disabled altogether. Alternatively, if a verified login is available, is it possible to get the 'Access Code' from that login and use it to verify the new login? This maybe a security issue, but EDIT 20251104: This also removes the confusion between devices/sessions, as the requirement is to verify each and every 'Login'. |
|
After some informal user testing and feedback from the 2025 Matrix conference, I have pushed two significant changes today.
Feedback welcome, but I think this now represents my best ideas about what we should do. |
github-project-automation
bot
moved this to Tracking for review
in Spec Core Team Workflow
turt2live
moved this from Tracking for review
to Proposed for FCP readiness
in Spec Core Team Workflow
turt2live
left a comment
turt2live
left a comment
There was a problem hiding this comment.
This MSC is currently in queue for proposed-FCP, though I feel there's a couple more steps that need to happen before it can confidently enter that state. The MSC checklist I'll add shortly after this review will cover the points in more detail.
The things I feel need addressing before this is ready for proposed-FCP are:
- Resolution of outstanding comments (prior to this review). These threads are either long, old, or both. They should be incorporated into the proposal text or marked as resolved in GitHub if already addressed.
- The exception is (always) the "implementation requirements" thread - that takes place of implementations in the description.
- Evidence of implementation. See my comment on the "implementation requirements" thread.
When these two points, and any other unchecked boxes from the checklist or concerns from other SCT members, are addressed, please re-raise this MSC for proposed-FCP in the SCT Office. Questions regarding threads are best asked in those threads. Questions for the SCT which are outside of existing threads should be raised in the SCT Office (SCT members might not see individual/team pings).
Overall though, in case it's not totally clear from the small number of comments, this proposal is extremely close to proposed-FCP. I'm looking forward to it getting pushed to that state!
| Devices that have not been cross-signed by the user who owns them are | ||
| **unconfirmed**. It is important that devices are **confirmed**, to prevent | ||
| security problems like a compromised server creating fake devices that | ||
| can impersonate users (see | ||
| [MSC4153](https://github.com/matrix-org/matrix-spec-proposals/pull/4153)). | ||
|
|
||
| > "This device is not confirmed. Please confirm it to continue." | ||
|
|
||
| > "Confirm it's you" (when asking to confirm a device during login) |
There was a problem hiding this comment.
For clarity: If the device does not support encryption, is it confirmed or unconfirmed?
(this should be addressed in the MSC)
| When an unverified contact resets their digital identity, the user should be warned that | ||
| this happened. |
There was a problem hiding this comment.
| When an unverified contact resets their digital identity, the user should be warned that | |
| this happened. | |
| When a verified contact resets their digital identity, the user should be warned that | |
| this happened. |
surely?
| When the user does not have the message key for a permanent and well-understood | ||
| reason, for example if it was sent before they joined the room, we say **you | ||
| don't have access to this message**. | ||
|
|
||
| > "You don't have access to this message" e.g. if it was sent before the user | ||
| > entered the room, or the user does not have key storage set up. |
There was a problem hiding this comment.
presumably this also includes when the sender refuses to provide the key (using a withheld error code)?
There was a problem hiding this comment.
I'm not seeing implementation attached to this MSC, so I've gone through to identify precise implementation requirements. Please provide screenshots and/or PR links which demonstrate each of these checkboxes. Ideally, implementation for each checkbox is provided for each of Element's clients (including Classic), though at a minimum all of these requirements must be met by at least a single Element client (preferably Web over X over Classic).
In short, though the MSC states that clients SHOULD use the terminology of the MSC, the implementation requirements upon Element are a MUST (at least while this proposal is pre-acceptance - Element can return to a SHOULD after successful FCP).
Implementation evidence required:
- Element using "devices" or "sessions" to refer to what the spec calls devices.
- Element using the word "unconfirmed" for devices which aren't cross-signed.
- Element using the term "linking" to refer to logging in & confirming a device concurrently.
- Element using "log out" or "sign out".
- Element shows other users as "verified" and "not verified".
- Element shows warnings that digital identities have been reset.
- If the MSC intended to show this when verified contacts reset their identity, then those users need to produce such warnings. Alternatively, unverified users need to produce the warnings. If both are intended, then Element needs to do both as well.
- Element offers to "withdraw verification" or to "re-verify"
- When for a verified contact, Element's warning cannot be dismissed and states that the other user's "digital identity has been reset".
- Element does not use the term "cross-signing" in its UI.
- Element does not use the term "Trust On First Use (TOFU)" in its UI.
- Element does not use the term "cryptographic identity" in its UI.
- Element uses "digital identity" to refer to a device's cross-signing keys/identity and key backup/storage.
- Element uses "message key" to talk about keys required to decrypt a message/event.
- Element uses "unable to decrypt" to describe the following scenarios:
- "Waiting for this message" when message keys are expected but not delivered (yet, hopefully).
- "You don't have access to this message" when keys are not expected and not delivered (ever, hopefully).
- When some error occurred. Exact wording is not defined by the MSC, though "unable to decrypt" is to be used.
- Element uses "message history" to describe decryptable events.
- Element uses "key storage" (ideally in combination with "message history") to talk about key backup.
- Element uses "recovery" when a user loses access to all of their devices (or has zero encryption-capable devices).
- Element uses "recovery key" or "recovery code" or "recovery passphrase" to talk about how to fix this.
- If using "recovery key/code", Element is talking about a machine-generated key a user can upload or enter.
- If using "recovery passphrase", Element is talking about a user-understandable phrase or password-like string to represent the machine-generated key.
- When a user loses their recovery key, Element says they can "reset" it.
- Element does not use "secret storage" or "quad S".
- If Element uses tooltips to say "your recovery key may have been called a security key in the past" (or similar), this is fine.
- Element allows users to "change their recovery key" rather than reset it.
- Element distinguishes between resetting digital identity and changing recovery key.
|
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.
|
CrazyNicc
left a comment
CrazyNicc
left a comment
There was a problem hiding this comment.
Just a minor suggestion for improving the clarity, and using one less term.
| When a mechanism for simultaneously logging in and confirming a device | ||
| is available (e.g. | ||
| [MSC4108: QR code login](https://github.com/matrix-org/matrix-spec-proposals/pull/4108)) | ||
| then we talk about **linking** the device. After a device is linked, it is | ||
| logged in and confirmed. | ||
|
|
||
| > "Link this device by scanning the QR code" |
There was a problem hiding this comment.
Should we really introduce another term here? I feel like Log-in and confirm this device by scanning the QR code would be more fitting, and use already established terms in this document, although it is a bit longer. I wouldn't immediately know what linking a device would mean.
There was a problem hiding this comment.
Signal, WhatsApp and Telegram all use "linking" to refer to logging in with QR codes, so I'd expect users to know what it means even though it's not an established term in Matrix.
20 participants
Rendered
Conflict of Interest declaration: I am employed by Element. This MSC was written as part of my work on the Element Cryptography team.
SCT Stuff
MSC checklist
No FCP tickyboxes