MSC4153: Exclude non-cross-signed devices (#4153)

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.