wholetrans/docs-matrix-spec
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Specify fallback keys (#3615)

Browse source 
* Specify fallback keys

MSC: https://github.com/matrix-org/matrix-doc/pull/2732

* changelog

* Appease spell check

* Fine, let's appease the spellcheck this way

* Apply suggestions from code review

Co-authored-by: Hubert Chathi <hubert@uhoreg.ca>

* Fix intro

* word wrap

Co-authored-by: Hubert Chathi <hubert@uhoreg.ca>
This commit is contained in:
Travis Ralston 2022-01-04 20:35:21 -07:00 • committed by GitHub
parent 26e0765159
commit 224773dc6a
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
4 changed files with 84 additions and 6 deletions
Download patch file Download diff file Expand all files Collapse all files

2
.github/_typos.toml vendored
View file

@ -9,4 +9,4 @@ au1ba7o = "au1ba7o"
[default.extend-words]
Appy = "Appy"
fo = "fo"
fo = "fo"

1
changelogs/client_server/newsfragments/3615.feature Normal file
View file

@ -0,0 +1 @@
Add support for fallback keys (optional keys used once one-time keys run out), as per [MSC2732](https://github.com/matrix-org/matrix-doc/pull/2732).

50
content/client-server-api/modules/end_to_end_encryption.md
View file

@ -117,9 +117,13 @@ must include the public part of the device's Ed25519 key, and must be
signed by that key, as described in [Signing
JSON](/appendices/#signing-json).
One-time keys are also uploaded to the homeserver using the
One-time and fallback keys are also uploaded to the homeserver using the
[`/keys/upload`](/client-server-api/#post_matrixclientv3keysupload) API.
{{% added-in v="1.2" %}} Fallback keys are similar to one-time keys, but
are not consumed once used. They are only used when the device has run out
of one-time keys, and can be replaced by a new fallback key.
Devices must store the private part of each key they upload. They can
discard the private part of a one-time key when they receive a message
using that key. However it's possible that a one-time key given out by a
@ -128,6 +132,24 @@ never know that it can discard the key. Therefore a device could end up
trying to store too many private keys. A device that is trying to store
too many private keys may discard keys starting with the oldest.
{{% boxes/warning %}}
Fallback keys are used to prevent one-time key exhaustion when devices
are offline/unable to upload additional keys, though sessions started using
fallback keys could be vulnerable to replay attacks.
{{% /boxes/warning %}}
{{% boxes/warning %}}
Clients should not store the private half of fallback keys indefinitely
to avoid situations where attackers can decrypt past messages sent using
that fallback key.
Instead, clients should keep the private keys for at most 2 fallback keys:
the current, unused, fallback key and the key immediately preceding it.
Once the client is reasonably certain it has received all messages that
used the old fallback key, such as after an hour since the first message,
it should remove that fallback key.
{{% /boxes/warning %}}
##### Tracking the device list for a user
Before Alice can send an encrypted message to Bob, she needs a list of
@ -344,6 +366,11 @@ A homeserver should rate-limit the number of one-time keys that a given
user or remote server can claim. A homeserver should discard the public
part of a one time key once it has given that key to another user.
{{% added-in v="1.2" %}} If the device has run out of one-time keys which
can be claimed, the homeserver will return the fallback key (if one was
uploaded). Fallback keys are not deleted once used and should be replaced
by the device when they are able to upload more one-time keys.
#### Device verification
Before Alice sends Bob encrypted data, or trusts data received from him,
@ -1603,10 +1630,23 @@ It also adds a `one_time_keys_count` property. Note the spelling
difference with the `one_time_key_counts` property in the
[`/keys/upload`](/client-server-api/#post_matrixclientv3keysupload) response.
| Parameter | Type | Description |
|----------------------------|--------------------|------------------------------------------------------------------------------------------------------------------------|
| device_lists | DeviceLists | Optional. Information on e2e device updates. Note: only present on an incremental sync. |
| device_one_time_keys_count | {string: integer} | Optional. For each key algorithm, the number of unclaimed one-time keys currently held on the server for this device. |
{{% added-in v="1.2" %}} Finally, a `device_unused_fallback_key_types` property
is added to list the key algorithms where the device has a fallback key that
*has not* been used in a [`/keys/claim`](/client-server-api/#post_matrixclientv3keysclaim)
response. When a previously uploaded fallback key's algorithm is missing
from this list, the device should upload a replacement key alongside any
necessary one-time keys to avoid the fallback key's further usage. This
property is required for inclusion, though previous versions of the
specification did not have it. In addition to `/versions`, this can be
a way to identify the server's support for fallback keys.
| Parameter | Type | Description |
|----------------------------------|--------------------|------------------------------------------------------------------------------------------------------------------------|
| device_lists | DeviceLists | Optional. Information on e2e device updates. Note: only present on an incremental sync. |
| device_one_time_keys_count | {string: integer} | Optional. For each key algorithm, the number of unclaimed one-time keys currently held on the server for this device. |
| device_unused_fallback_key_types | [string] | **Required.** The unused fallback key algorithms. |
`DeviceLists`

37
data/api/client-server/keys.yaml
View file

@ -100,6 +100,40 @@ paths:
}
}
}
fallback_keys:
type: object
x-addedInMatrixVersion: "1.2"
description: |-
The public key which should be used if the device's one-time keys
are exhausted. The fallback key is not deleted once used, but should
be replaced when additional one-time keys are being uploaded. The
server will notify the client of the fallback key being used through
`/sync`.
There can only be at most one key per algorithm uploaded, and the server
will only persist one key per algorithm.
When uploading a signed key, an additional `fallback: true` key should
be included to denote that the key is a fallback key.
May be absent if a new fallback key is not required.
additionalProperties:
type:
- string
- object
# XXX: We can't define an actual object here - see one_time_keys.
example: {
"curve25519:AAAAAG": "/qyvZvwjiTxGdGU0RCguDCLeR+nmsb3FfNG3/Ve4vU8",
"signed_curve25519:AAAAGj": {
"key": "zKbLg+NrIjpnagy+pIY6uPL4ZwEG2v+8F9lmgsnlZzs",
"fallback": true,
"signatures": {
"@alice:example.com": {
"ed25519:JLAFKJWSCS": "FLWxXqGbwrb8SM3Y795eB6OA8bwBcoMZFXBqnTn58AYWZSqiD45tlBVcDa2L7RwdKXebW/VzDlnfVJ+9jok1Bw"
}
}
}
}
responses:
200:
description:
@ -378,6 +412,9 @@ paths:
See the [key algorithms](/client-server-api/#key-algorithms) section for information
on the Key Object format.
If necessary, the claimed key might be a fallback key. Fallback
keys are re-used by the server until replaced by the device.
additionalProperties:
type: object
additionalProperties: