mirror of
https://github.com/matrix-org/matrix-spec
synced 2026-04-18 00:54:10 +02:00
Compare commits
3 commits
c6f815d4ad
...
c120e7efea
| Author | SHA1 | Date | |
|---|---|---|---|
|
c120e7efea | ||
|
|
9c313b099f | ||
|
|
f42ce28bfe |
1
changelogs/client_server/newsfragments/2187.feature
Normal file
1
changelogs/client_server/newsfragments/2187.feature
Normal file
|
|
@ -0,0 +1 @@
|
|||
Add the `use_state_after` query parameter and `state_after` response property to `GET /sync`, as per [MSC4222](https://github.com/matrix-org/matrix-spec-proposals/issues/4222).
|
||||
|
|
@ -0,0 +1 @@
|
|||
Clarify terminology for keys in cross-signing module.
|
||||
|
|
@ -93,7 +93,7 @@ Example:
|
|||
```
|
||||
|
||||
`ed25519` and `curve25519` keys are used for [device keys](#device-keys).
|
||||
Additionally, `ed25519` keys are used for [cross-signing keys](#cross-signing).
|
||||
Additionally, `ed25519` keys are keys used for [cross-signing](#cross-signing).
|
||||
|
||||
`signed_curve25519` keys are used for [one-time and fallback keys](#one-time-and-fallback-keys).
|
||||
|
||||
|
|
@ -675,7 +675,7 @@ The process between Alice and Bob verifying each other would be:
|
|||
15. Assuming they match, Alice and Bob's devices each calculate Message
|
||||
Authentication Codes (MACs) for:
|
||||
* Each of the keys that they wish the other user to verify (usually their
|
||||
device ed25519 key and their master cross-signing key).
|
||||
device ed25519 key and their master key, see below).
|
||||
* The complete list of key IDs that they wish the other user to verify.
|
||||
|
||||
The MAC calculation is defined [below](#mac-calculation).
|
||||
|
|
@ -931,16 +931,16 @@ and can be translated online:
|
|||
Rather than requiring Alice to verify each of Bob's devices with each of
|
||||
her own devices and vice versa, the cross-signing feature allows users
|
||||
to sign their device keys such that Alice and Bob only need to verify
|
||||
once. With cross-signing, each user has a set of cross-signing keys that
|
||||
once. With cross-signing, each user has a set of ed25519 key pairs that
|
||||
are used to sign their own device keys and other users' keys, and can be
|
||||
used to trust device keys that were not verified directly.
|
||||
|
||||
Each user has three ed25519 key pairs for cross-signing:
|
||||
Each user has three ed25519 key pairs used for cross-signing:
|
||||
|
||||
- a master key (MSK) that serves as the user's identity in
|
||||
cross-signing and signs their other cross-signing keys;
|
||||
- a master key (MK) that serves as the user's identity in
|
||||
cross-signing and signs their user-signing and self-signing keys;
|
||||
- a user-signing key (USK) -- only visible to the user that it belongs
|
||||
to --that signs other users' master keys; and
|
||||
to -- that signs other users' master keys; and
|
||||
- a self-signing key (SSK) that signs the user's own device keys.
|
||||
|
||||
The master key may also be used to sign other items such as the backup
|
||||
|
|
@ -950,13 +950,15 @@ previously verified Bob's device and Bob's device has signed his master
|
|||
key, then Alice's device can trust Bob's master key, and she can sign it
|
||||
with her user-signing key.
|
||||
|
||||
Users upload their cross-signing keys to the server using [POST
|
||||
Users upload the public part of their master, user-signing and self-signing
|
||||
key to the server using [POST
|
||||
/\_matrix/client/v3/keys/device\_signing/upload](/client-server-api/#post_matrixclientv3keysdevice_signingupload). When Alice uploads
|
||||
new cross-signing keys, her user ID will appear in the `changed`
|
||||
new keys, her user ID will appear in the `changed`
|
||||
property of the `device_lists` field of the `/sync` of response of all
|
||||
users who share an encrypted room with her. When Bob sees Alice's user
|
||||
ID in his `/sync`, he will call [POST /\_matrix/client/v3/keys/query](/client-server-api/#post_matrixclientv3keysquery)
|
||||
to retrieve Alice's device and cross-signing keys.
|
||||
to retrieve Alice's device keys, as well as their master, user-signing and
|
||||
self-signing key.
|
||||
|
||||
If Alice has a device and wishes to send an encrypted message to Bob,
|
||||
she can trust Bob's device if:
|
||||
|
|
@ -971,13 +973,13 @@ The following diagram illustrates how keys are signed:
|
|||
|
||||
```
|
||||
+------------------+ .................. +----------------+
|
||||
| +--------------+ | .................. : | +------------+ |
|
||||
| | v v v : : v v v | |
|
||||
| | +-----------+ : : +-----------+ | |
|
||||
| | | Alice MSK | : : | Bob MSK | | |
|
||||
| | +-----------+ : : +-----------+ | |
|
||||
| | | : : : : | | |
|
||||
| | +--+ :... : : ...: +--+ | |
|
||||
| +--------------+ | ................... : | +------------+ |
|
||||
| | v v v : : v v v | |
|
||||
| | +----------+ : : +----------+ | |
|
||||
| | | Alice MK | : : | Bob MK | | |
|
||||
| | +----------+ : : +----------+ | |
|
||||
| | | : : : : | | |
|
||||
| | +--+ :.... : : ...: +---+ | |
|
||||
| | v v : : v v | |
|
||||
| | +-----------+ ............. : : ............. +-----------+ | |
|
||||
| | | Alice SSK | : Alice USK : : : : Bob USK : | Bob SSK | | |
|
||||
|
|
@ -1004,11 +1006,11 @@ signatures that she cannot see:
|
|||
+------------------+ +----------------+ +----------------+
|
||||
| +--------------+ | | | | +------------+ |
|
||||
| | v v | v v v | |
|
||||
| | +-----------+ | +-----------+ | |
|
||||
| | | Alice MSK | | | Bob MSK | | |
|
||||
| | +-----------+ | +-----------+ | |
|
||||
| | | | | | | |
|
||||
| | +--+ +--+ | +--+ | |
|
||||
| | +----------+ | +----------+ | |
|
||||
| | | Alice MK | | | Bob MK | | |
|
||||
| | +----------+ | +----------+ | |
|
||||
| | | | | | | |
|
||||
| | +--+ +---+ | +---+ | |
|
||||
| | v v | v | |
|
||||
| | +-----------+ +-----------+ | +-----------+ | |
|
||||
| | | Alice SSK | | Alice USK | | | Bob SSK | | |
|
||||
|
|
@ -1024,16 +1026,16 @@ signatures that she cannot see:
|
|||
```
|
||||
|
||||
[Verification methods](#device-verification) can be used to verify a
|
||||
user's master key by using the master public key, encoded using unpadded
|
||||
user's master key by treating the master public key, encoded using unpadded
|
||||
base64, as the device ID, and treating it as a normal device. For
|
||||
example, if Alice and Bob verify each other using SAS, Alice's
|
||||
`m.key.verification.mac` message to Bob may include
|
||||
`"ed25519:alices+master+public+key": "alices+master+public+key"` in the
|
||||
`mac` property. Servers therefore must ensure that device IDs will not
|
||||
collide with cross-signing public keys.
|
||||
collide with public keys used for cross-signing.
|
||||
|
||||
The cross-signing private keys can be stored on the server or shared with other
|
||||
devices using the [Secrets](#secrets) module. When doing so, the master,
|
||||
Using the [Secrets](#secrets) module the private keys used for cross-signing can
|
||||
be stored on the server or shared with other devices. When doing so, the master,
|
||||
user-signing, and self-signing keys are identified using the names
|
||||
`m.cross_signing.master`, `m.cross_signing.user_signing`, and
|
||||
`m.cross_signing.self_signing`, respectively, and the keys are base64-encoded
|
||||
|
|
@ -1052,14 +1054,14 @@ If a user's client sees that any other user has changed their master
|
|||
key, that client must notify the user about the change before allowing
|
||||
communication between the users to continue.
|
||||
|
||||
Since device key IDs (`ed25519:DEVICE_ID`) and cross-signing key IDs
|
||||
(`ed25519:PUBLIC_KEY`) occupy the same namespace, clients must ensure that they
|
||||
use the correct keys when verifying.
|
||||
Since device key IDs (`ed25519:DEVICE_ID`) as well as master, user-signing and
|
||||
self-signing key IDs (`ed25519:PUBLIC_KEY`) occupy the same namespace, clients
|
||||
must ensure that they use the correct keys when verifying.
|
||||
|
||||
While servers MUST not allow devices to have the same IDs as cross-signing
|
||||
keys, a malicious server could construct such a situation, so clients must not
|
||||
rely on the server being well-behaved and should take the following precautions
|
||||
against this.
|
||||
While servers MUST not allow devices to have the same IDs as keys used for
|
||||
cross-signing, a malicious server could construct such a situation, so clients
|
||||
must not rely on the server being well-behaved and should take the following
|
||||
precautions against this:
|
||||
|
||||
1. Clients MUST refer to keys by their public keys during the verification
|
||||
process, rather than only by the key ID.
|
||||
|
|
@ -1067,7 +1069,8 @@ against this.
|
|||
verification process, and ensure that they do not change in the course of
|
||||
verification.
|
||||
3. Clients SHOULD also display a warning and MUST refuse to verify a user when
|
||||
they detect that the user has a device with the same ID as a cross-signing key.
|
||||
they detect that the user has a device with the same ID as a key used for
|
||||
cross-signing.
|
||||
|
||||
A user's user-signing and self-signing keys are intended to be easily
|
||||
replaceable if they are compromised by re-issuing a new key signed by
|
||||
|
|
@ -1104,7 +1107,7 @@ user-signing keys.
|
|||
|
||||
Verifying by QR codes provides a quick way to verify when one of the parties
|
||||
has a device capable of scanning a QR code. The QR code encodes both parties'
|
||||
master signing keys as well as a random shared secret that is used to allow
|
||||
master keys as well as a random shared secret that is used to allow
|
||||
bi-directional verification from a single scan.
|
||||
|
||||
To advertise the ability to show a QR code, clients use the names
|
||||
|
|
@ -1202,15 +1205,14 @@ The binary segment MUST be of the following form:
|
|||
bytes of the ID as a UTF-8 string
|
||||
- the ID encoded as a UTF-8 string
|
||||
- the first key, as 32 bytes. The key to use depends on the mode field:
|
||||
- if `0x00` or `0x01`, then the current user's own master cross-signing public key
|
||||
- if `0x00` or `0x01`, then the current user's own master public key
|
||||
- if `0x02`, then the current device's Ed25519 signing key
|
||||
- the second key, as 32 bytes. The key to use depends on the mode field:
|
||||
- if `0x00`, then what the device thinks the other user's master
|
||||
cross-signing public key is
|
||||
public key is
|
||||
- if `0x01`, then what the device thinks the other device's Ed25519 signing
|
||||
public key is
|
||||
- if `0x02`, then what the device thinks the user's master cross-signing public
|
||||
key is
|
||||
- if `0x02`, then what the device thinks the user's master public key is
|
||||
- a random shared secret, as a sequence of bytes. It is suggested to use a secret
|
||||
that is about 8 bytes long. Note: as we do not share the length of the
|
||||
secret, and it is not a fixed size, clients will just use the remainder of
|
||||
|
|
@ -1221,14 +1223,14 @@ For example, if Alice displays a QR code encoding the following binary data:
|
|||
```
|
||||
"MATRIX" |ver|mode| len | event ID
|
||||
4D 41 54 52 49 58 02 00 00 2D 21 41 42 43 44 ...
|
||||
| user's cross-signing key | other user's cross-signing key | shared secret
|
||||
00 01 02 03 04 05 06 07 ... 10 11 12 13 14 15 16 17 ... 20 21 22 23 24 25 26 27
|
||||
| the first key | the second key | shared secret
|
||||
00 01 02 03 04 05 06 07 ... 10 11 12 13 14 15 16 17 ... 20 21 22 23 24 25 26 27
|
||||
```
|
||||
|
||||
this indicates that Alice is verifying another user (say Bob), in response to
|
||||
the request from event "$ABCD...", her cross-signing key is
|
||||
Mode `0x00` indicates that Alice is verifying another user (say Bob), in
|
||||
response to the request from event "$ABCD...", her master key is
|
||||
`0001020304050607...` (which is "AAECAwQFBg..." in base64), she thinks that
|
||||
Bob's cross-signing key is `1011121314151617...` (which is "EBESExQVFh..." in
|
||||
Bob's master key is `1011121314151617...` (which is "EBESExQVFh..." in
|
||||
base64), and the shared secret is `2021222324252627` (which is "ICEiIyQlJic" in
|
||||
base64).
|
||||
|
||||
|
|
@ -1300,8 +1302,8 @@ one of its variants.
|
|||
Clients must only store keys in backups after they have ensured that the
|
||||
`auth_data` is trusted. This can be done either by:
|
||||
|
||||
- checking that it is signed by the user's [master cross-signing
|
||||
key](#cross-signing) or by a verified device belonging to the same user, or
|
||||
- checking that it is signed by the user's [master key](#cross-signing)
|
||||
or by a verified device belonging to the same user, or
|
||||
- deriving the public key from a private key that it obtained from a trusted
|
||||
source. Trusted sources for the private key include the user entering the
|
||||
key, retrieving the key stored in [secret storage](#secret-storage), or
|
||||
|
|
@ -1786,13 +1788,14 @@ a way to identify the server's support for fallback keys.
|
|||
|
||||
| Parameter | Type | Description |
|
||||
|------------|-----------|------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|
||||
| changed | [string] | List of users who have updated their device identity or cross-signing keys, or who now share an encrypted room with the client since the previous sync response. |
|
||||
| changed | [string] | List of users who have updated their device identity or their master, self-signing or user-signing keys, or who now share an encrypted room with the client since the previous sync response. |
|
||||
| left | [string] | List of users with whom we do not share any encrypted rooms anymore since the previous sync response. |
|
||||
|
||||
{{% boxes/note %}}
|
||||
For optimal performance, Alice should be added to `changed` in Bob's
|
||||
sync only when she updates her devices or cross-signing keys, or when
|
||||
Alice and Bob now share a room but didn't share any room previously.
|
||||
sync only when she updates her devices or master, self-signing or
|
||||
user-signing keys, or when Alice and Bob now share a room but didn't
|
||||
share any room previously.
|
||||
However, for the sake of simpler logic, a server may add Alice to
|
||||
`changed` when Alice and Bob share a new room, even if they previously
|
||||
already shared a room.
|
||||
|
|
|
|||
|
|
@ -21,16 +21,16 @@ paths:
|
|||
x-addedInMatrixVersion: "1.1"
|
||||
x-changedInMatrixVersion:
|
||||
"1.11": UIA is not always required for this endpoint.
|
||||
summary: Upload cross-signing keys.
|
||||
summary: Upload keys used for cross-signing.
|
||||
description: |-
|
||||
Publishes cross-signing keys for the user.
|
||||
Publishes keys used for cross-signing for the user.
|
||||
|
||||
This API endpoint uses the [User-Interactive Authentication API](/client-server-api/#user-interactive-authentication-api).
|
||||
|
||||
User-Interactive Authentication MUST be performed, except in these cases:
|
||||
- there is no existing cross-signing master key uploaded to the homeserver, OR
|
||||
- there is an existing cross-signing master key and it exactly matches the
|
||||
cross-signing master key provided in the request body. If there are any additional
|
||||
- there is no existing master key uploaded to the homeserver, OR
|
||||
- there is an existing master key and it exactly matches the
|
||||
master key provided in the request body. If there are any additional
|
||||
keys provided in the request (self-signing key, user-signing key) they MUST also
|
||||
match the existing keys stored on the server. In other words, the request contains
|
||||
no new keys.
|
||||
|
|
|
|||
|
|
@ -13,7 +13,7 @@
|
|||
# limitations under the License.
|
||||
type: object
|
||||
title: CrossSigningKey
|
||||
description: Cross signing key
|
||||
description: Key used for cross signing
|
||||
properties:
|
||||
user_id:
|
||||
type: string
|
||||
|
|
|
|||
|
|
@ -219,7 +219,7 @@ paths:
|
|||
x-addedInMatrixVersion: "1.1"
|
||||
type: object
|
||||
description: |-
|
||||
Information on the master cross-signing keys of the queried users.
|
||||
Information on the master keys of the queried users.
|
||||
A map from user ID, to master key information. For each key, the
|
||||
information returned will be the same as uploaded via
|
||||
`/keys/device_signing/upload`, along with the signatures
|
||||
|
|
|
|||
|
|
@ -117,6 +117,31 @@ paths:
|
|||
example: 30000
|
||||
schema:
|
||||
type: integer
|
||||
- in: query
|
||||
name: use_state_after
|
||||
x-addedInMatrixVersion: "1.16"
|
||||
description: |-
|
||||
Controls whether to receive state changes between the previous sync
|
||||
and the **start** of the timeline, or between the previous sync and
|
||||
the **end** of the timeline.
|
||||
|
||||
If this is set to `true`, servers MUST respond with the state
|
||||
between the previous sync and the **end** of the timeline in
|
||||
`state_after` and MUST omit `state`.
|
||||
|
||||
If `false`, servers MUST respond with the state between the previous
|
||||
sync and the **start** of the timeline in `state` and MUST omit
|
||||
`state_after`.
|
||||
|
||||
Even if this is set to `true`, clients MUST update their local state
|
||||
with events in `state` and `timeline` if `state_after` is missing in
|
||||
the response, for compatibility with servers that don't support this
|
||||
parameter.
|
||||
|
||||
By default, this is `false`.
|
||||
example: false
|
||||
schema:
|
||||
type: boolean
|
||||
responses:
|
||||
"200":
|
||||
description: The initial snapshot or delta for the client to use to update their
|
||||
|
|
@ -197,16 +222,50 @@ paths:
|
|||
type: object
|
||||
description: |-
|
||||
Updates to the state, between the time indicated by
|
||||
the `since` parameter, and the start of the
|
||||
`timeline` (or all state up to the start of the
|
||||
the `since` parameter, and the **start** of the
|
||||
`timeline` (or all state up to the **start** of the
|
||||
`timeline`, if `since` is not given, or
|
||||
`full_state` is true).
|
||||
|
||||
N.B. state updates for `m.room.member` events will
|
||||
{{% boxes/note %}}
|
||||
State updates for `m.room.member` events will
|
||||
be incomplete if `lazy_load_members` is enabled in
|
||||
the `/sync` filter, and only return the member events
|
||||
required to display the senders of the timeline events
|
||||
in this response.
|
||||
{{% /boxes/note %}}
|
||||
|
||||
MUST be omitted if `use_state_after` was set to `true`
|
||||
in the request.
|
||||
allOf:
|
||||
- $ref: definitions/state_event_batch.yaml
|
||||
state_after:
|
||||
title: State
|
||||
type: object
|
||||
x-addedInMatrixVersion: "1.16"
|
||||
description: |-
|
||||
Updates to the state, between the time indicated by
|
||||
the `since` parameter, and the **end** of the
|
||||
`timeline` (or all state up to the **end** of the
|
||||
`timeline`, if `since` is not given, or
|
||||
`full_state` is true).
|
||||
|
||||
{{% boxes/note %}}
|
||||
State updates for `m.room.member` events will
|
||||
be incomplete if `lazy_load_members` is enabled in
|
||||
the `/sync` filter, and only return the member events
|
||||
required to display the senders of the timeline events
|
||||
in this response.
|
||||
{{% /boxes/note %}}
|
||||
|
||||
If this field is set, even if it is empty, clients MUST
|
||||
only update their local state with events in this list,
|
||||
and MUST NOT update their local state with events in
|
||||
`timeline`. If this field is not set, clients MUST update
|
||||
their local state with events in `state` and `timeline`.
|
||||
|
||||
**Required** if `use_state_after` was set to `true` in the
|
||||
request, even if it is empty.
|
||||
allOf:
|
||||
- $ref: definitions/state_event_batch.yaml
|
||||
timeline:
|
||||
|
|
@ -353,7 +412,28 @@ paths:
|
|||
state:
|
||||
title: State
|
||||
type: object
|
||||
description: The state updates for the room up to the start of the timeline.
|
||||
description: |-
|
||||
The state updates for the room up to the **start** of the timeline.
|
||||
|
||||
MUST be omitted if `use_state_after` was set to `true` in the
|
||||
request.
|
||||
allOf:
|
||||
- $ref: definitions/state_event_batch.yaml
|
||||
state_after:
|
||||
title: State
|
||||
type: object
|
||||
x-addedInMatrixVersion: "1.16"
|
||||
description: |-
|
||||
The state updates for the room up to the **end** of the timeline.
|
||||
|
||||
If this field is set, even if it is empty, clients MUST only
|
||||
update their local state with events in this list, and MUST NOT
|
||||
update their local state with events in `timeline`. If this field
|
||||
is not set, clients MUST update their local state with events in
|
||||
`state` and `timeline`.
|
||||
|
||||
**Required** if `use_state_after` was set to `true` in the
|
||||
request, even if it is empty.
|
||||
allOf:
|
||||
- $ref: definitions/state_event_batch.yaml
|
||||
timeline:
|
||||
|
|
|
|||
|
|
@ -17,7 +17,7 @@ type: object
|
|||
title: m.signing_key_update
|
||||
description: |-
|
||||
An EDU that lets servers push details to each other when one of their users
|
||||
updates their cross-signing keys.
|
||||
updates their keys used for cross-signing.
|
||||
allOf:
|
||||
- $ref: ../edu.yaml
|
||||
- type: object
|
||||
|
|
@ -34,7 +34,7 @@ allOf:
|
|||
properties:
|
||||
user_id:
|
||||
type: string
|
||||
description: The user ID whose cross-signing keys have changed.
|
||||
description: The user ID whose keys have changed.
|
||||
example: "@alice:example.com"
|
||||
master_key:
|
||||
allOf:
|
||||
|
|
|
|||
|
|
@ -79,7 +79,7 @@ paths:
|
|||
- keys
|
||||
master_key:
|
||||
type: object
|
||||
description: The user\'s master cross-signing key.
|
||||
description: The user\'s master key.
|
||||
allOf:
|
||||
- $ref: ../client-server/definitions/cross_signing_key.yaml
|
||||
- example:
|
||||
|
|
|
|||
|
|
@ -194,7 +194,7 @@ paths:
|
|||
x-addedInMatrixVersion: "1.1"
|
||||
type: object
|
||||
description: |-
|
||||
Information on the master cross-signing keys of the queried users.
|
||||
Information on the master keys of the queried users.
|
||||
A map from user ID, to master key information. For each key, the
|
||||
information returned will be the same as uploaded via
|
||||
`/keys/device_signing/upload`, along with the signatures
|
||||
|
|
|
|||
Loading…
Reference in a new issue