Skip to content

Commit 628d53e

Browse files
andybalaamrichvdhturt2liveclokep
authored
MSC4287: Sharing key backup preference between clients (#4287)
* First draft of shared-key-backup-preference * Rename to reflect MSC number * Update MSC number in title * Small fixes and corrections * Mention the weird unstable prefix * Note that the security problem is less if clients make the setting visible * Fix wording of 'not perform key backup' * Improve wording around turning on key backups * Note that clients should notice when key backup is deleted * Note that servers can delete key backups already * Clarify that this only applies to clients that support key backup Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> * Fix extra JSON in account_data response. Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> * Note that clients don't have to monitor account data * Fix typo * Clarify the this only applies to client supporting encryption and key backup Co-authored-by: Travis Ralston <travisr@matrix.org> * Clarify that we are not requiring monitoring of the setting at all times. Co-authored-by: Patrick Cloke <clokep@users.noreply.github.com> * Allow clients to consider the setting value as they wish, rather than taking it as gospel * Note that m. in the unstable prefix was a mistake * Link to a specific spec version Co-authored-by: Travis Ralston <travisr@matrix.org> * Clarify how we can mitigate malicious server control of the setting * Avoid EITHER and OR by using MAY as suggested by @Johennes * Make sure we update the property if the client updates it * Revert "Make sure we update the property if the client updates it" This is a substantive change, which should not be applied during FCP, so reverting it. This reverts commit 395b98a. --------- Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> Co-authored-by: Travis Ralston <travisr@matrix.org> Co-authored-by: Patrick Cloke <clokep@users.noreply.github.com>
1 parent 9a49a47 commit 628d53e

1 file changed

Lines changed: 147 additions & 0 deletions

File tree

‎proposals/4287-shared-key-backup-preference.md‎

Lines changed: 147 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,147 @@
1+
# MSC4287: Sharing key backup preference between clients
2+
3+
Matrix allows for clients to [store backups of room
4+
keys](https://spec.matrix.org/v1.14/client-server-api/#server-side-key-backups)
5+
(encrypted) on the server.
6+
7+
Some users choose to disable this feature.
8+
9+
Some clients enable key backup by default, meaning that if a user signs in,
10+
their keys may be backed up even though they have chosen not to back them up on
11+
a different client. This is probably not the behaviour the user wants.
12+
13+
We describe a mechanism for remembering the user's preference in this matter,
14+
so that a new client can behave correctly without needing to be told again that
15+
the user does not want key backups.
16+
17+
## Proposal
18+
19+
We propose an event type to be stored in global account data,
20+
`m.key_backup` whose contents consist of a single field `enabled` whose value is
21+
boolean.
22+
23+
For example, if I `GET
24+
/_matrix/client/v3/user/{userId}/account_data/m.key_backup`, the response looks
25+
like:
26+
27+
```
28+
{
29+
"enabled": true
30+
}
31+
```
32+
33+
If `enabled` is `true`, key backup for new sign-ins is on. If `enabled` is
34+
`false`, key backup for new sign-ins is off. Otherwise, the value is
35+
undetermined and the client should either treat it as off, or make a choice and
36+
update the value to reflect it.
37+
38+
### Behaviour on sign-in
39+
40+
When a user signs in to a client which supports encryption and key backup:
41+
42+
* If this event type exists in account data and contains the specified property
43+
in the correct format, clients which support key backup MUST take account of
44+
its contents in their behaviour. For example, clients may automatically turn
45+
on/off key backup based on the property, or prompt the user, using the
46+
property value as a default. (Because this property is server-controlled,
47+
clients may wish to confirm the user's intention.)
48+
49+
* If this event type does not exist in account data, or if it does not contain
50+
the `enabled` property, or if the value of `enabled` is not a boolean value,
51+
clients MUST ignore the existing value and MAY decide whether or not to
52+
perform key backup, possibly based on user input.
53+
54+
### Behaviour on setting change
55+
56+
If the user turns on key backups, clients MUST set this event type in account
57+
data, to `"enabled": true`.
58+
59+
If the user turns off key backups, clients MUST set this event type in account
60+
data, to `"enabled": false`.
61+
62+
### Not actively monitoring this setting
63+
64+
We do not propose that clients actively monitor the `m.key_backup` account data
65+
and enable or disable key backup based on changes. Clients MAY monitor the
66+
setting but should be aware that changing this setting without user interaction
67+
based on choices made in a different client (or a compromised homeserver) may
68+
cause unforeseen security problems or simply be unexpected by users.
69+
70+
## Potential issues
71+
72+
It is possible that some use cases would involve a user having several clients,
73+
some of which are using key backups, and some of which are not. If we want to
74+
support that use case, we should allow some clients to opt out entirely from
75+
reading or updating this account data.
76+
77+
We are not aware of these use cases, so if any are known it would be helpful to
78+
let us know.
79+
80+
## Alternatives
81+
82+
### When the value is missing or invalid
83+
84+
There are alternative possibilities for the default behaviour (e.g. a
85+
missing/invalid event could simply mean "off") but the described behaviour is
86+
intended to be unambiguous and prevent two clients interpreting the same setting
87+
differently, while also allowing clients to choose default behaviour suitable
88+
for their audience.
89+
90+
### Dynamically reacting to changes
91+
92+
As specified, this only affects client behaviour when a user signs in. We could
93+
specify that clients must watch the value of this account data and dynamically
94+
change their key backup behaviour when it changes. This would increase the
95+
severity of the security issues discussed below. Whether this behaviour would be
96+
more or less surprising for the user is a potential discussion point.
97+
98+
Note that clients should already notice if a key backup is deleted, because
99+
attempts to upload new keys will start failing.
100+
101+
### A proper unstable prefix
102+
103+
Because an existing implementation exists, the proposed unstable prefix has
104+
different semantics from the final proposal. If this is deemed unacceptable, a
105+
more normal unstable prefix could be used.
106+
107+
## Security considerations
108+
109+
Unencrypted account data is under the control of the server, so a malicious
110+
server could:
111+
112+
* increase the user's attack surface by tricking clients into performing key backups
113+
against the user's will, or
114+
115+
* cause data loss by tricking clients into not performing key backups. (But
116+
servers can delete data from key backups at will, so this seems unimportant.)
117+
118+
This can be mitigated if clients make it visible to users when the
119+
server-provided setting is going to affect their behaviour e.g. by prompting the
120+
user for confirmation.
121+
122+
## Unstable prefix
123+
124+
This is currently partially implemented in Element clients using a
125+
reversed-sense format like:
126+
127+
```
128+
{
129+
"m.org.matrix.custom.backup_disabled" { "disabled": true }
130+
}
131+
```
132+
133+
so we propose to use this form as an unstable prefix, and reverse the sense of
134+
the boolean when this feature is stabilised.
135+
136+
NOTE: the use of the `m.` prefix for this property name was a mistake since
137+
[identifiers starting with the characters m. are reserved for use by the official Matrix specification](https://spec.matrix.org/v1.17/appendices/#common-namespaced-identifier-grammar).
138+
139+
## Dependencies
140+
141+
None
142+
143+
## Implementations
144+
145+
This is partially implemented (with the reverse-sense boolean) in Element
146+
clients. The part that is currently not implemented is proactively setting the
147+
value on sign-in.

0 commit comments

Comments
 (0)
⚡