From a9071b1e73ad0154ae353dd9fa2b0719455d46d6 Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Mon, 10 Jun 2024 18:38:57 -0400 Subject: [PATCH 01/17] initial draft of invisible crypto --- proposals/xxxx-invisible-crypto.md | 122 +++++++++++++++++++++++++++++ 1 file changed, 122 insertions(+) create mode 100644 proposals/xxxx-invisible-crypto.md diff --git a/proposals/xxxx-invisible-crypto.md b/proposals/xxxx-invisible-crypto.md new file mode 100644 index 00000000000..f1800a36c7f --- /dev/null +++ b/proposals/xxxx-invisible-crypto.md @@ -0,0 +1,122 @@ +# MSCxxxx: Invisible Cryptography + +End-to-end encryption was first introduced to Matrix in 2016. Over the years, +more encryption-related features have been added, such as key verification, +cross-signing, key backup, and secure storage/sharing. + +The current spec allows clients freedom to choose what features to implement. +And while clients should be able to make decisions based on their threat model, +there are behaviours that the spec can recommend that will improve the user +experience and security of encrypted conversations. + +In general, this MSC proposes to standardize on using cross-signing as a basis +for trusting devices. While a user may be unable to verify every other user +that they communicate with, or may be unaware of the need to verify other +users, cross-signing gives some measure of protection and so should be used +where possible. One of the goals of this MSC is to reduce the number of +warnings that users will encounter by taking advantage of cross-signing. + +## Proposal + +The changes below only apply to clients that support encryption. + +### Users should have cross-signing keys + +Clients should create new cross-signing keys for users who do not yet have +cross-signing keys. + +Users should have Secret Storage with a default key that encrypts the private +cross-signing keys and key backup key (if available) + +The spec currently does not give recommendations for what information is stored +in Secret Storage, or even whether Secret Storage is available to users. A +user’s Secret Storage should contain the user’s cross-signing secret keys and +the key backup decryption key (if the user is using key backup). This ensures +that users have a more consistent experience. + +### Verifying individual devices of other users is deprecated + +When one user verifies a different user, the verification should verify the +users’ cross-signing keys. Any flow that verifies only the device keys of +different users is deprecated. Verifying a user’s own device keys is still +supported. + +### Devices should be cross-signed + +Clients should encourage users to cross-sign their devices. This includes both +when logging in a new device, and for existing devices. Clients may even go so +far as to require cross-signing of devices by preventing the user from using +the client until the device is cross-signed. If the user cannot cross-sign +their device (for example, if they have forgotten their Secret Storage key), +the client can allow users to reset their Secret Storage, cross-signing, and +key backup. + +### Clients should flag when cross-signing keys change + +If Alice’s cross-signing keys change, Alice’s own devices must alert her to +this fact, and prompt her to re-cross-sign those devices. If Bob is in an +encrypted room with Alice, Bob’s devices should inform him of Alice’s key +change and should prevent him from sending an encrypted message to Alice +without acknowledging the change. + +Bob’s clients may behave differently depending on whether Bob had previously +verified Alice or not. For example, if Bob had previously verified Alice, and +Alice’s keys change, Bob’s client may require Bob to re-verify, or may display +a more aggressive warning. + +Note that this MSC does not propose a mechanism for remembering previous +cross-signing keys between devices. In other words if Alice changes her +cross-signing keys and then Bob logs in a new device, Bob’s new device will not +know that Alice’s cross-signing keys had changed, even if Bob has other devices +that were previously logged in. Such a mechanism could be proposed by another +MSC. + +### Room keys should by default not be sent to non-cross-signed devices + +Since non-cross-signed devices don’t provide any assurance that the device +belongs to the user, and server admins can trivially create new devices for +users, clients should not send room keys to non-cross-signed devices by +default. Clients may provide users the ability to encrypt to specific +non-cross-signed devices, for example, for development or testing purposes. + +### Messages from non-cross-signed devices should be untrusted + +Similarly, clients have no assurance that encrypted messages sent from +non-cross-signed devices were sent by the user, rather than an +impersonator. Therefore messages sent from non-cross-signed devices cannot be +trusted and should be displayed differently to the user. For example, the +message could be displayed with a warning, or may be hidden completely from the +user. Again, clients may be allow the user to override this behaviour for +specific devices for development or testing purposes. + +## Potential Issues + +If a user has devices that are not cross-signed, they will not be able to +communicate with other users whose clients implement this proposal completely, +due to the last two points. Thus we encourage clients to implement +cross-signing as soon as possible, and to encourage users to cross-sign their +devices, and clients should delay the implementation of the last two points (or +make it optional) until most clients have implemented cross-signing. + +TODO: status of cross-signing in clients + +## Alternatives + +## Security considerations + +## Unstable prefix + +No new names are introduced, so no unstable prefix is needed. + +## Dependencies + +Though not strictly dependencies, other MSCs improve the behaviour of this MSC: +- [authenticated backups + (MSC4048)](https://github.com/matrix-org/matrix-spec-proposals/pull/4048) + will improve the user experience by ensuring that trust information is + preserved when loading room keys from backup. TODO: I think we also need to + add information to the backup about the cross-signing status of the device +- [Including device keys with Olm-encrypted events + (MSC4147)](https://github.com/matrix-org/matrix-spec-proposals/pull/4147) + allows recipients to check the cross-signing status of devices that have been + deleted From 33cb6a59c5f6ce5c985c4391b379a06325e076fb Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Mon, 10 Jun 2024 19:31:51 -0400 Subject: [PATCH 02/17] use MSC number --- .../{xxxx-invisible-crypto.md => 4153-invisible-crypto.md} | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) rename proposals/{xxxx-invisible-crypto.md => 4153-invisible-crypto.md} (99%) diff --git a/proposals/xxxx-invisible-crypto.md b/proposals/4153-invisible-crypto.md similarity index 99% rename from proposals/xxxx-invisible-crypto.md rename to proposals/4153-invisible-crypto.md index f1800a36c7f..a8e5ba003ff 100644 --- a/proposals/xxxx-invisible-crypto.md +++ b/proposals/4153-invisible-crypto.md @@ -1,4 +1,4 @@ -# MSCxxxx: Invisible Cryptography +# MSC4153: Invisible Cryptography End-to-end encryption was first introduced to Matrix in 2016. Over the years, more encryption-related features have been added, such as key verification, From f02666f79512359e63a3ebf8af883003230b57be Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Tue, 25 Jun 2024 18:17:27 -0400 Subject: [PATCH 03/17] clarifications and respond to PR review comments --- proposals/4153-invisible-crypto.md | 43 ++++++++++++++++++++++-------- 1 file changed, 32 insertions(+), 11 deletions(-) diff --git a/proposals/4153-invisible-crypto.md b/proposals/4153-invisible-crypto.md index a8e5ba003ff..33b43e268c5 100644 --- a/proposals/4153-invisible-crypto.md +++ b/proposals/4153-invisible-crypto.md @@ -1,4 +1,4 @@ -# MSC4153: Invisible Cryptography +# MSC4153: Exclude non-cross-signed devices End-to-end encryption was first introduced to Matrix in 2016. Over the years, more encryption-related features have been added, such as key verification, @@ -25,14 +25,20 @@ The changes below only apply to clients that support encryption. Clients should create new cross-signing keys for users who do not yet have cross-signing keys. -Users should have Secret Storage with a default key that encrypts the private -cross-signing keys and key backup key (if available) +### Users should have Secret Storage + +Secret Storage allows users to keep secrets on the server so that they are +accessible when the user logs in to a new device. The spec currently does not give recommendations for what information is stored in Secret Storage, or even whether Secret Storage is available to users. A user’s Secret Storage should contain the user’s cross-signing secret keys and the key backup decryption key (if the user is using key backup). This ensures -that users have a more consistent experience. +that users use cross-signing and key backup on new devices. + +Users should have Secret Storage with a default key (a key referred to by +`m.secret_storage.default_key`) that encrypts the private cross-signing keys +and key backup key (if available). ### Verifying individual devices of other users is deprecated @@ -71,7 +77,7 @@ know that Alice’s cross-signing keys had changed, even if Bob has other device that were previously logged in. Such a mechanism could be proposed by another MSC. -### Room keys should by default not be sent to non-cross-signed devices +### Room keys and secrets should by default not be sent to non-cross-signed devices Since non-cross-signed devices don’t provide any assurance that the device belongs to the user, and server admins can trivially create new devices for @@ -79,18 +85,22 @@ users, clients should not send room keys to non-cross-signed devices by default. Clients may provide users the ability to encrypt to specific non-cross-signed devices, for example, for development or testing purposes. -### Messages from non-cross-signed devices should be untrusted +In addition, users should not send secrets (via Secret Sharing) to their own +devices that are not cross-signed. + +### Messages from non-cross-signed devices should be ignored by default Similarly, clients have no assurance that encrypted messages sent from non-cross-signed devices were sent by the user, rather than an impersonator. Therefore messages sent from non-cross-signed devices cannot be -trusted and should be displayed differently to the user. For example, the -message could be displayed with a warning, or may be hidden completely from the -user. Again, clients may be allow the user to override this behaviour for -specific devices for development or testing purposes. +trusted and should not be displayed differently to the user. Again, clients +may be allow the user to override this behaviour for specific devices for +development or testing purposes. ## Potential Issues +### Client support + If a user has devices that are not cross-signed, they will not be able to communicate with other users whose clients implement this proposal completely, due to the last two points. Thus we encourage clients to implement @@ -100,6 +110,17 @@ make it optional) until most clients have implemented cross-signing. TODO: status of cross-signing in clients +### Bots and application services + +This is a special case to the issue above, but seems to be a large enough class +that it deserves its own mention: support for cross-signing in bots and +application services may be less common than in interactive clients. When a +client fully implements this proposal, users will be unable to interact with +bots and application services in encrypted rooms if they do not support +cross-signing. + +TODO: status of cross-signing in bots/application services + ## Alternatives ## Security considerations @@ -111,7 +132,7 @@ No new names are introduced, so no unstable prefix is needed. ## Dependencies Though not strictly dependencies, other MSCs improve the behaviour of this MSC: -- [authenticated backups +- [Authenticated backups (MSC4048)](https://github.com/matrix-org/matrix-spec-proposals/pull/4048) will improve the user experience by ensuring that trust information is preserved when loading room keys from backup. TODO: I think we also need to From b2c9541f0697b1146fc340a2591348ad629d3cd8 Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Fri, 31 Jan 2025 13:33:31 -0500 Subject: [PATCH 04/17] respond to review comments and add some more clarifications --- proposals/4153-invisible-crypto.md | 119 ++++++++++++++++++++++------- 1 file changed, 91 insertions(+), 28 deletions(-) diff --git a/proposals/4153-invisible-crypto.md b/proposals/4153-invisible-crypto.md index 33b43e268c5..cf68f8fa776 100644 --- a/proposals/4153-invisible-crypto.md +++ b/proposals/4153-invisible-crypto.md @@ -18,38 +18,38 @@ warnings that users will encounter by taking advantage of cross-signing. ## Proposal -The changes below only apply to clients that support encryption. +Note: The changes below only apply to clients that support encryption. -### Users should have cross-signing keys +### Users SHOULD have cross-signing keys -Clients should create new cross-signing keys for users who do not yet have +Clients SHOULD create new cross-signing keys for users who do not yet have cross-signing keys. -### Users should have Secret Storage +### Users SHOULD have Secret Storage Secret Storage allows users to keep secrets on the server so that they are accessible when the user logs in to a new device. The spec currently does not give recommendations for what information is stored in Secret Storage, or even whether Secret Storage is available to users. A -user’s Secret Storage should contain the user’s cross-signing secret keys and +user’s Secret Storage SHOULD contain the user’s cross-signing secret keys and the key backup decryption key (if the user is using key backup). This ensures that users use cross-signing and key backup on new devices. -Users should have Secret Storage with a default key (a key referred to by +Users SHOULD have Secret Storage with a default key (a key referred to by `m.secret_storage.default_key`) that encrypts the private cross-signing keys and key backup key (if available). ### Verifying individual devices of other users is deprecated -When one user verifies a different user, the verification should verify the +When one user verifies a different user, the verification SHOULD verify the users’ cross-signing keys. Any flow that verifies only the device keys of -different users is deprecated. Verifying a user’s own device keys is still -supported. +different users is deprecated without verifying the cross-signing keys. +Verifying a user’s own device keys is still supported. -### Devices should be cross-signed +### Devices SHOULD be cross-signed -Clients should encourage users to cross-sign their devices. This includes both +Clients SHOULD encourage users to cross-sign their devices. This includes both when logging in a new device, and for existing devices. Clients may even go so far as to require cross-signing of devices by preventing the user from using the client until the device is cross-signed. If the user cannot cross-sign @@ -57,12 +57,12 @@ their device (for example, if they have forgotten their Secret Storage key), the client can allow users to reset their Secret Storage, cross-signing, and key backup. -### Clients should flag when cross-signing keys change +### Clients SHOULD flag when cross-signing keys change -If Alice’s cross-signing keys change, Alice’s own devices must alert her to +If Alice’s cross-signing keys change, Alice’s own devices MUST alert her to this fact, and prompt her to re-cross-sign those devices. If Bob is in an -encrypted room with Alice, Bob’s devices should inform him of Alice’s key -change and should prevent him from sending an encrypted message to Alice +encrypted room with Alice, Bob’s devices SHOULD inform him of Alice’s key +change and SHOULD prevent him from sending an encrypted message to Alice without acknowledging the change. Bob’s clients may behave differently depending on whether Bob had previously @@ -74,28 +74,72 @@ Note that this MSC does not propose a mechanism for remembering previous cross-signing keys between devices. In other words if Alice changes her cross-signing keys and then Bob logs in a new device, Bob’s new device will not know that Alice’s cross-signing keys had changed, even if Bob has other devices -that were previously logged in. Such a mechanism could be proposed by another -MSC. +that were previously logged in. This may result in Bob never seeing a warning +about Alice's identity change, for example if Bob logs out of his last device, +then Alice changes her cross-signing keys, and then Bob logs into a new device. -### Room keys and secrets should by default not be sent to non-cross-signed devices +In addition, this MSC does not propose a mechanism for synchronising between +devices information regarding what warnings the user has seen or acknowledged. +That is, if Alice changes her cross-signing keys and Bob has multiple devices +logged in, then Bob will see a warning on all his devices, and will have to +dismiss the warning on all of his devices. + +A mechanism for synchonising information between devices could be proposed by +another MSC. + +### Encrypted to-device messages MUST NOT be sent to non-cross-signed devices Since non-cross-signed devices don’t provide any assurance that the device belongs to the user, and server admins can trivially create new devices for -users, clients should not send room keys to non-cross-signed devices by -default. Clients may provide users the ability to encrypt to specific -non-cross-signed devices, for example, for development or testing purposes. +users, clients MUST not send encrypted to-device messages, such as room keys or +secrets (via Secret Sharing), to non-cross-signed devices by default. When +sending room keys, clients can use a [`m.room_key.withheld` +message](https://spec.matrix.org/unstable/client-server-api/#reporting-that-decryption-keys-are-withheld) +with a code of `m.unverified` to indicate to the non-cross-signed device why it +is not receiving the room key. -In addition, users should not send secrets (via Secret Sharing) to their own -devices that are not cross-signed. +An allowed exception to this rule is that clients may provide users the ability +to encrypt to specific non-cross-signed devices for development or testing +purposes. -### Messages from non-cross-signed devices should be ignored by default +A future MSC may specify exceptions to this rule. For example, if a future MSC +defines a device verification method that uses encrypted to-device messages, +such messages would need to be sent to a user's own non-cross-signed devices, so +that the user can verify their device to cross-sign it. + +### Encrypted messages from non-cross-signed devices SHOULD be ignored Similarly, clients have no assurance that encrypted messages sent from non-cross-signed devices were sent by the user, rather than an impersonator. Therefore messages sent from non-cross-signed devices cannot be -trusted and should not be displayed differently to the user. Again, clients -may be allow the user to override this behaviour for specific devices for -development or testing purposes. +trusted and SHOULD NOT be displayed to the user. + +Again, an allowed exception to this is that clients may be allow the user to +override this behaviour for specific devices for development or testing +purposes. + +### Non-cryptographic devices SHOULD NOT impact E2EE behaviour + +For the sake of clarity: non-cryptographic devices (devices which do not have +device identity keys uploaded to the homeserver) should not have any impact on +a client's E2EE behaviour. For all intents and purposes, non-cryptographic +devices are a completely separate concept and do not exist from the perspective +of the cryptography layer since they do not have identity keys, so it is +impossible to send them encrypted messages. + +In particular, Matrix clients MUST NOT consider non-cryptographic devices to be +equivalent to non-cross-signed cryptographic devices for purposes of enforcing +E2EE policy. For example, clients SHOULD NOT warn nor refuse to send messages +due to the presence of non-cryptographic devices. + +The intent of this is to smoothly support and minimise interference from +applications which choose to set up E2EE only on demand (e.g. +[WorkAdventure](https://workadventu.re/article-en/managing-e2e-encryption-with-matrix-in-a-simple-way/). +Such clients should initially create a non-cryptographic device until they are +ready to set up E2EE. Only when they are ready will they create the device +identity keys for the device and upload them to the homeserver, converting the +device into a cryptographic device and making it subject to the rules given in +this MSC. ## Potential Issues @@ -119,12 +163,31 @@ client fully implements this proposal, users will be unable to interact with bots and application services in encrypted rooms if they do not support cross-signing. -TODO: status of cross-signing in bots/application services +Some possible solutions for bots are: + +- if a bot is the only device logged into a given account, the bot can create its + own cross-signing keys and cross-sign its device. +- the bot administrator can provide the Secret Storage key to the bot so that + the bot can fetch its self-signing private key and cross-sign its device. +- the bot can log its device keys so that the administrator can cross-sign it + from a different device by manually comparing the device keys. Note that many + clients do not have the ability to verify by comparing device keys. + +TODO: status of cross-signing in bots/application services, which clients can be +used to cross-sign by comparing device keys ## Alternatives +We could do nothing and leave things as they are, but the rules given in this +MSC provide improved security. + ## Security considerations +Warning the user about cross-signing key changes can be circumvented by a +malicious server if it sends forged cross-signing keys the first time the user +sees them. Therefore users should still verify other users when security is +important. + ## Unstable prefix No new names are introduced, so no unstable prefix is needed. From 5e01739c61828397662fe085f7e59c4597958fd8 Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Fri, 31 Jan 2025 14:26:06 -0500 Subject: [PATCH 05/17] fix typo --- proposals/4153-invisible-crypto.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/4153-invisible-crypto.md b/proposals/4153-invisible-crypto.md index cf68f8fa776..785ff1a1114 100644 --- a/proposals/4153-invisible-crypto.md +++ b/proposals/4153-invisible-crypto.md @@ -84,7 +84,7 @@ That is, if Alice changes her cross-signing keys and Bob has multiple devices logged in, then Bob will see a warning on all his devices, and will have to dismiss the warning on all of his devices. -A mechanism for synchonising information between devices could be proposed by +A mechanism for synchronising information between devices could be proposed by another MSC. ### Encrypted to-device messages MUST NOT be sent to non-cross-signed devices From 010b2943f67e01b382c8d06720947cb74bc34c8c Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Fri, 31 Jan 2025 14:41:10 -0500 Subject: [PATCH 06/17] additional clarification --- proposals/4153-invisible-crypto.md | 24 +++++++++++++----------- 1 file changed, 13 insertions(+), 11 deletions(-) diff --git a/proposals/4153-invisible-crypto.md b/proposals/4153-invisible-crypto.md index 785ff1a1114..2641aa846e7 100644 --- a/proposals/4153-invisible-crypto.md +++ b/proposals/4153-invisible-crypto.md @@ -27,18 +27,20 @@ cross-signing keys. ### Users SHOULD have Secret Storage -Secret Storage allows users to keep secrets on the server so that they are -accessible when the user logs in to a new device. - The spec currently does not give recommendations for what information is stored -in Secret Storage, or even whether Secret Storage is available to users. A -user’s Secret Storage SHOULD contain the user’s cross-signing secret keys and -the key backup decryption key (if the user is using key backup). This ensures -that users use cross-signing and key backup on new devices. - -Users SHOULD have Secret Storage with a default key (a key referred to by -`m.secret_storage.default_key`) that encrypts the private cross-signing keys -and key backup key (if available). +in Secret Storage, or even whether Secret Storage is available to users. Secret +Storage allows users to keep secrets on the server so that they are accessible +when the user logs in to a new device and does not have an existing device that +can share the secrets with the new device. Therefore users SHOULD have Secret +storage set up. + +The user’s Secret Storage SHOULD contain the user’s cross-signing secret keys +and the key backup decryption key (if the user is using key backup). This +ensures that users use cross-signing and key backup on new devices. + +The user's Secret Storage SHOULD have a default key (a key referred to by +`m.secret_storage.default_key`) that encrypts the private cross-signing keys and +key backup key (if available). ### Verifying individual devices of other users is deprecated From ea450d2dd19801b9b8ca7d89d7925e25b0ef37c4 Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Fri, 31 Jan 2025 14:45:15 -0500 Subject: [PATCH 07/17] another typo --- proposals/4153-invisible-crypto.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/4153-invisible-crypto.md b/proposals/4153-invisible-crypto.md index 2641aa846e7..8478cdc6f19 100644 --- a/proposals/4153-invisible-crypto.md +++ b/proposals/4153-invisible-crypto.md @@ -116,7 +116,7 @@ non-cross-signed devices were sent by the user, rather than an impersonator. Therefore messages sent from non-cross-signed devices cannot be trusted and SHOULD NOT be displayed to the user. -Again, an allowed exception to this is that clients may be allow the user to +Again, an allowed exception to this is that clients may allow the user to override this behaviour for specific devices for development or testing purposes. From 31748ab1a719509ca38159e41d33d21085f1fdcb Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Tue, 18 Feb 2025 21:51:23 -0500 Subject: [PATCH 08/17] add cross-signing status for clients --- proposals/4153-invisible-crypto.md | 16 +++++++++++++++- 1 file changed, 15 insertions(+), 1 deletion(-) diff --git a/proposals/4153-invisible-crypto.md b/proposals/4153-invisible-crypto.md index 8478cdc6f19..d5a6ff3db5a 100644 --- a/proposals/4153-invisible-crypto.md +++ b/proposals/4153-invisible-crypto.md @@ -154,7 +154,21 @@ cross-signing as soon as possible, and to encourage users to cross-sign their devices, and clients should delay the implementation of the last two points (or make it optional) until most clients have implemented cross-signing. -TODO: status of cross-signing in clients +The following clients support cross-signing: + +- Cinny +- Element (all platforms), and derivatives such as Schildi Chat +- Fractal +- gomuks +- NeoChat +- Nheko +- pantalaimon +- Tammy +- Trixnity Messenger + +The following encryption-capable clients do not support cross-signing: + +- kazv ### Bots and application services From 6084c6e1fc693d20f06f344973507d97f778a3bb Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Tue, 11 Mar 2025 14:05:39 -0400 Subject: [PATCH 09/17] add cross-signing status for bots, and fix note about authenticated backups --- proposals/4153-invisible-crypto.md | 17 +++++++++++++---- 1 file changed, 13 insertions(+), 4 deletions(-) diff --git a/proposals/4153-invisible-crypto.md b/proposals/4153-invisible-crypto.md index d5a6ff3db5a..98197c6cc28 100644 --- a/proposals/4153-invisible-crypto.md +++ b/proposals/4153-invisible-crypto.md @@ -189,8 +189,16 @@ Some possible solutions for bots are: from a different device by manually comparing the device keys. Note that many clients do not have the ability to verify by comparing device keys. -TODO: status of cross-signing in bots/application services, which clients can be -used to cross-sign by comparing device keys +The following bots support cross-signing: + +- [meowlnir](https://github.com/maunium/meowlnir) +- [Arnie](https://gitlab.com/andybalaam/arnie) + +The following bot SDKs support, or plan to support, cross-signing such that any +bots written using them will support cross-signing: + +- [maubot](https://github.com/maubot/maubot) (planned) +- [mautrix-go](https://github.com/mautrix/go) (planned support for Application Services) ## Alternatives @@ -214,8 +222,9 @@ Though not strictly dependencies, other MSCs improve the behaviour of this MSC: - [Authenticated backups (MSC4048)](https://github.com/matrix-org/matrix-spec-proposals/pull/4048) will improve the user experience by ensuring that trust information is - preserved when loading room keys from backup. TODO: I think we also need to - add information to the backup about the cross-signing status of the device + preserved when loading room keys from backup. We may also need to add + information to the backup about the cross-signing status of the device, + but this can be addressed in a future MSC. - [Including device keys with Olm-encrypted events (MSC4147)](https://github.com/matrix-org/matrix-spec-proposals/pull/4147) allows recipients to check the cross-signing status of devices that have been From aeceee38cc02c3c56eff0840755d3be929922e2f Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Thu, 11 Sep 2025 15:20:15 -0400 Subject: [PATCH 10/17] add information on handling encrypted bridges --- proposals/4153-invisible-crypto.md | 20 +++++++++++++++++++- 1 file changed, 19 insertions(+), 1 deletion(-) diff --git a/proposals/4153-invisible-crypto.md b/proposals/4153-invisible-crypto.md index 98197c6cc28..d0bb1c5b3ad 100644 --- a/proposals/4153-invisible-crypto.md +++ b/proposals/4153-invisible-crypto.md @@ -143,6 +143,21 @@ identity keys for the device and upload them to the homeserver, converting the device into a cryptographic device and making it subject to the rules given in this MSC. +### Clients MAY make provisions for encrypted bridges + +Some bridges are structured in a way such that only one user controlled by the +bridge (often called the bridge bot) participates in encryption, and encrypted +messages from other bridge users are encrypted by the bridge bot. Thus +encrypted messages sent by one user could be encrypted by a Megolm session sent +by a different user. Clients MAY accept such messages, provided the bridge +bot's device is cross-signed. However, the client MUST annotate the message with +a warning, unless the client has a way to check that the bridge bot is permitted +to encrypt messages on behalf of the user. + +[MSC4350](https://github.com/matrix-org/matrix-spec-proposals/pull/4350) +presents a way for bridge users to indicate that the bridge bot is allowed to +perform encryption on their behalf. + ## Potential Issues ### Client support @@ -228,4 +243,7 @@ Though not strictly dependencies, other MSCs improve the behaviour of this MSC: - [Including device keys with Olm-encrypted events (MSC4147)](https://github.com/matrix-org/matrix-spec-proposals/pull/4147) allows recipients to check the cross-signing status of devices that have been - deleted + deleted. +- [Permitting encryption impersonation for appservices + (MSC4350)](https://github.com/matrix-org/matrix-spec-proposals/pull/4350) + allows a user to assert that a bridge is allowed to encrypt for them. From 1ef347d15e54fe68d54b4b25b8f23bf8bf87125a Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Mon, 15 Sep 2025 16:23:19 -0400 Subject: [PATCH 11/17] clarify some wording --- proposals/4153-invisible-crypto.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/proposals/4153-invisible-crypto.md b/proposals/4153-invisible-crypto.md index d0bb1c5b3ad..39fad9b40b3 100644 --- a/proposals/4153-invisible-crypto.md +++ b/proposals/4153-invisible-crypto.md @@ -45,9 +45,9 @@ key backup key (if available). ### Verifying individual devices of other users is deprecated When one user verifies a different user, the verification SHOULD verify the -users’ cross-signing keys. Any flow that verifies only the device keys of -different users is deprecated without verifying the cross-signing keys. -Verifying a user’s own device keys is still supported. +users’ cross-signing keys. Any flow between different users that does not +verify the users' cross-signing keys (it verifies only the device keys) is +deprecated. Verifying a user’s own device keys is still supported. ### Devices SHOULD be cross-signed From 5d4bd81dcbf0da44198d602889226eb479f11c1a Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Mon, 15 Sep 2025 16:30:47 -0400 Subject: [PATCH 12/17] Update bot support Co-authored-by: Tulir Asokan --- proposals/4153-invisible-crypto.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/4153-invisible-crypto.md b/proposals/4153-invisible-crypto.md index 39fad9b40b3..f0d928e4ded 100644 --- a/proposals/4153-invisible-crypto.md +++ b/proposals/4153-invisible-crypto.md @@ -208,11 +208,11 @@ The following bots support cross-signing: - [meowlnir](https://github.com/maunium/meowlnir) - [Arnie](https://gitlab.com/andybalaam/arnie) +- [maubot](https://github.com/maubot/maubot) The following bot SDKs support, or plan to support, cross-signing such that any bots written using them will support cross-signing: -- [maubot](https://github.com/maubot/maubot) (planned) - [mautrix-go](https://github.com/mautrix/go) (planned support for Application Services) ## Alternatives From 99d440af6abb93f93188004cb5b9639a1b9385b4 Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Wed, 24 Sep 2025 18:24:01 -0400 Subject: [PATCH 13/17] Apply suggestions from code review Co-authored-by: Andrew Morgan <1342360+anoadragon453@users.noreply.github.com> Co-authored-by: Travis Ralston Co-authored-by: Patrick Cloke Co-authored-by: Alexey Rusakov --- proposals/4153-invisible-crypto.md | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/proposals/4153-invisible-crypto.md b/proposals/4153-invisible-crypto.md index f0d928e4ded..247a5b01a7f 100644 --- a/proposals/4153-invisible-crypto.md +++ b/proposals/4153-invisible-crypto.md @@ -30,9 +30,10 @@ cross-signing keys. The spec currently does not give recommendations for what information is stored in Secret Storage, or even whether Secret Storage is available to users. Secret Storage allows users to keep secrets on the server so that they are accessible -when the user logs in to a new device and does not have an existing device that -can share the secrets with the new device. Therefore users SHOULD have Secret -storage set up. +when the user logs in to a new device. This is necessary to retrieve secrets when +the user does not have an existing device that can then share the secrets with the +new device. Therefore users SHOULD have Secret storage set up to avoid needing +to reset their cryptographic identity in this case. The user’s Secret Storage SHOULD contain the user’s cross-signing secret keys and the key backup decryption key (if the user is using key backup). This @@ -96,7 +97,7 @@ belongs to the user, and server admins can trivially create new devices for users, clients MUST not send encrypted to-device messages, such as room keys or secrets (via Secret Sharing), to non-cross-signed devices by default. When sending room keys, clients can use a [`m.room_key.withheld` -message](https://spec.matrix.org/unstable/client-server-api/#reporting-that-decryption-keys-are-withheld) +message](https://spec.matrix.org/v1.15/client-server-api/#reporting-that-decryption-keys-are-withheld) with a code of `m.unverified` to indicate to the non-cross-signed device why it is not receiving the room key. @@ -136,7 +137,7 @@ due to the presence of non-cryptographic devices. The intent of this is to smoothly support and minimise interference from applications which choose to set up E2EE only on demand (e.g. -[WorkAdventure](https://workadventu.re/article-en/managing-e2e-encryption-with-matrix-in-a-simple-way/). +[WorkAdventure](https://workadventu.re/article-en/managing-e2e-encryption-with-matrix-in-a-simple-way/)). Such clients should initially create a non-cryptographic device until they are ready to set up E2EE. Only when they are ready will they create the device identity keys for the device and upload them to the homeserver, converting the @@ -149,8 +150,8 @@ Some bridges are structured in a way such that only one user controlled by the bridge (often called the bridge bot) participates in encryption, and encrypted messages from other bridge users are encrypted by the bridge bot. Thus encrypted messages sent by one user could be encrypted by a Megolm session sent -by a different user. Clients MAY accept such messages, provided the bridge -bot's device is cross-signed. However, the client MUST annotate the message with +by a different user. Clients MAY accept such messages, provided the session +creator's device is cross-signed. However, the client MUST annotate the message with a warning, unless the client has a way to check that the bridge bot is permitted to encrypt messages on behalf of the user. @@ -184,6 +185,7 @@ The following clients support cross-signing: The following encryption-capable clients do not support cross-signing: - kazv +- Quaternion (versions prior to 0.98) ### Bots and application services From 2019c4ce32bfcc585b85b8c71b11387ad5b61852 Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Thu, 25 Sep 2025 16:38:38 -0400 Subject: [PATCH 14/17] Apply changes from code review --- proposals/4153-invisible-crypto.md | 42 ++++++++++++++++++++---------- 1 file changed, 28 insertions(+), 14 deletions(-) diff --git a/proposals/4153-invisible-crypto.md b/proposals/4153-invisible-crypto.md index 247a5b01a7f..c444da7702f 100644 --- a/proposals/4153-invisible-crypto.md +++ b/proposals/4153-invisible-crypto.md @@ -1,8 +1,9 @@ # MSC4153: Exclude non-cross-signed devices -End-to-end encryption was first introduced to Matrix in 2016. Over the years, -more encryption-related features have been added, such as key verification, -cross-signing, key backup, and secure storage/sharing. +End-to-end encryption was [first introduced to Matrix in +2016](https://matrix.org/blog/2016/11/21/matrix-s-olm-end-to-end-encryption-security-assessment-released-and-implemented-cross-platform-on-riot-at-last/). Over +the years, more encryption-related features have been added, such as key +verification, cross-signing, key backup, and secure storage/sharing. The current spec allows clients freedom to choose what features to implement. And while clients should be able to make decisions based on their threat model, @@ -18,22 +19,25 @@ warnings that users will encounter by taking advantage of cross-signing. ## Proposal -Note: The changes below only apply to clients that support encryption. +Note: The changes below only apply to clients that support +[encryption](https://spec.matrix.org/v1.15/client-server-api/#end-to-end-encryption). ### Users SHOULD have cross-signing keys -Clients SHOULD create new cross-signing keys for users who do not yet have -cross-signing keys. +Clients SHOULD create new [cross-signing +keys](https://spec.matrix.org/v1.15/client-server-api/#cross-signing) for users +who do not yet have cross-signing keys. ### Users SHOULD have Secret Storage -The spec currently does not give recommendations for what information is stored -in Secret Storage, or even whether Secret Storage is available to users. Secret -Storage allows users to keep secrets on the server so that they are accessible -when the user logs in to a new device. This is necessary to retrieve secrets when -the user does not have an existing device that can then share the secrets with the -new device. Therefore users SHOULD have Secret storage set up to avoid needing -to reset their cryptographic identity in this case. +The [spec](https://spec.matrix.org/v1.15/client-server-api/#storage) currently +does not give recommendations for what information is stored in Secret Storage, +or even whether Secret Storage is available to users. Secret Storage allows +users to keep secrets on the server so that they are accessible when the user +logs in to a new device. This is necessary to retrieve secrets when the user +does not have an existing device that can then share the secrets with the new +device. Therefore users SHOULD have Secret storage set up to avoid needing to +reset their cryptographic identity in this case. The user’s Secret Storage SHOULD contain the user’s cross-signing secret keys and the key backup decryption key (if the user is using key backup). This @@ -50,6 +54,16 @@ users’ cross-signing keys. Any flow between different users that does not verify the users' cross-signing keys (it verifies only the device keys) is deprecated. Verifying a user’s own device keys is still supported. +Specifically, for the currently specced verification methods: + +- In Step 15 of (SAS + verification)[https://spec.matrix.org/v1.15/client-server-api/#short-authentication-string-sas-verification], + the master cross-signing key SHOULD be included when two different users are + verifying it other. +- [QR code + verification](https://spec.matrix.org/v1.15/client-server-api/#qr-codes) + already satisfies this requirement. + ### Devices SHOULD be cross-signed Clients SHOULD encourage users to cross-sign their devices. This includes both @@ -128,7 +142,7 @@ device identity keys uploaded to the homeserver) should not have any impact on a client's E2EE behaviour. For all intents and purposes, non-cryptographic devices are a completely separate concept and do not exist from the perspective of the cryptography layer since they do not have identity keys, so it is -impossible to send them encrypted messages. +impossible to send them decryption keys. In particular, Matrix clients MUST NOT consider non-cryptographic devices to be equivalent to non-cross-signed cryptographic devices for purposes of enforcing From 48cb55872d0e1be75a9eb79780e7869c3b972a0c Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Thu, 25 Sep 2025 18:04:11 -0400 Subject: [PATCH 15/17] add note about conflicting when creating cross-signing keys --- proposals/4153-invisible-crypto.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/proposals/4153-invisible-crypto.md b/proposals/4153-invisible-crypto.md index c444da7702f..e9ccd6ad491 100644 --- a/proposals/4153-invisible-crypto.md +++ b/proposals/4153-invisible-crypto.md @@ -28,6 +28,11 @@ Clients SHOULD create new [cross-signing keys](https://spec.matrix.org/v1.15/client-server-api/#cross-signing) for users who do not yet have cross-signing keys. +Since [replacing a cross-signing +key](https://spec.matrix.org/v1.15/client-server-api/#post_matrixclientv3keysdevice_signingupload) +requires User-Interactive Authentication, this will prevent clients from +conflicting if they try to create cross-signing keys at the same time. + ### Users SHOULD have Secret Storage The [spec](https://spec.matrix.org/v1.15/client-server-api/#storage) currently From 6dadee8d79463e5c37f3e909aaea852f64187aa4 Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Wed, 1 Oct 2025 14:47:36 -0400 Subject: [PATCH 16/17] fix reference to two sections that are no longer "the last two" --- proposals/4153-invisible-crypto.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/proposals/4153-invisible-crypto.md b/proposals/4153-invisible-crypto.md index e9ccd6ad491..435dacccdf9 100644 --- a/proposals/4153-invisible-crypto.md +++ b/proposals/4153-invisible-crypto.md @@ -184,10 +184,12 @@ perform encryption on their behalf. If a user has devices that are not cross-signed, they will not be able to communicate with other users whose clients implement this proposal completely, -due to the last two points. Thus we encourage clients to implement -cross-signing as soon as possible, and to encourage users to cross-sign their -devices, and clients should delay the implementation of the last two points (or -make it optional) until most clients have implemented cross-signing. +due to the "Encrypted to-device messages MUST NOT be sent to non-cross-signed +devices" and "Encrypted messages from non-cross-signed devices SHOULD be +ignored" sections. Thus we encourage clients to implement cross-signing as soon +as possible, and to encourage users to cross-sign their devices, and clients +should delay the implementation of those two sections (or make it optional) +until most clients have implemented cross-signing. The following clients support cross-signing: From 772f556e6ef4915331a731d8fcab0486e933862b Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Fri, 10 Oct 2025 15:45:17 -0400 Subject: [PATCH 17/17] change MUST to SHOULD to be compatible with suggestion to delay implementation --- proposals/4153-invisible-crypto.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/proposals/4153-invisible-crypto.md b/proposals/4153-invisible-crypto.md index 435dacccdf9..1d4c015ddf2 100644 --- a/proposals/4153-invisible-crypto.md +++ b/proposals/4153-invisible-crypto.md @@ -109,11 +109,11 @@ dismiss the warning on all of his devices. A mechanism for synchronising information between devices could be proposed by another MSC. -### Encrypted to-device messages MUST NOT be sent to non-cross-signed devices +### Encrypted to-device messages SHOULD NOT be sent to non-cross-signed devices Since non-cross-signed devices don’t provide any assurance that the device belongs to the user, and server admins can trivially create new devices for -users, clients MUST not send encrypted to-device messages, such as room keys or +users, clients SHOULD NOT send encrypted to-device messages, such as room keys or secrets (via Secret Sharing), to non-cross-signed devices by default. When sending room keys, clients can use a [`m.room_key.withheld` message](https://spec.matrix.org/v1.15/client-server-api/#reporting-that-decryption-keys-are-withheld)