From 5f08ae9e48eb22d2457c86bc615d1058a4b1166f Mon Sep 17 00:00:00 2001 From: Andy Balaam Date: Thu, 27 Jun 2024 11:27:25 +0100 Subject: [PATCH 01/31] Initial commit for MSC4161: Crypto terminology for non-technical users --- proposals/4161-crypto-terminology.md | 1 + 1 file changed, 1 insertion(+) create mode 100644 proposals/4161-crypto-terminology.md diff --git a/proposals/4161-crypto-terminology.md b/proposals/4161-crypto-terminology.md new file mode 100644 index 00000000000..99628f7ea2d --- /dev/null +++ b/proposals/4161-crypto-terminology.md @@ -0,0 +1 @@ +# MSC4161: Crypto terminology for non-technical users From 32f386b79161c51e62f90d0cb5da28954520ee86 Mon Sep 17 00:00:00 2001 From: Andy Balaam Date: Thu, 27 Jun 2024 11:50:36 +0100 Subject: [PATCH 02/31] First draft --- proposals/4161-crypto-terminology.md | 275 +++++++++++++++++++++++++++ 1 file changed, 275 insertions(+) diff --git a/proposals/4161-crypto-terminology.md b/proposals/4161-crypto-terminology.md index 99628f7ea2d..70dddda7007 100644 --- a/proposals/4161-crypto-terminology.md +++ b/proposals/4161-crypto-terminology.md @@ -1 +1,276 @@ # MSC4161: Crypto terminology for non-technical users + +## Background + +Matrix makes use of advanced cryptographic techniques to provide secure +messaging. These techniques often involve precise and detailed language that is +unfamiliar to non-technical users. + +This document provides a list of concepts and explanations that are intended to +be suitable for use in Matrix clients that are aimed at non-technical users. + +Ideally, encryption in Matrix should be entirely invisible to end-users (much as +WhatsApp or Signal users are not exposed to encryption specifics) - as outlined +in [MSC4153](https://github.com/matrix-org/matrix-spec-proposals/pull/4153). +However, consistent terminology is still required, especially during the +transition period to Invisible Cryptography. + +## Goals + +We hope that Matrix client developers will like the terms and wording we +provide, and adapt their user interfaces and documentation to use them. (If this +MSC is accepted, Element will use it as a reference for English wording in its +clients.) + +Where concepts and terms exactly match existing terms in the Matrix spec, we +propose changing the spec to use the terms from this document. Where they do not +match, we are very comfortable with different words being used in the spec, +given it is a highly technical document, as opposed to a client user interface. + +We hope that this MSC will: + +* Cause small changes in the spec (as described in the previous paragraph), and +* Become a document, blessed by the spec core team and available on the spec web + site, but probably separate from the spec proper. + +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. + +Where changes are made in the spec, we suggest that notes be added mentioning +the old name, as in [this +example](https://github.com/matrix-org/matrix-spec/pull/1819/files#diff-8b25d378e077f18eb06ebdb9c376e194c8a4c8b95cf909fca6448659a627f283R1326). + +## Proposal + +When communicating about cryptography with non-technical users, we propose using +the following terms and concepts. + +### Devices + +Instances of a client are called 'devices' (not 'sessions'). Aligned with +MSC4153, we take it as granted that all devices have been cross-signed by the +user who owns them, and we call these **devices**. + +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. + +> "This device is not secure. Please verify it to continue." + +> "Ignoring 5 messages that were sent from a device that is not secure." + +> "Confim it's you" (when asking to verify a device during login) + +⚠️ Avoid saying "secure device". All devices are considered secure by default; +the user doesn't typically need to worry about the fact that insecure devices +are a thing, given they should only ever occur in error (or transitional) +scenarios. + +⚠️ Avoid saying "trusted device" or "verified device". Devices are not people, +and it is helpful to use different language for people vs. devices. (However, we +do use the verb "verify" to describe how to make a device secure. By using the +same verb, we help users understand the confusing fact that verifying devices +and verifying people are similar processes, but with different outcomes.) + +⚠️ Avoid using "cross-signing", which requires a deeper understanding of +cryptography to understand. + +⚠️ Avoid mentioning "device keys" - a device is just secure or not. + +⚠️ Avoid "session" to mean device. Device better describes what most people +encounter, and is more commonly used in other products. + +### Verified person + +When you verify a person they become **verified**. This means that you have +cryptographic proof that no-one is listening in on your conversations. (You need +this if you suspect someone in a room may be using a malicious homeserver.) + +In many contexts, most people are **not verified**: verification is a manual +step (scanning a QR code or comparing emojis). (In future, verification will +probably become more common thanks to "transitive trust" or "key transparency"). +When an unverified person resets their cryptographic identity, we should warn +the user, so they are aware of the change. + +If a verified person's cryptographic identity changes (i.e. they reset their +recovery key) then this is very important: we verified them because we care +about proof that no-one is listening, and now someone could be. The user can +choose to **withdraw verification** (i.e. "demote" them from being verified), or +**re-verify** them. Until they do one or the other, communication with them should +contain a prominent and serious warning that the user's **verified identity has +changed**. + +> "This person is verified." + +> "WARNING: Bob's verified identity has changed!" + +> "You verified this person's identity, but it has changed. Please choose to +> re-verify them or withdraw verification." + +⚠️ Avoid using "cross-signing", which requires a deeper understanding of +cryptography to understand. + +⚠️ Avoid using "trust on first use (TOFU)", which is a colloquial name for noting +the identity of people who are not verified so that we can notify the user if it +changes. (This is a kind of "light" form of verification where we assume that +the first identity we can see is trusted.) + +⚠️ Avoid confusing verification of people with verification of devices: the +mechanism is similar but the purpose is different. Devices must be verified to +make them secure, but people can optionally be verified to ensure no-one is +listening in or tampering with communications. + +⚠️ Avoid talking about "mismatch" or "verification mismatch" which is very +jargony - it is the identity which is mismatched, not the verification process. +Just say "Bob's verified identity has changed". + +⚠️ Avoid talking about "cryptographic identity" which is very jargony. Just call +it "identity" where possible - i.e. the non-technical dictionary definition of +identity such that someone is who they claim they are, not someone else. The +fact we confirm identity cryptographically is irrelevant to the user; +cryptography should be invisible. + +### Identity + +A person's **identity** is proof of who they are, and, if they are verified, +proof that you have a secure communication channel with them. + +> "Warning: Alice's identity appears to have changed" (when a non-verified +> person resets their recovery key) + +> "WARNING: Bob's verified identity has changed!" (when a verified person resets +> their recovery key) + +(During login, at the "Confirm it's you" stage): + +> "If you don't have any other device and you have lost your recovery key, you +> can create a new identity. (Warning: you will lose access to your old +> messages!)" button text (in red or similar): "Reset my identity" + +⚠️ Avoid saying "master key" - this is an implementation detail. + +⚠️ Avoid saying "reset their encryption" - the reason that Alice's identity +changes could be due to attack rather than because they reset their encryption +(plus "encryption" is jargony). + +### Message key + +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. + +> "Store message keys on the server." + +> "This message could not be decrypted because its key is missing." + +⚠️ Avoid saying "key" without a previous word saying what type of key it is. + +⚠️ Avoid using "room key". These keys are used to decrypt messages, not rooms. + +Note: this clashes with the term "message key" in the double ratchet. Since the +double ratchet algorithm is for a very different audience, we think that this is +not a problem. + +### Message history + +Your **message history** is a record of every message you have received or sent, +and is particularly used to describe messages that are stored on the server +rather than your device(s) + +###Key storage + +**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. + +If a user loses their recovery key, they may **reset** their key storage. Unless +they have old devices, they will not be able to access old encrypted messages +because the message keys are stored in key storage, and their cryptographic +identity will change, because it too is stored in key storage. + +> "Allow key storage" + +> "Key storage holds your cryptographic identity on the server along with the +> keys that allow you to read your message history." + +⚠️ Avoid distinguishing between "secret storage" and "key backup" - these are +both part of key storage. + +⚠️ Avoid talking about more keys: "the backup key is stored in the secret +storage, and this allows us to decrypt the messages keys from key backup". +Instead, we simply say that both cryptographic identity and message keys are +stored in key storage. + +⚠️ Avoid using "key backup" to talk about storing message keys: keeping things on +the server is not a "backup", but a reliable, cross-device place where this +information is stored. The word "backup" implies a redundant way to recover lost +information, but if the user loses their recovery key, this information is lost. +Clients and servers may wish to offer additional backup services that provide +true redundancy and disaster recovery, but key storage is not this. + +⚠️ Avoid "4S" or "quad-S" - these are not descriptive terms. + +⚠️ Avoid "private key" - this is an implementation detail and a term with +specific meaning from cryptography. + +### 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 +identity (meaning other people don't see "Alice has reset their encryption" +messages), and also read old messages using the stored message keys. + +A **recovery passphrase** is an easier-to-remember way of accessing the recovery +key and has the same purpose as the recovery key. + +> "Write down your recovery key in a safe place" + +> "If you lose access to your devices and your recovery key, you will need to +> reset your key storage, which will create a new identity" + +> "If you lose your recovery key you can generate a new one if you are signed in +> elsewhere" + +⚠️ Avoid using "security key", "security code", "recovery code", "master key". A +recovery key allows "unlocking" the key storage, which is a "box" that is on the +server, containing your cryptographic identity and message keys. It is used to +recover the situation if you lose access to your devices. None of these other +terms express this concept so clearly. + +⚠️ Remember that users may have historically been trained to refer to these +concepts as "security key" or "security passphrase", and so user interfaces +should provide a way for users to be educated on the terminology change (e.g. a +tooltip or help link): e.g. "Your recovery key may also have been referred to as +a security key in the past" + +## Potential issues + +Lots of existing clients use a whole variety of different terminology, and many +users are familiar with different terms. Nevertheless we believe that working +together to agree on a common language is the only way to address this issue +over time. + +## Further work + +Several other concepts might benefit from similar treatment. Within +cryptography, "device dehydration" is a prime candidate. Outside cryptography, +many other terms could be agreed, including "export chat" (particularly in +contrast to "export message keys"). + +## Security considerations + +In order for good security practices to work, users need to understand the +implications of their actions, so this MSC should be reviewed by security +experts to ensure it is not misleading. + +## Dependencies + +None + +## Credits + +Written by Andy Balaam, Aaron Thornburgh and Patrick Maier as part of our work +for Element. Richard van der Hoff, Matthew Hodgson and Denis Kasak contributed +many improvements before the first draft was published. From cd26b70a4e4be5da3f0cbcfe7e2ce48c36847e64 Mon Sep 17 00:00:00 2001 From: Andy Balaam Date: Thu, 27 Jun 2024 13:07:22 +0100 Subject: [PATCH 03/31] Fix typo --- proposals/4161-crypto-terminology.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/4161-crypto-terminology.md b/proposals/4161-crypto-terminology.md index 70dddda7007..84a69a95b97 100644 --- a/proposals/4161-crypto-terminology.md +++ b/proposals/4161-crypto-terminology.md @@ -62,7 +62,7 @@ condition, similar to an invalid TLS certificate. > "Ignoring 5 messages that were sent from a device that is not secure." -> "Confim it's you" (when asking to verify a device during login) +> "Confirm it's you" (when asking to verify a device during login) ⚠️ Avoid saying "secure device". All devices are considered secure by default; the user doesn't typically need to worry about the fact that insecure devices From a7b5a77e1e100fa393e412459df32916e958d593 Mon Sep 17 00:00:00 2001 From: Andy Balaam Date: Thu, 27 Jun 2024 13:13:38 +0100 Subject: [PATCH 04/31] Fix mis-formatted heading --- proposals/4161-crypto-terminology.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/4161-crypto-terminology.md b/proposals/4161-crypto-terminology.md index 84a69a95b97..19e664e9057 100644 --- a/proposals/4161-crypto-terminology.md +++ b/proposals/4161-crypto-terminology.md @@ -179,7 +179,7 @@ Your **message history** is a record of every message you have received or sent, and is particularly used to describe messages that are stored on the server rather than your device(s) -###Key storage +### Key storage **Key storage** means keeping cryptographic information on the server. This includes the user's cryptographic identity, and/or the message keys needed to From a79b289d8e273ed78c781fc0d73e57c1592c257f Mon Sep 17 00:00:00 2001 From: Andy Balaam Date: Thu, 27 Jun 2024 13:15:31 +0100 Subject: [PATCH 05/31] Fix incorrect bolding --- proposals/4161-crypto-terminology.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/4161-crypto-terminology.md b/proposals/4161-crypto-terminology.md index 19e664e9057..050d7de45fc 100644 --- a/proposals/4161-crypto-terminology.md +++ b/proposals/4161-crypto-terminology.md @@ -217,7 +217,7 @@ specific meaning from cryptography. ### Recovery key (and recovery passphrase) -A **recovery** key is a way of regaining access to key storage if the user loses +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 identity (meaning other people don't see "Alice has reset their encryption" messages), and also read old messages using the stored message keys. From 89412ccc00b4a548ddc5e608eba0d0124de0b212 Mon Sep 17 00:00:00 2001 From: Andy Balaam Date: Thu, 27 Jun 2024 13:16:49 +0100 Subject: [PATCH 06/31] Ensure we are consistently saying Alice's identity appears to have changed --- proposals/4161-crypto-terminology.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/proposals/4161-crypto-terminology.md b/proposals/4161-crypto-terminology.md index 050d7de45fc..a8b82d32bb5 100644 --- a/proposals/4161-crypto-terminology.md +++ b/proposals/4161-crypto-terminology.md @@ -219,8 +219,8 @@ specific meaning from cryptography. 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 -identity (meaning other people don't see "Alice has reset their encryption" -messages), and also read old messages using the stored message keys. +identity (meaning other people don't see "Alice's identity appears to have +changed" messages), and also read old messages using the stored message keys. A **recovery passphrase** is an easier-to-remember way of accessing the recovery key and has the same purpose as the recovery key. From d15576e8cd309a0e16175bc67ca752cb89545b17 Mon Sep 17 00:00:00 2001 From: Andy Balaam Date: Thu, 5 Sep 2024 10:58:40 +0100 Subject: [PATCH 07/31] Add another example for key storage --- proposals/4161-crypto-terminology.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/proposals/4161-crypto-terminology.md b/proposals/4161-crypto-terminology.md index a8b82d32bb5..29d82468122 100644 --- a/proposals/4161-crypto-terminology.md +++ b/proposals/4161-crypto-terminology.md @@ -195,6 +195,8 @@ identity will change, because it too is stored in key storage. > "Key storage holds your cryptographic identity on the server along with the > keys that allow you to read your message history." +> "Message history is unavailable because key storage is disabled." + ⚠️ Avoid distinguishing between "secret storage" and "key backup" - these are both part of key storage. From af70e439bda45331804f39973886c5fd92c68a44 Mon Sep 17 00:00:00 2001 From: Andy Balaam Date: Thu, 5 Sep 2024 13:40:52 +0100 Subject: [PATCH 08/31] Link to MSC4153 where we mention it. Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> --- proposals/4161-crypto-terminology.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/4161-crypto-terminology.md b/proposals/4161-crypto-terminology.md index 29d82468122..8c8712df4b5 100644 --- a/proposals/4161-crypto-terminology.md +++ b/proposals/4161-crypto-terminology.md @@ -49,7 +49,7 @@ the following terms and concepts. ### Devices Instances of a client are called 'devices' (not 'sessions'). Aligned with -MSC4153, we take it as granted that all devices have been cross-signed by the +[MSC4153](https://github.com/matrix-org/matrix-spec-proposals/pull/4153), we take it as granted that all devices have been cross-signed by the user who owns them, and we call these **devices**. Devices which have not been cross-signed by the user are considered an error From 720cdeb1f9fa8f664392c829fb663616149970f2 Mon Sep 17 00:00:00 2001 From: Andy Balaam Date: Thu, 5 Sep 2024 13:41:56 +0100 Subject: [PATCH 09/31] Make the wording about resetting keys more precise. Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> --- proposals/4161-crypto-terminology.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/4161-crypto-terminology.md b/proposals/4161-crypto-terminology.md index 8c8712df4b5..9d3aaeaa8e9 100644 --- a/proposals/4161-crypto-terminology.md +++ b/proposals/4161-crypto-terminology.md @@ -96,7 +96,7 @@ When an unverified person resets their cryptographic identity, we should warn the user, so they are aware of the change. If a verified person's cryptographic identity changes (i.e. they reset their -recovery key) then this is very important: we verified them because we care +master cross-signing key) then this is very important: we verified them because we care about proof that no-one is listening, and now someone could be. The user can choose to **withdraw verification** (i.e. "demote" them from being verified), or **re-verify** them. Until they do one or the other, communication with them should From de285aa0525cc8e9410b52fab88216ce7889e75d Mon Sep 17 00:00:00 2001 From: Andy Balaam Date: Thu, 5 Sep 2024 13:50:01 +0100 Subject: [PATCH 10/31] Re-word the paragraph about the importance of verified identity changes to use Alice and Bob --- proposals/4161-crypto-terminology.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/proposals/4161-crypto-terminology.md b/proposals/4161-crypto-terminology.md index 9d3aaeaa8e9..8be22dfe69b 100644 --- a/proposals/4161-crypto-terminology.md +++ b/proposals/4161-crypto-terminology.md @@ -95,13 +95,13 @@ probably become more common thanks to "transitive trust" or "key transparency"). When an unverified person resets their cryptographic identity, we should warn the user, so they are aware of the change. -If a verified person's cryptographic identity changes (i.e. they reset their -master cross-signing key) then this is very important: we verified them because we care -about proof that no-one is listening, and now someone could be. The user can -choose to **withdraw verification** (i.e. "demote" them from being verified), or -**re-verify** them. Until they do one or the other, communication with them should -contain a prominent and serious warning that the user's **verified identity has -changed**. +If Alice is verified with Bob, and then Alice's cryptographic identity changes +(i.e. Alice reset their master cross-signing key) then this is very important to +Bob: Bob verified Alice because they care about proof that no-one is listening, +and now someone could be. Bob can choose to **withdraw verification** (i.e. +"demote" Alice from being verified), or **re-verify** with Alice. Until Bob does +one or the other, Bob's communication with Alice should contain a prominent and +serious warning that Alice's **verified identity has changed**. > "This person is verified." From 57fc5c1a80d7686cb84ad969364eb2a4271390d2 Mon Sep 17 00:00:00 2001 From: Andy Balaam Date: Thu, 5 Sep 2024 16:52:21 +0100 Subject: [PATCH 11/31] Link to the spec equivalent wording for our recovery key --- proposals/4161-crypto-terminology.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/proposals/4161-crypto-terminology.md b/proposals/4161-crypto-terminology.md index 8be22dfe69b..ba5e3403c39 100644 --- a/proposals/4161-crypto-terminology.md +++ b/proposals/4161-crypto-terminology.md @@ -247,6 +247,13 @@ should provide a way for users to be educated on the terminology change (e.g. a tooltip or help link): e.g. "Your recovery key may also have been referred to as a security key in the past" +⚠️ 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 +in the spec as the +[secret storage key](https://spec.matrix.org/v1.8/client-server-api/#secret-storage). + ## Potential issues Lots of existing clients use a whole variety of different terminology, and many From a4b95b46d69c20dd230314c6085081ecdeb157ae Mon Sep 17 00:00:00 2001 From: Andy Balaam Date: Thu, 5 Sep 2024 16:53:08 +0100 Subject: [PATCH 12/31] Re-word the paragraph about Invisible Crypto --- proposals/4161-crypto-terminology.md | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/proposals/4161-crypto-terminology.md b/proposals/4161-crypto-terminology.md index ba5e3403c39..028b0363470 100644 --- a/proposals/4161-crypto-terminology.md +++ b/proposals/4161-crypto-terminology.md @@ -10,10 +10,16 @@ This document provides a list of concepts and explanations that are intended to be suitable for use in Matrix clients that are aimed at non-technical users. Ideally, encryption in Matrix should be entirely invisible to end-users (much as -WhatsApp or Signal users are not exposed to encryption specifics) - as outlined -in [MSC4153](https://github.com/matrix-org/matrix-spec-proposals/pull/4153). -However, consistent terminology is still required, especially during the -transition period to Invisible Cryptography. +WhatsApp or Signal users are not exposed to encryption specifics). This +initiative is referred to as "Invisible Cryptography" and is tracked as: + +* [MSC4153](https://github.com/matrix-org/matrix-spec-proposals/pull/4153) - + Exclude non-cross-signed devices, +* [MSC4048](https://github.com/matrix-org/matrix-spec-proposals/pull/4048) - + Authenticated key backup, +* [MSC4147](https://github.com/matrix-org/matrix-spec-proposals/pull/4147) - + Including device keys with Olm-encrypted events, and +* MSC4161 - this document ## Goals From 0499900abe6aaa45f57b160ce39dc543cd2339dc Mon Sep 17 00:00:00 2001 From: Andy Balaam Date: Fri, 6 Sep 2024 10:32:44 +0100 Subject: [PATCH 13/31] Propose being an appendix to the spec --- proposals/4161-crypto-terminology.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/proposals/4161-crypto-terminology.md b/proposals/4161-crypto-terminology.md index 028b0363470..98667f5cee1 100644 --- a/proposals/4161-crypto-terminology.md +++ b/proposals/4161-crypto-terminology.md @@ -36,8 +36,9 @@ given it is a highly technical document, as opposed to a client user interface. We hope that this MSC will: * Cause small changes in the spec (as described in the previous paragraph), and -* Become a document, blessed by the spec core team and available on the spec web - site, but probably separate from the spec proper. +* Become an appendix in the spec, with a description that makes clear that the + intended audience is different from most of the spec, meaning different words + are used from the main spec body. Clients may, of course, choose to use different language. Some clients may deliberately choose to use more technical language, to suit the profiles of From b919630cfbcaf95e83a400b8cec1fa4009e72a3d Mon Sep 17 00:00:00 2001 From: Andy Balaam Date: Fri, 6 Sep 2024 11:36:37 +0100 Subject: [PATCH 14/31] Add a section on what to say when a message can't be decrypted --- proposals/4161-crypto-terminology.md | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/proposals/4161-crypto-terminology.md b/proposals/4161-crypto-terminology.md index 98667f5cee1..3c1fcc43f80 100644 --- a/proposals/4161-crypto-terminology.md +++ b/proposals/4161-crypto-terminology.md @@ -180,6 +180,26 @@ Note: this clashes with the term "message key" in the double ratchet. Since the double ratchet algorithm is for a very different audience, we think that this is not a problem. +### Unable to decrypt + +When we have an encrypted message but no message key to decrypt it, we are +unable to decrypt it. + +When we expect the key to arrive, we are **waiting for this message**. + +> "Waiting for this message" button: "learn more" which explains that the key to +> decrypt this message has not yet been received, but that we expect it to +> arrive shortly. Further detail may be provided, for instance explaining that +> connectivity issues between the sender's homeserver and our own can cause +> key delivery delays. + +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. + ### Message history Your **message history** is a record of every message you have received or sent, From 007a15f43b73144b3338d4c243aac2d6d9853099 Mon Sep 17 00:00:00 2001 From: Andy Balaam Date: Fri, 6 Sep 2024 11:44:53 +0100 Subject: [PATCH 15/31] Add a missing 's' --- proposals/4161-crypto-terminology.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/4161-crypto-terminology.md b/proposals/4161-crypto-terminology.md index 3c1fcc43f80..d434dc200f6 100644 --- a/proposals/4161-crypto-terminology.md +++ b/proposals/4161-crypto-terminology.md @@ -103,7 +103,7 @@ When an unverified person resets their cryptographic identity, we should warn the user, so they are aware of the change. If Alice is verified with Bob, and then Alice's cryptographic identity changes -(i.e. Alice reset their master cross-signing key) then this is very important to +(i.e. Alice resets their master cross-signing key) then this is very important to Bob: Bob verified Alice because they care about proof that no-one is listening, and now someone could be. Bob can choose to **withdraw verification** (i.e. "demote" Alice from being verified), or **re-verify** with Alice. Until Bob does From 45928bb05373d58c09df481d029a360bf3b447f0 Mon Sep 17 00:00:00 2001 From: Andy Balaam Date: Fri, 6 Sep 2024 11:47:22 +0100 Subject: [PATCH 16/31] changes->changed --- proposals/4161-crypto-terminology.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/4161-crypto-terminology.md b/proposals/4161-crypto-terminology.md index d434dc200f6..51899896307 100644 --- a/proposals/4161-crypto-terminology.md +++ b/proposals/4161-crypto-terminology.md @@ -160,7 +160,7 @@ proof that you have a secure communication channel with them. ⚠️ Avoid saying "master key" - this is an implementation detail. ⚠️ Avoid saying "reset their encryption" - the reason that Alice's identity -changes could be due to attack rather than because they reset their encryption +changed could be due to attack rather than because they reset their encryption (plus "encryption" is jargony). ### Message key From 3a2d012fe8f013bfed1349f5cab425fcc3d8591b Mon Sep 17 00:00:00 2001 From: Andy Balaam Date: Fri, 6 Sep 2024 11:48:54 +0100 Subject: [PATCH 17/31] Remove erroneous UTD message --- proposals/4161-crypto-terminology.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/proposals/4161-crypto-terminology.md b/proposals/4161-crypto-terminology.md index 51899896307..f23166a7b65 100644 --- a/proposals/4161-crypto-terminology.md +++ b/proposals/4161-crypto-terminology.md @@ -170,8 +170,6 @@ are "locked in a box" by encrypting them, and "unlocked" by decrypting them. > "Store message keys on the server." -> "This message could not be decrypted because its key is missing." - ⚠️ Avoid saying "key" without a previous word saying what type of key it is. ⚠️ Avoid using "room key". These keys are used to decrypt messages, not rooms. @@ -187,7 +185,7 @@ unable to decrypt it. When we expect the key to arrive, we are **waiting for this message**. -> "Waiting for this message" button: "learn more" which explains that the key to +> "Waiting for this message" with a button: "learn more" that explains that the key to > decrypt this message has not yet been received, but that we expect it to > arrive shortly. Further detail may be provided, for instance explaining that > connectivity issues between the sender's homeserver and our own can cause From 56b5daf17585e23e8b0f62dfa95abf07f12bf30e Mon Sep 17 00:00:00 2001 From: Andy Balaam Date: Mon, 7 Oct 2024 13:36:00 +0100 Subject: [PATCH 18/31] Mention that clients SHOULD follow this guide and document any exceptions --- proposals/4161-crypto-terminology.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/proposals/4161-crypto-terminology.md b/proposals/4161-crypto-terminology.md index f23166a7b65..2bc629ca3f6 100644 --- a/proposals/4161-crypto-terminology.md +++ b/proposals/4161-crypto-terminology.md @@ -53,6 +53,11 @@ example](https://github.com/matrix-org/matrix-spec/pull/1819/files#diff-8b25d378 When communicating about cryptography with non-technical users, we propose using the following terms and concepts. +When referring to concepts outlined in this document in their user interface, +clients SHOULD use the language specified, except where their own users are +known to understand different terms more easily. When making such exceptions, +clients SHOULD document how they deviate from this document, and why. + ### Devices Instances of a client are called 'devices' (not 'sessions'). Aligned with From fba4f5caf291af0a31e1aa2ea90343a7c5f4796b Mon Sep 17 00:00:00 2001 From: Andy Balaam Date: Mon, 7 Oct 2024 13:39:01 +0100 Subject: [PATCH 19/31] person->user --- proposals/4161-crypto-terminology.md | 34 ++++++++++++++-------------- 1 file changed, 17 insertions(+), 17 deletions(-) diff --git a/proposals/4161-crypto-terminology.md b/proposals/4161-crypto-terminology.md index 2bc629ca3f6..e7c680cd96e 100644 --- a/proposals/4161-crypto-terminology.md +++ b/proposals/4161-crypto-terminology.md @@ -81,30 +81,30 @@ the user doesn't typically need to worry about the fact that insecure devices are a thing, given they should only ever occur in error (or transitional) scenarios. -⚠️ Avoid saying "trusted device" or "verified device". Devices are not people, -and it is helpful to use different language for people vs. devices. (However, we +⚠️ Avoid saying "trusted device" or "verified device". Devices are not users, +and it is helpful to use different language for users vs. devices. (However, we do use the verb "verify" to describe how to make a device secure. By using the same verb, we help users understand the confusing fact that verifying devices -and verifying people are similar processes, but with different outcomes.) +and verifying users are similar processes, but with different outcomes.) ⚠️ Avoid using "cross-signing", which requires a deeper understanding of cryptography to understand. ⚠️ Avoid mentioning "device keys" - a device is just secure or not. -⚠️ Avoid "session" to mean device. Device better describes what most people +⚠️ Avoid "session" to mean device. Device better describes what most users encounter, and is more commonly used in other products. -### Verified person +### Verified user -When you verify a person they become **verified**. This means that you have +When you verify a user they become **verified**. This means that you have cryptographic proof that no-one is listening in on your conversations. (You need this if you suspect someone in a room may be using a malicious homeserver.) -In many contexts, most people are **not verified**: verification is a manual +In many contexts, most users are **not verified**: verification is a manual step (scanning a QR code or comparing emojis). (In future, verification will probably become more common thanks to "transitive trust" or "key transparency"). -When an unverified person resets their cryptographic identity, we should warn +When an unverified user resets their cryptographic identity, we should warn the user, so they are aware of the change. If Alice is verified with Bob, and then Alice's cryptographic identity changes @@ -115,24 +115,24 @@ and now someone could be. Bob can choose to **withdraw verification** (i.e. one or the other, Bob's communication with Alice should contain a prominent and serious warning that Alice's **verified identity has changed**. -> "This person is verified." +> "This user is verified." > "WARNING: Bob's verified identity has changed!" -> "You verified this person's identity, but it has changed. Please choose to +> "You verified this user's identity, but it has changed. Please choose to > re-verify them or withdraw verification." ⚠️ Avoid using "cross-signing", which requires a deeper understanding of cryptography to understand. ⚠️ Avoid using "trust on first use (TOFU)", which is a colloquial name for noting -the identity of people who are not verified so that we can notify the user if it +the identity of users who are not verified so that we can notify the user if it changes. (This is a kind of "light" form of verification where we assume that the first identity we can see is trusted.) -⚠️ Avoid confusing verification of people with verification of devices: the +⚠️ Avoid confusing verification of users with verification of devices: the mechanism is similar but the purpose is different. Devices must be verified to -make them secure, but people can optionally be verified to ensure no-one is +make them secure, but users can optionally be verified to ensure no-one is listening in or tampering with communications. ⚠️ Avoid talking about "mismatch" or "verification mismatch" which is very @@ -147,13 +147,13 @@ cryptography should be invisible. ### Identity -A person's **identity** is proof of who they are, and, if they are verified, +A user's **identity** is proof of who they are, and, if they are verified, proof that you have a secure communication channel with them. > "Warning: Alice's identity appears to have changed" (when a non-verified -> person resets their recovery key) +> user resets their recovery key) -> "WARNING: Bob's verified identity has changed!" (when a verified person resets +> "WARNING: Bob's verified identity has changed!" (when a verified user resets > their recovery key) (During login, at the "Confirm it's you" stage): @@ -251,7 +251,7 @@ specific meaning from cryptography. 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 -identity (meaning other people don't see "Alice's identity appears to have +identity (meaning other users don't see "Alice's identity appears to have changed" messages), and also read old messages using the stored message keys. A **recovery passphrase** is an easier-to-remember way of accessing the recovery From 9246021ee8b08735e9f08c454523d58ed9d0a309 Mon Sep 17 00:00:00 2001 From: Andy Balaam Date: Mon, 7 Oct 2024 13:40:03 +0100 Subject: [PATCH 20/31] Reword sentence on cross-signing --- proposals/4161-crypto-terminology.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/4161-crypto-terminology.md b/proposals/4161-crypto-terminology.md index e7c680cd96e..b97136dd077 100644 --- a/proposals/4161-crypto-terminology.md +++ b/proposals/4161-crypto-terminology.md @@ -87,7 +87,7 @@ do use the verb "verify" to describe how to make a device secure. By using the same verb, we help users understand the confusing fact that verifying devices and verifying users are similar processes, but with different outcomes.) -⚠️ Avoid using "cross-signing", which requires a deeper understanding of +⚠️ Avoid using "cross-signing", which requires a deeper knowledge of cryptography to understand. ⚠️ Avoid mentioning "device keys" - a device is just secure or not. From 0c9d81206b79d7bb94c52392fc4d839fa938d419 Mon Sep 17 00:00:00 2001 From: Andy Balaam Date: Mon, 7 Oct 2024 13:42:18 +0100 Subject: [PATCH 21/31] Re-word the "Waiting for this message" sentence Co-authored-by: Travis Ralston --- proposals/4161-crypto-terminology.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/proposals/4161-crypto-terminology.md b/proposals/4161-crypto-terminology.md index b97136dd077..8ac1e299a6a 100644 --- a/proposals/4161-crypto-terminology.md +++ b/proposals/4161-crypto-terminology.md @@ -190,8 +190,8 @@ unable to decrypt it. When we expect the key to arrive, we are **waiting for this message**. -> "Waiting for this message" with a button: "learn more" that explains that the key to -> decrypt this message has not yet been received, but that we expect it to +> "Waiting for this message" with a button: "learn more" that explains that the message key for +this message has not yet been received, but that we expect it to > arrive shortly. Further detail may be provided, for instance explaining that > connectivity issues between the sender's homeserver and our own can cause > key delivery delays. From 705f7bb4496a9f4b87fc6f634fb4494ab2567ed3 Mon Sep 17 00:00:00 2001 From: Andy Balaam Date: Mon, 7 Oct 2024 13:42:46 +0100 Subject: [PATCH 22/31] Add missing word "message" Co-authored-by: Travis Ralston --- proposals/4161-crypto-terminology.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/4161-crypto-terminology.md b/proposals/4161-crypto-terminology.md index 8ac1e299a6a..9bd55f959e1 100644 --- a/proposals/4161-crypto-terminology.md +++ b/proposals/4161-crypto-terminology.md @@ -260,7 +260,7 @@ key and has the same purpose as the recovery key. > "Write down your recovery key in a safe place" > "If you lose access to your devices and your recovery key, you will need to -> reset your key storage, which will create a new identity" +> reset your message key storage, which will create a new identity" > "If you lose your recovery key you can generate a new one if you are signed in > elsewhere" From 4bcee3308bd22e75b6eed67c3d2e0bab727a844c Mon Sep 17 00:00:00 2001 From: Andy Balaam Date: Mon, 7 Oct 2024 13:45:21 +0100 Subject: [PATCH 23/31] Remove unneeded 'private key' warning --- proposals/4161-crypto-terminology.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/proposals/4161-crypto-terminology.md b/proposals/4161-crypto-terminology.md index 9bd55f959e1..951f22495f0 100644 --- a/proposals/4161-crypto-terminology.md +++ b/proposals/4161-crypto-terminology.md @@ -244,9 +244,6 @@ true redundancy and disaster recovery, but key storage is not this. ⚠️ Avoid "4S" or "quad-S" - these are not descriptive terms. -⚠️ Avoid "private key" - this is an implementation detail and a term with -specific meaning from cryptography. - ### Recovery key (and recovery passphrase) A **recovery key** is a way of regaining access to key storage if the user loses From f654c2e6a88cebc7138946a3841b98d1d77628f5 Mon Sep 17 00:00:00 2001 From: Andy Balaam Date: Mon, 7 Oct 2024 13:48:05 +0100 Subject: [PATCH 24/31] Re-word 'key-backup' paragraph to contrast with export. --- proposals/4161-crypto-terminology.md | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/proposals/4161-crypto-terminology.md b/proposals/4161-crypto-terminology.md index 951f22495f0..e729cbbec47 100644 --- a/proposals/4161-crypto-terminology.md +++ b/proposals/4161-crypto-terminology.md @@ -235,12 +235,8 @@ storage, and this allows us to decrypt the messages keys from key backup". Instead, we simply say that both cryptographic identity and message keys are stored in key storage. -⚠️ Avoid using "key backup" to talk about storing message keys: keeping things on -the server is not a "backup", but a reliable, cross-device place where this -information is stored. The word "backup" implies a redundant way to recover lost -information, but if the user loses their recovery key, this information is lost. -Clients and servers may wish to offer additional backup services that provide -true redundancy and disaster recovery, but key storage is not this. +⚠️ Avoid using "key backup" to talk about storing message keys: this is too +easily confused with exporting keys or messages to an external system. ⚠️ Avoid "4S" or "quad-S" - these are not descriptive terms. From 3c7695f2592fdf0c28c2ee85b93022bab3dd5df7 Mon Sep 17 00:00:00 2001 From: Andy Balaam Date: Mon, 7 Oct 2024 13:54:22 +0100 Subject: [PATCH 25/31] Make clear that 'insecure device' is permitted --- proposals/4161-crypto-terminology.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/4161-crypto-terminology.md b/proposals/4161-crypto-terminology.md index e729cbbec47..eb47ae4f09c 100644 --- a/proposals/4161-crypto-terminology.md +++ b/proposals/4161-crypto-terminology.md @@ -67,7 +67,7 @@ user who owns them, and we call these **devices**. 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 +secure** or **insecure** and their existence is considered a serious and dangerous error condition, similar to an invalid TLS certificate. > "This device is not secure. Please verify it to continue." From 7a789c583b21880ee261155fb5ffc713ab42618a Mon Sep 17 00:00:00 2001 From: Andy Balaam Date: Tue, 17 Dec 2024 13:17:34 +0000 Subject: [PATCH 26/31] Remove 'cryptographic' before 'identity', and also tone down the warnings against this --- proposals/4161-crypto-terminology.md | 21 ++++++++++----------- 1 file changed, 10 insertions(+), 11 deletions(-) diff --git a/proposals/4161-crypto-terminology.md b/proposals/4161-crypto-terminology.md index eb47ae4f09c..0b1b0482434 100644 --- a/proposals/4161-crypto-terminology.md +++ b/proposals/4161-crypto-terminology.md @@ -104,10 +104,10 @@ this if you suspect someone in a room may be using a malicious homeserver.) In many contexts, most users are **not verified**: verification is a manual step (scanning a QR code or comparing emojis). (In future, verification will probably become more common thanks to "transitive trust" or "key transparency"). -When an unverified user resets their cryptographic identity, we should warn +When an unverified user resets their identity, we should warn the user, so they are aware of the change. -If Alice is verified with Bob, and then Alice's cryptographic identity changes +If Alice is verified with Bob, and then Alice's identity changes (i.e. Alice resets their master cross-signing key) then this is very important to Bob: Bob verified Alice because they care about proof that no-one is listening, and now someone could be. Bob can choose to **withdraw verification** (i.e. @@ -139,11 +139,10 @@ listening in or tampering with communications. jargony - it is the identity which is mismatched, not the verification process. Just say "Bob's verified identity has changed". -⚠️ Avoid talking about "cryptographic identity" which is very jargony. Just call -it "identity" where possible - i.e. the non-technical dictionary definition of -identity such that someone is who they claim they are, not someone else. The -fact we confirm identity cryptographically is irrelevant to the user; -cryptography should be invisible. +⚠️ Where possible, avoid talking about "cryptographic identity" which is very jargony. +In many contexts, just the word "identity" is sufficient: the dictionary definition of +identity meaning that someone is who they claim they are, not someone else. The +fact we confirm identity cryptographically is usually irrelevant to the user. ### Identity @@ -212,7 +211,7 @@ rather than your device(s) ### Key storage **Key storage** means keeping cryptographic information on the server. This -includes the user's cryptographic identity, and/or the message keys needed to +includes the user's identity, and/or the message keys needed to decrypt messages. If a user loses their recovery key, they may **reset** their key storage. Unless @@ -222,7 +221,7 @@ identity will change, because it too is stored in key storage. > "Allow key storage" -> "Key storage holds your cryptographic identity on the server along with the +> "Key storage holds your identity on the server along with the > keys that allow you to read your message history." > "Message history is unavailable because key storage is disabled." @@ -232,7 +231,7 @@ both part of key storage. ⚠️ Avoid talking about more keys: "the backup key is stored in the secret storage, and this allows us to decrypt the messages keys from key backup". -Instead, we simply say that both cryptographic identity and message keys are +Instead, we simply say that both identity and message keys are stored in key storage. ⚠️ Avoid using "key backup" to talk about storing message keys: this is too @@ -260,7 +259,7 @@ key and has the same purpose as the recovery key. ⚠️ Avoid using "security key", "security code", "recovery code", "master key". A recovery key allows "unlocking" the key storage, which is a "box" that is on the -server, containing your cryptographic identity and message keys. It is used to +server, containing your identity and message keys. It is used to recover the situation if you lose access to your devices. None of these other terms express this concept so clearly. From 3ed51ec665f6ac4f711a2a1b7cfac92b2e437e3a Mon Sep 17 00:00:00 2001 From: Andy Balaam Date: Tue, 17 Dec 2024 13:35:19 +0000 Subject: [PATCH 27/31] Link to spec sections on QR and emoji, and transitive trust MSC --- proposals/4161-crypto-terminology.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/proposals/4161-crypto-terminology.md b/proposals/4161-crypto-terminology.md index 0b1b0482434..7fcaee267b3 100644 --- a/proposals/4161-crypto-terminology.md +++ b/proposals/4161-crypto-terminology.md @@ -102,8 +102,8 @@ cryptographic proof that no-one is listening in on your conversations. (You need this if you suspect someone in a room may be using a malicious homeserver.) In many contexts, most users are **not verified**: verification is a manual -step (scanning a QR code or comparing emojis). (In future, verification will -probably become more common thanks to "transitive trust" or "key transparency"). +step ([scanning a QR code](https://spec.matrix.org/v1.12/client-server-api/#qr-codes) or [comparing emojis](https://spec.matrix.org/v1.12/client-server-api/#sas-method-emoji)). (In future, verification will +probably become more common thanks to [MSC2882 Transitive Trust](https://github.com/matrix-org/matrix-spec-proposals/pull/2882) or something similar). When an unverified user resets their identity, we should warn the user, so they are aware of the change. From b44397bad6cc734d5203bd4b28f0c973ff5d27f8 Mon Sep 17 00:00:00 2001 From: Andy Balaam Date: Tue, 17 Dec 2024 14:00:38 +0000 Subject: [PATCH 28/31] Add a section about why this is important --- proposals/4161-crypto-terminology.md | 25 ++++++++++++++++++++++++- 1 file changed, 24 insertions(+), 1 deletion(-) diff --git a/proposals/4161-crypto-terminology.md b/proposals/4161-crypto-terminology.md index 7fcaee267b3..386f35215b9 100644 --- a/proposals/4161-crypto-terminology.md +++ b/proposals/4161-crypto-terminology.md @@ -21,7 +21,30 @@ initiative is referred to as "Invisible Cryptography" and is tracked as: Including device keys with Olm-encrypted events, and * MSC4161 - this document -## Goals +## Why is this important? + +Use of common terminology should help further these goals: + +* **to reduce confusion**: many members of the community are confused by the + crypto features in Matrix clients, and the profusion of different words for + the same thing makes it much worse. By reducing the *number* of words, and + carefully choosing *good* words, we hope to develop a common language which + makes Matrix easier to understand, and easier to explain. + +* **to ease migration**: one of the key features of Matrix for end-users is the + choice of clients, meaning no-one is locked in to a particular piece of + software. If each client uses conflicting terminology, it becomes much more + difficult to move to a different client, which works against the user's + ability to migrate. + +This proposal uses "SHOULD" language rather than "MUST", because there are many +good reasons why a particular client might choose different wording. In +particular, different clients may have very different audiences who communicate +in different ways and understand different metaphors. This proposal hopes to +nudge client developers towards consistency, but never at the cost of their +unique relationship with their users. + +## Outcomes We hope that Matrix client developers will like the terms and wording we provide, and adapt their user interfaces and documentation to use them. (If this From 04df819f2f18191781c0489aeca17bede6cc5d05 Mon Sep 17 00:00:00 2001 From: Andy Balaam Date: Tue, 17 Dec 2024 14:16:50 +0000 Subject: [PATCH 29/31] Add a paragraph about losing the recovery key --- proposals/4161-crypto-terminology.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/proposals/4161-crypto-terminology.md b/proposals/4161-crypto-terminology.md index 386f35215b9..384c744d090 100644 --- a/proposals/4161-crypto-terminology.md +++ b/proposals/4161-crypto-terminology.md @@ -272,6 +272,15 @@ changed" messages), and also read old messages using the stored message keys. A **recovery passphrase** is an easier-to-remember way of accessing the recovery key and has the same purpose as the recovery key. +**Losing the recovery key**: if the user loses their recovery key, they can +"reset" it, which means re-storing the identity information in the server, +encrypted with a new recovery key. If the user has a verified client, then that +is holding the identity information locally, so they can reset their recovery +key without losing access to key storage. If they don't have a verified client +and they lose their recovery key, then they need to reset key storage as well as +recovery key (since the identity information is needed to read from key +storage), meaning they lose access to old messages. + > "Write down your recovery key in a safe place" > "If you lose access to your devices and your recovery key, you will need to From bdbd7b4b711d0cf19f5e7cb4389b7ea678c41426 Mon Sep 17 00:00:00 2001 From: Andy Balaam Date: Tue, 17 Dec 2024 15:14:37 +0000 Subject: [PATCH 30/31] Remove the 'appears to have changed' wording and add explanation --- proposals/4161-crypto-terminology.md | 19 ++++++++++++------- 1 file changed, 12 insertions(+), 7 deletions(-) diff --git a/proposals/4161-crypto-terminology.md b/proposals/4161-crypto-terminology.md index 384c744d090..c8b100dc91e 100644 --- a/proposals/4161-crypto-terminology.md +++ b/proposals/4161-crypto-terminology.md @@ -169,14 +169,19 @@ fact we confirm identity cryptographically is usually irrelevant to the user. ### Identity -A user's **identity** is proof of who they are, and, if they are verified, +A user's **identity** is proof of who they are, and, if you have verified them, 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) +> When a non-verified user resets their identity: +> "Warning: Alice's identity has changed." +> +> Longer explanation: +> 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. To be sure, please +> verify their identity by going to their profile. -> "WARNING: Bob's verified identity has changed!" (when a verified user resets -> their recovery key) +> When a verified user resets their identity: +> "WARNING: Bob's verified identity has changed!" (During login, at the "Confirm it's you" stage): @@ -186,7 +191,7 @@ proof that you have a secure communication channel with them. ⚠️ Avoid saying "master key" - this is an implementation detail. -⚠️ Avoid saying "reset their encryption" - the reason that Alice's identity +⚠️ Avoid saying "Alice reset their encryption" - the reason that Alice's identity changed could be due to attack rather than because they reset their encryption (plus "encryption" is jargony). @@ -266,7 +271,7 @@ easily confused with exporting keys or messages to an external system. 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 -identity (meaning other users don't see "Alice's identity appears to have +identity (meaning other users don't see "Alice's identity has changed" messages), and also read old messages using the stored message keys. A **recovery passphrase** is an easier-to-remember way of accessing the recovery From 7a9a84b16dd1057bccc8c7e3dac2a07d26089bbb Mon Sep 17 00:00:00 2001 From: Andy Balaam Date: Tue, 17 Dec 2024 15:26:58 +0000 Subject: [PATCH 31/31] Note that older spec versions say 'recovery key' --- proposals/4161-crypto-terminology.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/4161-crypto-terminology.md b/proposals/4161-crypto-terminology.md index c8b100dc91e..f6f8faa8534 100644 --- a/proposals/4161-crypto-terminology.md +++ b/proposals/4161-crypto-terminology.md @@ -306,7 +306,7 @@ should provide a way for users to be educated on the terminology change (e.g. a tooltip or help link): e.g. "Your recovery key may also have been referred to as a security key in the past" -⚠️ Be aware that at time of writing the spec uses +⚠️ Be aware that old versions of the spec use ["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