MSC4161: Crypto terminology for non-technical users #4161
Conversation
uhoreg
added
e2e
proposal
turt2live
added
the
needs-implementation
| When communicating about cryptography with non-technical users, we propose using | ||
| the following terms and concepts. | ||
|
|
||
| ### Devices |
There was a problem hiding this comment.
I really don't like calling sessions devices. It may work well for other, mobile first networks, but with matrix it's not all that uncommon to run multiple sessions on the same device.
There was a problem hiding this comment.
The problem is that "sessions" is used to refer to other things in the spec. So it would be more confusing to call something else "sessions".
There was a problem hiding this comment.
How about explicitly naming them "Crypto-Sessions" or something in this direction? I agree with the initial mention about devices. This is already these days due to some UIs a bit confusing.
There was a problem hiding this comment.
My personal take is that most people are familiar with "devices", and non-technical users will probably only have one crypto session per device. Further, where people do have multiple sessions on a device I think is it relatively easy to explain that they look like multiple devices to Matrix even though they exist on the same physical device.
In contrast, when I started using Matrix I had no idea what a "session" was, and as I learned more I became further confused because the word is used for several other concepts, including e.g message keys.
So I plan to propose this as-is.
There was a problem hiding this comment.
as much as i hate the "devices" terminology, this is also how it's named over on eg. Discord.
There was a problem hiding this comment.
as much as i hate the "devices" terminology, this is also how it's named over on eg. Discord.
or Whatsapp or Signal or other platforms. Which is why we suggest it in the first place.
Has user research shown that devices are preferred over sessions? Does Element have some data on their existing transition from devices to sessions?
Not sure whether we have something dedicated to exactly this comparison. @americanrefugee might know more.
There was a problem hiding this comment.
Gmail uses “session”. I’m sure others do too. I don’t think it’s such a foreign term for laypeople, or that it can’t be understood by them.
Whatsapp and Signal are more or less tied to phones and don’t expect any other client than “the one app” you have on said phones. In their context, device works. Comparing to them doesn’t work.
There was a problem hiding this comment.
The problem is that "sessions" is used to refer to other things in the spec. So it would be more confusing to call something else "sessions".
This MSC is about terms to use for non-technical users as far as I can see. I reckon it is not a problem to use a word for something in a given context, and a different word for the same thing in another context. The spec can call these crypto-sessions as was suggested above, or even devices if further disambiguation is deemed necessary. In a technical context, it can be clear that a “device” is not a piece of equipment, whereas it is really not clear for non-technical users.
Without even thinking about multiple distinct clients on the same device, a single client can become a new session if access to the previous session is lost for some reason. And so now you have two “devices” listed even though you used a single computer and a single client.
There was a problem hiding this comment.
Element's product people favour "devices", as do Discord, Signal and WhatsApp. We have a counter-example in Google, but I personally find much of Google's UI quite confusing, especially gmail.
As for having two devices listed even though you only used one: the proposed wording seems helpful to me - the mismatch between the wording and reality indicates a problem: they should remove the old device.
Perhaps the product designers from other products could chip in, but at the moment the scale seems to be tipping towards "devices".
There was a problem hiding this comment.
as do Discord, Signal and WhatsApp
Again: you are comparing apples to oranges. Signal and WhatsApp have a very different relationship to clients and devices.
Co-authored-by: Richard van der Hoff <[email protected]>
Co-authored-by: Richard van der Hoff <[email protected]>
…es to use Alice and Bob
| A **message key** is used to decrypt a message. The metaphor is that messages | ||
| are "locked in a box" by encrypting them, and "unlocked" by decrypting them. |
There was a problem hiding this comment.
Better term could be encryption key, as it's more common in news and other messenger apps.
There was a problem hiding this comment.
The problem is there are loads of things in Matrix that could be called an "encryption key". This is specifically a "message encryption key", shortened to "message key".
| > "Key storage holds your cryptographic identity on the server along with the | ||
| > keys that allow you to read your message history." |
There was a problem hiding this comment.
⚠️ Avoid talking about "cryptographic identity" which is very jargony.
There was a problem hiding this comment.
Hmm, yeah. Just "Key storage holds your identity"? Or maybe "Key storage holds your identity information"? @pmaier1 any thoughts?
There was a problem hiding this comment.
Key storage holds your identity
Yeah, keep it simple, makes sense to me.
There was a problem hiding this comment.
See https://github.com/matrix-org/matrix-spec-proposals/pull/4161/files#r1778410962 for my concerns about this. "Key storage holds your identity" sounds extremely confusing to me if I imagine myself as a non-technical newcomer to Matrix.
|
This should be given more priority. User-friendliness of clients is a must |
There was a problem hiding this comment.
This MSC is something I think would be extremely helpful in the spec. It's important to me that users get a relatively consistent experience regardless of the client they choose to use, but still allowing those clients to express their unique features/competitive advantage to users. Clients should also have capacity to participate in different markets outside of chat.
The MSC also appears very nearly ready for FCP, with only a few blocking comments from my side:
- The MSC could do with a bit stronger rationale for why this is important.
- The MSC appears to have a heavy focus on Element clients, which is natural given the authors.
- To help with the "why" of the MSC, "implementation" in the form of user research would help. Ideally from a broad spectrum of users and clients, demonstrating the terms chosen carry well between different markets, audiences, brands, etc.
| When communicating about cryptography with non-technical users, we propose using | ||
| the following terms and concepts. |
There was a problem hiding this comment.
The proposal body should be assertive language. Is this a MUST for client developers? What section of the spec would it fall under?
There was a problem hiding this comment.
Is this a MUST for client developers?
I don't think it can be a must: some clients will have very specific groups of users, who use different terms. I don't think we should put a specialised client into the position of being in violation of the spec just because they chose suitable terminology for their user base.
What section of the spec would it fall under?
The latest draft proposes that this should "Become an appendix in the spec".
| Clients may, of course, choose to use different language. Some clients may | ||
| deliberately choose to use more technical language, to suit the profiles of | ||
| their users. This document is aimed at clients targeting non-technical users. |
There was a problem hiding this comment.
it's unclear if this is part of the proposal, or accepting fate. If it's part of the proposal, I suggest moving it down to the normative sections (under "Proposal").
There was a problem hiding this comment.
I wrote some words in 56b5daf - let me know what you think.
| When communicating about cryptography with non-technical users, we propose using | ||
| the following terms and concepts. | ||
|
|
||
| ### Devices |
There was a problem hiding this comment.
Has user research shown that devices are preferred over sessions? Does Element have some data on their existing transition from devices to sessions?
(comment from a product/design-orientated person would be appreciated)
proposals/4161-crypto-terminology.md
Outdated
| Devices which have not been cross-signed by the user are considered an error | ||
| state, primarily to be encountered during the transition to MSC4153 and/or due | ||
| to buggy/incomplete/outdated clients. These devices are referred to as **not | ||
| secure** and presence of them are considered a serious and dangerous error | ||
| condition, similar to an invalid TLS certificate. |
There was a problem hiding this comment.
this appears to extend beyond definition and into specification. Is there existing spec which describes the 'error state'? Should we explore the concepts of error and security through another MSC?
There was a problem hiding this comment.
Implementation requirements (in my opinion):
- User research to show these terms as helpful and easily understood.
The research may be done through studies or deployment to a portion of the user base with analytics to show "easier" use of the app.
| in the spec as the | ||
| [secret storage key](https://spec.matrix.org/v1.8/client-server-api/#secret-storage). | ||
|
|
||
| ## Potential issues |
There was a problem hiding this comment.
The MSC should address why it's important that all clients use the same language, and why the language of the MSC is generic enough to fit the language and feel of all client applications. An app which has a less professional feel may prefer to use different terms for brand identity/recognition, for example. This MSC feels a bit too prescriptive for all audiences.
A common language feels important to me, regardless of audience impact, but the MSC does not really tell me why I should feel that way.
There was a problem hiding this comment.
Overall review: The MSC appears to describe features and requirements of Element, and assumes that all clients in the ecosystem have similar or comparable features/needs. The assumptions read fine when applying this MSC to an Element client, but when comparing to the spec there feels like there's a gap in understanding.
Significant review from other client authors/developers, and their respective product/design teams, I think would be extremely valuable to help ensure this MSC does not solely apply to Element. This kind of review may need to be chased down as it's somewhat uncommon for a product-y MSC to be in the spec process.
| and is particularly used to describe messages that are stored on the server | ||
| rather than your device(s) | ||
|
|
||
| ### Key storage |
There was a problem hiding this comment.
I would call this "Secret storage".
The mechanism in question can store arbitrary data, not all of which are keys. The next paragraph already has to perform significant linguistic gymnastics in order to explain that the user's identity is also stored in the key storage, even though it is called an identity, not a key. (The fact that it is a key is an unimportant technical detail from a user perspective and is very jargony.)
On the other hand, explaining that a key is a certain type of secret should be very natural.
There was a problem hiding this comment.
I would call this "Secret storage".
We discussed this. The challenge we see is that it could be mixed up. It could either mean
- a storage for secrets
- a storage that is secret
That's why we discarded it and propose "Key storage". For a user it is irrelevant if something is a secret or a key or a token or a hash or whatnot, technically speaking. From a users point of view it should be a safe place that holds keys to open up stuff on new devices or in case of an emergency.
There was a problem hiding this comment.
Also, the problem will be further exacerbated if/when new non-key things start getting stored in secret storage.
There was a problem hiding this comment.
We discussed this. The challenge we see is that it could be mixed up. It could either mean
a storage for secrets
a storage that is secret
Wouldn't "Secrets storage" fix that problem?
There was a problem hiding this comment.
"Secrets storage" is feels unnatural to say in English. The justification for "key storage" is that the most important things (from a non-technical user's point of view) that are stored in this storage are message keys.
The fact that other things also get stored there doesn't need to prevent us naming it after the most important thing. For example, if I have a school locker for P.E. kit that I commonly call a "kit locker" I think it would be perfectly natural for me to say "I keep my Sony Walkman and Rubik's cube in my kit locker"...
There was a problem hiding this comment.
The fact that other things also get stored there doesn't need to prevent us naming it after the most important thing
It doesn't need to, but I think it should, considering that the whole point of this exercise is to make the language used less confusing.
Co-authored-by: Travis Ralston <[email protected]>
Co-authored-by: Travis Ralston <[email protected]>
|
|
||
| **Key storage** means keeping cryptographic information on the server. This | ||
| includes the user's cryptographic identity, and/or the message keys needed to | ||
| decrypt messages. |
There was a problem hiding this comment.
I want to split this into 2 separate concepts: I thought we could run storage of message keys together with storage of identity keys etc (recovery) but recently I realised they a really separate, so we probably need something like this:
- Room key storage - store
roommessage keys on the server, protected by aroommessage key storage key. Thisroommessage key storage key can be passed around between devices even if you don't have recovery storage. - Recovery storage - store identity keys and the
roommessage key storage key on the server, protected by a recovery code. This allows us to recover both our identity and ourroommessage key storage key even if we lose all our devices.
There was a problem hiding this comment.
It's worth noting that the EX designs (https://www.figma.com/design/qTWRfItpO3RdCjnTKPu4mL/Settings?node-id=1653-29941&node-type=frame&t=LeUe8iJVmzG8srM5-0 etc) refer to "key storage" to cover both of these concepts. I think that's ok; we just need to be clear that "key storage" is used for both room keys and recovery, and that they are set up separately.
There was a problem hiding this comment.
Room key storage - store room keys on the server, protected by a room key storage key.
NB they are message keys, not room keys.
There was a problem hiding this comment.
IMO it would be great if we could abstract the details to the user. It should just be one feature from a user POV. Either you want the server to store some information for you and get benefits from it or you don't. I don't see a reason why the user should need to understand the exact concepts behind it.
There was a problem hiding this comment.
Well, it would be quite a change from the way the apps currently work. Currently EX sets up key backup on registration, but doesn't set up recovery until you actively go through the steps (and EW is even more flexible). That's also why the designs above have separate entries for "Allow key storage" and "set up recovery".
Possibly we could change that, and force the user to set up recovery during the registration/login flow; but it would go against the desire to get people using the app quickly. (Also, this MSC is intended to cover matrix clients in general: even if the Element clients force you to set up recovery at the same time as key backup, other clients may not, and having the terminology available to refer to that situation is important.)
| ### Recovery key (and recovery passphrase) | ||
|
|
||
| A **recovery key** is a way of regaining access to key storage if the user loses | ||
| all their devices. Using key storage, they can preserve their cryptographic |
There was a problem hiding this comment.
For the record, Beeper settled on "recovery code" after considering other options including "recovery key", but I don't remember the exact reasoning since the switch was made 2 years ago
There was a problem hiding this comment.
Asked for the reasoning internally:
Code sounded more friendly than key (in an unscientific review).
e.g. people know what a pin code is. Code is a numerical thing but a 'key' to most people is a physical object
| proof that you have a secure communication channel with them. | ||
|
|
||
| > "Warning: Alice's identity appears to have changed" (when a non-verified | ||
| > user resets their recovery key) |
There was a problem hiding this comment.
We have been trialing the "appears to have changed" wording in Element clients, and it is not popular at all, because it suggest we are unsure what has happened.
The intention of the wording was to make clear that although we are sure that the cryptographic identity has changed, we can't be sure whether this is because the real person did a reset, or some malicious actor is impersonating them.
But this is clearly not working, and we need to work on different wording.
There was a problem hiding this comment.
I wonder whether "Alice's identity has changed: there is a chance someone took over their account - to be sure, you should verify their identity in their profile" or something else action-orientated would be helpful.
There was a problem hiding this comment.
I think the chances that someone took over the account are in practice very low, and it is alarming to say it up-front. I'd go with Alice probably re-installed the app and lost her recovery key, you can always verifiy to ensure the identity is legitimate
There was a problem hiding this comment.
+1 to "Alice's identity has changed". I think most people will get that. Especially if we can couple it with "there is a chance someone took over their account".
There was a problem hiding this comment.
Why not roughly copy what other messengers do?
Alice's identity has changed. [This can happen if the user lost all their devices and the recovery key, but it can also be a sign of someone taking over the account].
Clients are suggested to always display something to the effect of the first sentence. The rest (what's in the brackets) should be available but can be hidden behind a "Tap for more info." interaction or similar.
There was a problem hiding this comment.
+1 to "Alice's identity has changed." I do think we should be action-focused too, though, so: "Please verify them".
There was a problem hiding this comment.
Note that this thread is specifically about the non-verified case. It makes sense to mention verification but probably in a non-binding way. I still think there is room for a short single sentence explanation of why this happened, especially if hidden behind an interaction.
| ⚠️ Be aware that at time of writing the spec uses | ||
| ["recovery key"](https://spec.matrix.org/v1.8/client-server-api/#recovery-key) | ||
| to refer to the private half of the backup encryption key, which is different | ||
| from the usage here. The recovery key described in this section is referred to |
There was a problem hiding this comment.
This got fixed in matrix-org/matrix-spec#1819
| state, primarily to be encountered during the transition to MSC4153 and/or due | ||
| to buggy/incomplete/outdated clients. These devices are referred to as **not | ||
| secure** or **insecure** and their existence is considered a serious and dangerous error | ||
| condition, similar to an invalid TLS certificate. |
There was a problem hiding this comment.
Proposed new wording: "Encryption login" - your device is insecure because you have not completed the encryption login.
There was a problem hiding this comment.
Mock-up of how this might be communicated to user.
(clip-art credit: https://openclipart.org/detail/183969/computer-network-icons )
There was a problem hiding this comment.
Hmm, lots of push-back on this wording in our team, but we like the diagram.
We are playing around with something like "verify it's you".
Rendered
Conflict of Interest declaration: I am employed by Element. This MSC was written as part of my work on the Element Cryptography team.