Skip to content

Commit 55ec009

Browse files
uhoreguhoreg
authored
MSC4153: Exclude non-cross-signed devices (#4153)
1 parent ebb7d20 commit 55ec009

File tree

1 file changed

+272
-0
lines changed

1 file changed

+272
-0
lines changed

‎proposals/4153-invisible-crypto.md‎

Lines changed: 272 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,272 @@
1+
# MSC4153: Exclude non-cross-signed devices
2+
3+
End-to-end encryption was [first introduced to Matrix in
4+
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
5+
the years, more encryption-related features have been added, such as key
6+
verification, cross-signing, key backup, and secure storage/sharing.
7+
8+
The current spec allows clients freedom to choose what features to implement.
9+
And while clients should be able to make decisions based on their threat model,
10+
there are behaviours that the spec can recommend that will improve the user
11+
experience and security of encrypted conversations.
12+
13+
In general, this MSC proposes to standardize on using cross-signing as a basis
14+
for trusting devices. While a user may be unable to verify every other user
15+
that they communicate with, or may be unaware of the need to verify other
16+
users, cross-signing gives some measure of protection and so should be used
17+
where possible. One of the goals of this MSC is to reduce the number of
18+
warnings that users will encounter by taking advantage of cross-signing.
19+
20+
## Proposal
21+
22+
Note: The changes below only apply to clients that support
23+
[encryption](https://spec.matrix.org/v1.15/client-server-api/#end-to-end-encryption).
24+
25+
### Users SHOULD have cross-signing keys
26+
27+
Clients SHOULD create new [cross-signing
28+
keys](https://spec.matrix.org/v1.15/client-server-api/#cross-signing) for users
29+
who do not yet have cross-signing keys.
30+
31+
Since [replacing a cross-signing
32+
key](https://spec.matrix.org/v1.15/client-server-api/#post_matrixclientv3keysdevice_signingupload)
33+
requires User-Interactive Authentication, this will prevent clients from
34+
conflicting if they try to create cross-signing keys at the same time.
35+
36+
### Users SHOULD have Secret Storage
37+
38+
The [spec](https://spec.matrix.org/v1.15/client-server-api/#storage) currently
39+
does not give recommendations for what information is stored in Secret Storage,
40+
or even whether Secret Storage is available to users. Secret Storage allows
41+
users to keep secrets on the server so that they are accessible when the user
42+
logs in to a new device. This is necessary to retrieve secrets when the user
43+
does not have an existing device that can then share the secrets with the new
44+
device. Therefore users SHOULD have Secret storage set up to avoid needing to
45+
reset their cryptographic identity in this case.
46+
47+
The user’s Secret Storage SHOULD contain the user’s cross-signing secret keys
48+
and the key backup decryption key (if the user is using key backup). This
49+
ensures that users use cross-signing and key backup on new devices.
50+
51+
The user's Secret Storage SHOULD have a default key (a key referred to by
52+
`m.secret_storage.default_key`) that encrypts the private cross-signing keys and
53+
key backup key (if available).
54+
55+
### Verifying individual devices of other users is deprecated
56+
57+
When one user verifies a different user, the verification SHOULD verify the
58+
users’ cross-signing keys. Any flow between different users that does not
59+
verify the users' cross-signing keys (it verifies only the device keys) is
60+
deprecated. Verifying a user’s own device keys is still supported.
61+
62+
Specifically, for the currently specced verification methods:
63+
64+
- In Step 15 of (SAS
65+
verification)[https://spec.matrix.org/v1.15/client-server-api/#short-authentication-string-sas-verification],
66+
the master cross-signing key SHOULD be included when two different users are
67+
verifying it other.
68+
- [QR code
69+
verification](https://spec.matrix.org/v1.15/client-server-api/#qr-codes)
70+
already satisfies this requirement.
71+
72+
### Devices SHOULD be cross-signed
73+
74+
Clients SHOULD encourage users to cross-sign their devices. This includes both
75+
when logging in a new device, and for existing devices. Clients may even go so
76+
far as to require cross-signing of devices by preventing the user from using
77+
the client until the device is cross-signed. If the user cannot cross-sign
78+
their device (for example, if they have forgotten their Secret Storage key),
79+
the client can allow users to reset their Secret Storage, cross-signing, and
80+
key backup.
81+
82+
### Clients SHOULD flag when cross-signing keys change
83+
84+
If Alice’s cross-signing keys change, Alice’s own devices MUST alert her to
85+
this fact, and prompt her to re-cross-sign those devices. If Bob is in an
86+
encrypted room with Alice, Bob’s devices SHOULD inform him of Alice’s key
87+
change and SHOULD prevent him from sending an encrypted message to Alice
88+
without acknowledging the change.
89+
90+
Bob’s clients may behave differently depending on whether Bob had previously
91+
verified Alice or not. For example, if Bob had previously verified Alice, and
92+
Alice’s keys change, Bob’s client may require Bob to re-verify, or may display
93+
a more aggressive warning.
94+
95+
Note that this MSC does not propose a mechanism for remembering previous
96+
cross-signing keys between devices. In other words if Alice changes her
97+
cross-signing keys and then Bob logs in a new device, Bob’s new device will not
98+
know that Alice’s cross-signing keys had changed, even if Bob has other devices
99+
that were previously logged in. This may result in Bob never seeing a warning
100+
about Alice's identity change, for example if Bob logs out of his last device,
101+
then Alice changes her cross-signing keys, and then Bob logs into a new device.
102+
103+
In addition, this MSC does not propose a mechanism for synchronising between
104+
devices information regarding what warnings the user has seen or acknowledged.
105+
That is, if Alice changes her cross-signing keys and Bob has multiple devices
106+
logged in, then Bob will see a warning on all his devices, and will have to
107+
dismiss the warning on all of his devices.
108+
109+
A mechanism for synchronising information between devices could be proposed by
110+
another MSC.
111+
112+
### Encrypted to-device messages SHOULD NOT be sent to non-cross-signed devices
113+
114+
Since non-cross-signed devices don’t provide any assurance that the device
115+
belongs to the user, and server admins can trivially create new devices for
116+
users, clients SHOULD NOT send encrypted to-device messages, such as room keys or
117+
secrets (via Secret Sharing), to non-cross-signed devices by default. When
118+
sending room keys, clients can use a [`m.room_key.withheld`
119+
message](https://spec.matrix.org/v1.15/client-server-api/#reporting-that-decryption-keys-are-withheld)
120+
with a code of `m.unverified` to indicate to the non-cross-signed device why it
121+
is not receiving the room key.
122+
123+
An allowed exception to this rule is that clients may provide users the ability
124+
to encrypt to specific non-cross-signed devices for development or testing
125+
purposes.
126+
127+
A future MSC may specify exceptions to this rule. For example, if a future MSC
128+
defines a device verification method that uses encrypted to-device messages,
129+
such messages would need to be sent to a user's own non-cross-signed devices, so
130+
that the user can verify their device to cross-sign it.
131+
132+
### Encrypted messages from non-cross-signed devices SHOULD be ignored
133+
134+
Similarly, clients have no assurance that encrypted messages sent from
135+
non-cross-signed devices were sent by the user, rather than an
136+
impersonator. Therefore messages sent from non-cross-signed devices cannot be
137+
trusted and SHOULD NOT be displayed to the user.
138+
139+
Again, an allowed exception to this is that clients may allow the user to
140+
override this behaviour for specific devices for development or testing
141+
purposes.
142+
143+
### Non-cryptographic devices SHOULD NOT impact E2EE behaviour
144+
145+
For the sake of clarity: non-cryptographic devices (devices which do not have
146+
device identity keys uploaded to the homeserver) should not have any impact on
147+
a client's E2EE behaviour. For all intents and purposes, non-cryptographic
148+
devices are a completely separate concept and do not exist from the perspective
149+
of the cryptography layer since they do not have identity keys, so it is
150+
impossible to send them decryption keys.
151+
152+
In particular, Matrix clients MUST NOT consider non-cryptographic devices to be
153+
equivalent to non-cross-signed cryptographic devices for purposes of enforcing
154+
E2EE policy. For example, clients SHOULD NOT warn nor refuse to send messages
155+
due to the presence of non-cryptographic devices.
156+
157+
The intent of this is to smoothly support and minimise interference from
158+
applications which choose to set up E2EE only on demand (e.g.
159+
[WorkAdventure](https://workadventu.re/article-en/managing-e2e-encryption-with-matrix-in-a-simple-way/)).
160+
Such clients should initially create a non-cryptographic device until they are
161+
ready to set up E2EE. Only when they are ready will they create the device
162+
identity keys for the device and upload them to the homeserver, converting the
163+
device into a cryptographic device and making it subject to the rules given in
164+
this MSC.
165+
166+
### Clients MAY make provisions for encrypted bridges
167+
168+
Some bridges are structured in a way such that only one user controlled by the
169+
bridge (often called the bridge bot) participates in encryption, and encrypted
170+
messages from other bridge users are encrypted by the bridge bot. Thus
171+
encrypted messages sent by one user could be encrypted by a Megolm session sent
172+
by a different user. Clients MAY accept such messages, provided the session
173+
creator's device is cross-signed. However, the client MUST annotate the message with
174+
a warning, unless the client has a way to check that the bridge bot is permitted
175+
to encrypt messages on behalf of the user.
176+
177+
[MSC4350](https://github.com/matrix-org/matrix-spec-proposals/pull/4350)
178+
presents a way for bridge users to indicate that the bridge bot is allowed to
179+
perform encryption on their behalf.
180+
181+
## Potential Issues
182+
183+
### Client support
184+
185+
If a user has devices that are not cross-signed, they will not be able to
186+
communicate with other users whose clients implement this proposal completely,
187+
due to the "Encrypted to-device messages MUST NOT be sent to non-cross-signed
188+
devices" and "Encrypted messages from non-cross-signed devices SHOULD be
189+
ignored" sections. Thus we encourage clients to implement cross-signing as soon
190+
as possible, and to encourage users to cross-sign their devices, and clients
191+
should delay the implementation of those two sections (or make it optional)
192+
until most clients have implemented cross-signing.
193+
194+
The following clients support cross-signing:
195+
196+
- Cinny
197+
- Element (all platforms), and derivatives such as Schildi Chat
198+
- Fractal
199+
- gomuks
200+
- NeoChat
201+
- Nheko
202+
- pantalaimon
203+
- Tammy
204+
- Trixnity Messenger
205+
206+
The following encryption-capable clients do not support cross-signing:
207+
208+
- kazv
209+
- Quaternion (versions prior to 0.98)
210+
211+
### Bots and application services
212+
213+
This is a special case to the issue above, but seems to be a large enough class
214+
that it deserves its own mention: support for cross-signing in bots and
215+
application services may be less common than in interactive clients. When a
216+
client fully implements this proposal, users will be unable to interact with
217+
bots and application services in encrypted rooms if they do not support
218+
cross-signing.
219+
220+
Some possible solutions for bots are:
221+
222+
- if a bot is the only device logged into a given account, the bot can create its
223+
own cross-signing keys and cross-sign its device.
224+
- the bot administrator can provide the Secret Storage key to the bot so that
225+
the bot can fetch its self-signing private key and cross-sign its device.
226+
- the bot can log its device keys so that the administrator can cross-sign it
227+
from a different device by manually comparing the device keys. Note that many
228+
clients do not have the ability to verify by comparing device keys.
229+
230+
The following bots support cross-signing:
231+
232+
- [meowlnir](https://github.com/maunium/meowlnir)
233+
- [Arnie](https://gitlab.com/andybalaam/arnie)
234+
- [maubot](https://github.com/maubot/maubot)
235+
236+
The following bot SDKs support, or plan to support, cross-signing such that any
237+
bots written using them will support cross-signing:
238+
239+
- [mautrix-go](https://github.com/mautrix/go) (planned support for Application Services)
240+
241+
## Alternatives
242+
243+
We could do nothing and leave things as they are, but the rules given in this
244+
MSC provide improved security.
245+
246+
## Security considerations
247+
248+
Warning the user about cross-signing key changes can be circumvented by a
249+
malicious server if it sends forged cross-signing keys the first time the user
250+
sees them. Therefore users should still verify other users when security is
251+
important.
252+
253+
## Unstable prefix
254+
255+
No new names are introduced, so no unstable prefix is needed.
256+
257+
## Dependencies
258+
259+
Though not strictly dependencies, other MSCs improve the behaviour of this MSC:
260+
- [Authenticated backups
261+
(MSC4048)](https://github.com/matrix-org/matrix-spec-proposals/pull/4048)
262+
will improve the user experience by ensuring that trust information is
263+
preserved when loading room keys from backup. We may also need to add
264+
information to the backup about the cross-signing status of the device,
265+
but this can be addressed in a future MSC.
266+
- [Including device keys with Olm-encrypted events
267+
(MSC4147)](https://github.com/matrix-org/matrix-spec-proposals/pull/4147)
268+
allows recipients to check the cross-signing status of devices that have been
269+
deleted.
270+
- [Permitting encryption impersonation for appservices
271+
(MSC4350)](https://github.com/matrix-org/matrix-spec-proposals/pull/4350)
272+
allows a user to assert that a bridge is allowed to encrypt for them.

0 commit comments

Comments
 (0)