diff --git a/proposals/4153-invisible-crypto.md b/proposals/4153-invisible-crypto.md new file mode 100644 index 00000000000..1d4c015ddf2 --- /dev/null +++ b/proposals/4153-invisible-crypto.md @@ -0,0 +1,272 @@ +# MSC4153: Exclude non-cross-signed devices + +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, +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 + +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](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 +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 +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 + +When one user verifies a different user, the verification SHOULD verify the +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 +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. 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. + +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 synchronising information between devices could be proposed by +another MSC. + +### 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 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) +with a code of `m.unverified` to indicate to the non-cross-signed device why it +is not receiving the room key. + +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. + +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 to the user. + +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. + +### 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 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 +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. + +### 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 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. + +[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 + +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 "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: + +- 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 +- Quaternion (versions prior to 0.98) + +### 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. + +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. + +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: + +- [mautrix-go](https://github.com/mautrix/go) (planned support for Application Services) + +## 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. + +## 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. 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 + 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.