mirror of
https://github.com/matrix-org/matrix-spec
synced 2026-04-08 12:24:09 +02:00
Compare commits
6 commits
ae45d77ef1
...
1b6f57b94f
| Author | SHA1 | Date | |
|---|---|---|---|
|
1b6f57b94f | ||
|
|
be21886a73 | ||
|
|
a8d8990646 | ||
|
|
d0e5768d1d | ||
|
|
580298895b | ||
|
|
57a1d5ad0e |
1
changelogs/client_server/newsfragments/2301.feature
Normal file
1
changelogs/client_server/newsfragments/2301.feature
Normal file
|
|
@ -0,0 +1 @@
|
|||
Add recommendation about excluding non-cross-signed devices from encrypted conversations, as per [MSC4153](https://github.com/matrix-org/matrix-spec-proposals/pull/4153).
|
||||
|
|
@ -0,0 +1 @@
|
|||
Clarify terminology for keys in cross-signing module.
|
||||
|
|
@ -0,0 +1 @@
|
|||
Add 404 responses to the OpenAPI of `GET /login` and `GET /auth_metadata` endpoints. The responses were already defined in text but not written in OpenAPI.
|
||||
|
|
@ -0,0 +1 @@
|
|||
Clarify meaning of floating-point powerlevels.
|
||||
1
changelogs/server_server/newsfragments/2319.removal
Normal file
1
changelogs/server_server/newsfragments/2319.removal
Normal file
|
|
@ -0,0 +1 @@
|
|||
Remove `/v1/send_join` and `/v1/send_leave`, as per [MSC4376](https://github.com/matrix-org/matrix-spec-proposals/pull/4376).
|
||||
|
|
@ -5,6 +5,91 @@ Matrix optionally supports end-to-end encryption, allowing rooms to be
|
|||
created whose conversation contents are not decryptable or interceptable
|
||||
on any of the participating homeservers.
|
||||
|
||||
#### Recommended client behaviour
|
||||
|
||||
{{% added-in v="1.18" %}}
|
||||
|
||||
While clients are able to choose what encryption features they implement based
|
||||
on their threat model, this section recommends behaviours that will improve the
|
||||
overall user experience and security of encrypted conversations.
|
||||
|
||||
While a user may be unable to [verify](#device-verification) every other user
|
||||
that they communicate with, or may be unaware of the need to verify other users,
|
||||
[cross-signing](#cross-signing) gives some measure of protection and so SHOULD
|
||||
be used where possible. In particular, clients SHOULD implement the following
|
||||
recommendations.
|
||||
|
||||
* Clients SHOULD create new [cross-signing keys](#cross-signing) for users who
|
||||
do not yet have cross-signing keys.
|
||||
* Clients SHOULD encourage users to set up their [Secret Storage](#storage) to
|
||||
avoid needing to reset their cryptographic identity in case the user does not
|
||||
have an existing device that can [share the secrets](#sharing) with the new
|
||||
device. The user's Secret Storage SHOULD contain the user's cross-signing
|
||||
private keys and the [key backup](#server-side-key-backups) decryption key
|
||||
(if the user is using key backup). The user's Secret Storage SHOULD have a
|
||||
[default key](#key-storage) (a key referred to by
|
||||
`m.secret_storage.default_key`) that encrypts the private cross-signing keys
|
||||
and key backup decryption key (if available).
|
||||
* Clients SHOULD encourage users to [cross-sign](#cross-signing) 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](#storage), cross-signing keys, and [key backup](#server-side-key-backups).
|
||||
* When Alice [verifies](#device-verification) Bob, the verification SHOULD
|
||||
verify their [cross-signing keys](#cross-signing). Any flow between different
|
||||
users that does not verify the users' cross-signing keys (it verifies only the
|
||||
device keys) is deprecated.
|
||||
* Clients SHOULD flag when [cross-signing keys](#cross-signing) 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](#device-verification)
|
||||
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.
|
||||
* Clients SHOULD NOT send encrypted [to-device](#send-to-device-messaging)
|
||||
messages, such as [room keys](#sharing-keys-between-devices) or [secrets](#secrets)
|
||||
(via [Secret Sharing](#sharing)), to [non-cross-signed](#cross-signing)
|
||||
devices by default. 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. When sending room keys, clients can use a
|
||||
[`m.room_key.withheld`](#mroom_keywithheld) message with a code of
|
||||
`m.unverified` to indicate to the non-cross-signed device why it is not
|
||||
receiving the room key.
|
||||
|
||||
Note that clients cannot selectively send room events only to cross-signed
|
||||
devices. The only way to exclude non-cross-signed devices from encrypted
|
||||
conversations is to not send the room keys so those devices won't be able to
|
||||
decrypt the messages.
|
||||
* Similarly, messages sent from [non-cross-signed](#cross-signing) devices
|
||||
cannot be trusted and SHOULD NOT be displayed to the user. Clients have no
|
||||
assurance that encrypted messages sent from non-cross-signed devices were sent
|
||||
by the user, rather than an impersonator.
|
||||
* Matrix clients MUST NOT consider non-cryptographic devices (devices which do
|
||||
not have [device identity keys](#device-keys) uploaded to the homeserver) to
|
||||
be equivalent to [non-cross-signed](#cross-signing) 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. 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.
|
||||
* 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](#mmegolmv1aes-sha2) session sent by
|
||||
a different user. Clients MAY accept such messages, provided the session
|
||||
creator's device is [cross-signed](#cross-signing). 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. Future
|
||||
MSCs such as [MSC4350](https://github.com/matrix-org/matrix-spec-proposals/pull/4350)
|
||||
may provide a secure way to allow such impersonation.
|
||||
|
||||
#### Key Distribution
|
||||
|
||||
Encryption and Authentication in Matrix is based around public-key
|
||||
|
|
@ -93,7 +178,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 used for [cross-signing](#cross-signing).
|
||||
|
||||
`signed_curve25519` keys are used for [one-time and fallback keys](#one-time-and-fallback-keys).
|
||||
|
||||
|
|
@ -678,8 +763,11 @@ The process between Alice and Bob verifying each other would be:
|
|||
their devices if they match or not.
|
||||
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).
|
||||
* {{% changed-in v="1.18" %}} Each of the keys that they wish the other user
|
||||
to verify (usually their device ed25519 key and their master signing key,
|
||||
see below). The master signing key SHOULD be included when two different
|
||||
users are verifying each other. Verifying individual devices of other
|
||||
users is deprecated.
|
||||
* The complete list of key IDs that they wish the other user to verify.
|
||||
|
||||
The MAC calculation is defined [below](#mac-calculation).
|
||||
|
|
@ -935,40 +1023,42 @@ 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 cross-signing 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 (cross-signing keys):
|
||||
|
||||
- a master key (MSK) that serves as the user's identity in
|
||||
cross-signing and signs their other cross-signing keys;
|
||||
- a master signing key (MSK, for historical reasons sometimes known as
|
||||
`master_key`) 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 signing 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
|
||||
key. The master key may also be signed by the user's own device keys to
|
||||
The master signing key may also be used to sign other items such as the backup
|
||||
key. The master signing key may also be signed by the user's own device keys to
|
||||
aid in migrating from device verifications: if Alice's device had
|
||||
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
|
||||
key, then Alice's device can trust Bob's master signing 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 parts of their master signing, user-signing and
|
||||
self-signing keys 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 cross-signing keys.
|
||||
|
||||
If Alice has a device and wishes to send an encrypted message to Bob,
|
||||
she can trust Bob's device if:
|
||||
|
||||
- Alice's device is using a master key that has signed her
|
||||
- Alice's device is using a master signing key that has signed her
|
||||
user-signing key,
|
||||
- Alice's user-signing key has signed Bob's master key,
|
||||
- Bob's master key has signed Bob's self-signing key, and
|
||||
- Alice's user-signing key has signed Bob's master signing key,
|
||||
- Bob's master signing key has signed Bob's self-signing key, and
|
||||
- Bob's self-signing key has signed Bob's device key.
|
||||
|
||||
The following diagram illustrates how keys are signed:
|
||||
|
|
@ -1028,27 +1118,28 @@ 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
|
||||
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
|
||||
user's master signing key by treating its public key (master signing 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.
|
||||
|
||||
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,
|
||||
user-signing, and self-signing keys are identified using the names
|
||||
`m.cross_signing.master`, `m.cross_signing.user_signing`, and
|
||||
Using the [Secrets](#secrets) module the private parts of the cross-signing keys can
|
||||
be stored on the server or shared with other devices. When doing so, the
|
||||
master signing, 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
|
||||
before being encrypted.
|
||||
|
||||
###### Key and signature security
|
||||
|
||||
A user's master key could allow an attacker to impersonate that user to
|
||||
A user's master signing key could allow an attacker to impersonate that user to
|
||||
other users, or other users to that user. Thus clients must ensure that
|
||||
the private part of the master key is treated securely. If clients do
|
||||
not have a secure means of storing the master key (such as a secret
|
||||
the private part of the master signing key is treated securely. If clients do
|
||||
not have a secure means of storing the master signing key (such as a secret
|
||||
storage system provided by the operating system), then clients must not
|
||||
store the private part.
|
||||
|
||||
|
|
@ -1061,9 +1152,9 @@ Since device key IDs (`ed25519:DEVICE_ID`) and cross-signing key IDs
|
|||
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.
|
||||
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:
|
||||
|
||||
1. Clients MUST refer to keys by their public keys during the verification
|
||||
process, rather than only by the key ID.
|
||||
|
|
@ -1071,31 +1162,32 @@ 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 cross-signing
|
||||
key.
|
||||
|
||||
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
|
||||
the user's master key and possibly by re-verifying devices or users.
|
||||
the user's master signing key and possibly by re-verifying devices or users.
|
||||
However, doing so relies on the user being able to notice when their
|
||||
keys have been compromised, and it involves extra work for the user, and
|
||||
so although clients do not have to treat the private parts as
|
||||
sensitively as the master key, clients should still make efforts to
|
||||
sensitively as the master signing key, clients should still make efforts to
|
||||
store the private part securely, or not store it at all. Clients will
|
||||
need to balance the security of the keys with the usability of signing
|
||||
users and devices when performing key verification.
|
||||
|
||||
To avoid leaking of social graphs, servers will only allow users to see:
|
||||
|
||||
- signatures made by the user's own master, self-signing or
|
||||
- signatures made by the user's own master signing, self-signing or
|
||||
user-signing keys,
|
||||
- signatures made by the user's own devices about their own master
|
||||
key,
|
||||
- signatures made by other users' self-signing keys about their
|
||||
respective devices,
|
||||
- signatures made by other users' master keys about their respective
|
||||
- signatures made by other users' master signing keys about their respective
|
||||
self-signing key, or
|
||||
- signatures made by other users' devices about their respective
|
||||
master keys.
|
||||
master signing keys.
|
||||
|
||||
Users will not be able to see signatures made by other users'
|
||||
user-signing keys.
|
||||
|
|
@ -1197,24 +1289,24 @@ The binary segment MUST be of the following form:
|
|||
- one byte indicating the QR code verification mode. Should be one of the
|
||||
following values:
|
||||
- `0x00` verifying another user with cross-signing
|
||||
- `0x01` self-verifying in which the current device does trust the master key
|
||||
- `0x01` self-verifying in which the current device does trust the master signing key
|
||||
- `0x02` self-verifying in which the current device does not yet trust the
|
||||
master key
|
||||
master signing key
|
||||
- the event ID or `transaction_id` of the associated verification
|
||||
request event, encoded as:
|
||||
- two bytes in network byte order (big-endian) indicating the length in
|
||||
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 signing 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 signing 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
|
||||
|
|
@ -1225,14 +1317,14 @@ For example, if Alice displays a QR code encoding the following binary data:
|
|||
```nohighlight
|
||||
"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 signing 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 signing key is `1011121314151617...` (which is "EBESExQVFh..." in
|
||||
base64), and the shared secret is `2021222324252627` (which is "ICEiIyQlJic" in
|
||||
base64).
|
||||
|
||||
|
|
@ -1304,8 +1396,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 signing 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
|
||||
|
|
|
|||
41
content/rooms/fragments/v1-floaty-power-levels.md
Normal file
41
content/rooms/fragments/v1-floaty-power-levels.md
Normal file
|
|
@ -0,0 +1,41 @@
|
|||
|
||||
##### `m.room.power_levels` events accept values as floats
|
||||
|
||||
When the value is a float
|
||||
* First, exponential notation is applied: `5.114698E4` becomes `51146.98`
|
||||
* Second, the value is truncated at the decimal point: `51146.98` becomes `51146`.
|
||||
|
||||
Values outside the range represented by IEE754 binary64 (a "double") cause the
|
||||
powerlevel event to be rejected, as do `Infinity`, `-Infinity` and `NaN`.
|
||||
|
||||
For example, this is a valid `m.room.power_levels` event in this room version:
|
||||
|
||||
```json
|
||||
{
|
||||
"content": {
|
||||
"ban": 50,
|
||||
"events": {
|
||||
"m.room.power_levels": 100
|
||||
},
|
||||
"events_default": 0,
|
||||
"state_default": 50,
|
||||
"users": {
|
||||
"@example:example.org": 100,
|
||||
"@alice:localhost": 50,
|
||||
"@bob:localhost": 50.57
|
||||
},
|
||||
"users_default": 0
|
||||
},
|
||||
"origin_server_ts": 1432735824653,
|
||||
"room_id": "!jEsUZKDJdhlrceRyVU:example.org",
|
||||
"sender": "@example:example.org",
|
||||
"state_key": "",
|
||||
"type": "m.room.power_levels"
|
||||
}
|
||||
```
|
||||
|
||||
In this example, both `@bob:localhost` and `@alice:localhost` have the same effective
|
||||
power level of `50`, even though the values are technically different.
|
||||
|
||||
Note that, since this room version does not enforce that events comply with the requirements
|
||||
of [Canonical JSON](/appendices#canonical-json), power levels can be formatted as floats.
|
||||
|
|
@ -59,6 +59,8 @@ Events in version 1 rooms have the following structure:
|
|||
|
||||
{{% rver-fragment name="v1-stringy-power-levels" %}}
|
||||
|
||||
{{% rver-fragment name="v1-floaty-power-levels" %}}
|
||||
|
||||
### Authorization rules
|
||||
|
||||
{{% rver-fragment name="v1-auth-rules" %}}
|
||||
|
|
|
|||
|
|
@ -57,6 +57,8 @@ Events in rooms of this version have the following structure:
|
|||
|
||||
{{% rver-fragment name="v1-stringy-power-levels" %}}
|
||||
|
||||
{{% rver-fragment name="v1-floaty-power-levels" %}}
|
||||
|
||||
### Authorization rules
|
||||
|
||||
{{% rver-fragment name="v1-auth-rules" %}}
|
||||
|
|
|
|||
|
|
@ -87,6 +87,8 @@ The complete structure of a event in a v3 room is shown below.
|
|||
|
||||
{{% rver-fragment name="v1-stringy-power-levels" %}}
|
||||
|
||||
{{% rver-fragment name="v1-floaty-power-levels" %}}
|
||||
|
||||
### Authorization rules
|
||||
|
||||
{{% boxes/note %}}
|
||||
|
|
|
|||
|
|
@ -76,6 +76,8 @@ the changes in this room version.
|
|||
|
||||
{{% rver-fragment name="v1-stringy-power-levels" %}}
|
||||
|
||||
{{% rver-fragment name="v1-floaty-power-levels" %}}
|
||||
|
||||
### Authorization rules
|
||||
|
||||
{{% rver-fragment name="v3-auth-rules" %}}
|
||||
|
|
|
|||
|
|
@ -58,6 +58,8 @@ completeness.
|
|||
|
||||
{{% rver-fragment name="v1-stringy-power-levels" %}}
|
||||
|
||||
{{% rver-fragment name="v1-floaty-power-levels" %}}
|
||||
|
||||
### Authorization rules
|
||||
|
||||
{{% rver-fragment name="v3-auth-rules" %}}
|
||||
|
|
|
|||
|
|
@ -42,7 +42,8 @@ in [room version 5](/rooms/v5).
|
|||
### Event format
|
||||
|
||||
{{% added-in v=6 %}} Through enforcement of [Canonical JSON](#canonical-json),
|
||||
the `depth` limit has been reduced in this room version.
|
||||
the `depth` limit has been reduced in this room version, and numeric values may
|
||||
no longer be formatted as floats.
|
||||
|
||||
{{% rver-fragment name="v6-event-format" %}}
|
||||
|
||||
|
|
|
|||
|
|
@ -32,9 +32,9 @@ paths:
|
|||
except when used by an application service.
|
||||
|
||||
User-Interactive Authentication MUST be performed for regular clients, 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 signing key uploaded to the homeserver, OR
|
||||
- there is an existing master signing key and it exactly matches the
|
||||
master signing 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.
|
||||
|
|
@ -61,22 +61,22 @@ paths:
|
|||
type: object
|
||||
properties:
|
||||
master_key:
|
||||
description: Optional. The user\'s master key.
|
||||
description: Optional. The user\'s master signing key.
|
||||
allOf:
|
||||
- $ref: definitions/cross_signing_key.yaml
|
||||
self_signing_key:
|
||||
description: |-
|
||||
Optional. The user\'s self-signing key. Must be signed by
|
||||
the accompanying master key, or by the user\'s most recently
|
||||
uploaded master key if no master key is included in the
|
||||
the accompanying master signing key, or by the user\'s most recently
|
||||
uploaded master signing key if no master signing key is included in the
|
||||
request.
|
||||
allOf:
|
||||
- $ref: definitions/cross_signing_key.yaml
|
||||
user_signing_key:
|
||||
description: |-
|
||||
Optional. The user\'s user-signing key. Must be signed by
|
||||
the accompanying master key, or by the user\'s most recently
|
||||
uploaded master key if no master key is included in the
|
||||
the accompanying master signing key, or by the user\'s most recently
|
||||
uploaded master signing key if no master signing key is included in the
|
||||
request.
|
||||
allOf:
|
||||
- $ref: definitions/cross_signing_key.yaml
|
||||
|
|
@ -147,7 +147,7 @@ paths:
|
|||
|
||||
* `M_INVALID_SIGNATURE`: For example, the self-signing or
|
||||
user-signing key had an incorrect signature.
|
||||
* `M_MISSING_PARAM`: No master key is available.
|
||||
* `M_MISSING_PARAM`: No master signing key is available.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
@ -44,8 +44,8 @@ properties:
|
|||
title: Signatures
|
||||
description: |-
|
||||
Signatures of the key, calculated using the process described at [Signing JSON](/appendices/#signing-json).
|
||||
Optional for the master key. Other keys must be signed by the
|
||||
user\'s master key.
|
||||
Optional for the master signing key. Other keys must be signed by the
|
||||
user\'s master signing key.
|
||||
example: {
|
||||
"@alice:example.com": {
|
||||
"ed25519:alice+base64+master+key": "signature+of+key"
|
||||
|
|
|
|||
|
|
@ -219,8 +219,8 @@ paths:
|
|||
x-addedInMatrixVersion: "1.1"
|
||||
type: object
|
||||
description: |-
|
||||
Information on the master cross-signing keys of the queried users.
|
||||
A map from user ID, to master key information. For each key, the
|
||||
Information on the master signing keys of the queried users.
|
||||
A map from user ID, to master signing key information. For each key, the
|
||||
information returned will be the same as uploaded via
|
||||
`/keys/device_signing/upload`, along with the signatures
|
||||
uploaded via `/keys/signatures/upload` that the requesting user
|
||||
|
|
|
|||
|
|
@ -70,6 +70,21 @@ paths:
|
|||
}
|
||||
]
|
||||
}
|
||||
"404":
|
||||
description: |-
|
||||
With `M_UNRECOGNIZED`: the homeserver does not support the legacy authentication API.
|
||||
(See [Authentication API discovery](/client-server-api/#authentication-api-discovery).)
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: definitions/errors/error.yaml
|
||||
examples:
|
||||
response:
|
||||
value:
|
||||
{
|
||||
"errcode": "M_UNRECOGNIZED",
|
||||
"error": "OAuth 2.0 authentication is in use on this homeserver.",
|
||||
}
|
||||
"429":
|
||||
description: This request was rate-limited.
|
||||
content:
|
||||
|
|
|
|||
|
|
@ -195,6 +195,21 @@ paths:
|
|||
"org.matrix.cross_signing_reset",
|
||||
],
|
||||
}
|
||||
"404":
|
||||
description: |-
|
||||
With `M_UNRECOGNIZED`: the homeserver does not support the OAuth 2.0 API.
|
||||
(See [Authentication API discovery](/client-server-api/#authentication-api-discovery).)
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: definitions/errors/error.yaml
|
||||
examples:
|
||||
response:
|
||||
value:
|
||||
{
|
||||
"errcode": "M_UNRECOGNIZED",
|
||||
"error": "Legacy authentication is in use on this homeserver.",
|
||||
}
|
||||
tags:
|
||||
- Session management
|
||||
servers:
|
||||
|
|
|
|||
|
|
@ -234,207 +234,6 @@ paths:
|
|||
"errcode": "M_NOT_FOUND",
|
||||
"error": "Unknown room"
|
||||
}
|
||||
"/send_join/{roomId}/{eventId}":
|
||||
put:
|
||||
deprecated: true
|
||||
summary: Submit a signed join event to a resident server
|
||||
description: |-
|
||||
**Note:**
|
||||
Servers should instead prefer to use the v2 `/send_join` endpoint.
|
||||
|
||||
Submits a signed join event to the resident server for it
|
||||
to accept it into the room's graph. Note that events have
|
||||
a different format depending on the room version - check
|
||||
the [room version specification](/rooms) for precise event formats.
|
||||
**The request and response body here describe the common
|
||||
event fields in more detail and may be missing other required
|
||||
fields for a PDU.**
|
||||
|
||||
The receiving server MUST apply certain validation before accepting the event.
|
||||
A specific error code is not mandated, but servers SHOULD return `M_INVALID_PARAM` if:
|
||||
|
||||
* The join event fails a [signature check](/server-server-api/#validating-hashes-and-signatures-on-received-events).
|
||||
* The event type is not `m.room.member`.
|
||||
* The `membership` field inside the event content is not `join`.
|
||||
* The event sender is not a user ID on the origin server.
|
||||
* The `state_key` is not equal to the `sender`.
|
||||
operationId: sendJoinV1
|
||||
security:
|
||||
- signedRequest: []
|
||||
parameters:
|
||||
- in: path
|
||||
name: roomId
|
||||
description: The room ID that is about to be joined.
|
||||
required: true
|
||||
example: "!abc123:matrix.org"
|
||||
schema:
|
||||
type: string
|
||||
- in: path
|
||||
name: eventId
|
||||
description: The event ID for the join event.
|
||||
required: true
|
||||
example: $abc123:example.org
|
||||
schema:
|
||||
type: string
|
||||
requestBody:
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
sender:
|
||||
type: string
|
||||
description: The user ID of the joining member.
|
||||
example: "@someone:example.org"
|
||||
origin:
|
||||
type: string
|
||||
description: The name of the joining homeserver.
|
||||
example: matrix.org
|
||||
origin_server_ts:
|
||||
type: integer
|
||||
format: int64
|
||||
description: A timestamp added by the joining homeserver.
|
||||
example: 1234567890
|
||||
type:
|
||||
type: string
|
||||
description: The value `m.room.member`.
|
||||
example: m.room.member
|
||||
state_key:
|
||||
type: string
|
||||
description: The user ID of the joining member.
|
||||
example: "@someone:example.org"
|
||||
content:
|
||||
type: object
|
||||
title: Membership Event Content
|
||||
description: The content of the event.
|
||||
example:
|
||||
membership: join
|
||||
properties:
|
||||
membership:
|
||||
type: string
|
||||
description: The value `join`.
|
||||
example: join
|
||||
join_authorised_via_users_server:
|
||||
type: string
|
||||
x-addedInMatrixVersion: "1.2"
|
||||
description: |-
|
||||
Required if the room is [restricted](/client-server-api/#restricted-rooms)
|
||||
and is joining through one of the conditions available. If the
|
||||
user is responding to an invite, this is not required.
|
||||
|
||||
An arbitrary user ID belonging to the resident server in
|
||||
the room being joined that is able to issue invites to other
|
||||
users. This is used in later validation of the auth rules for
|
||||
the `m.room.member` event.
|
||||
|
||||
The resident server which owns the provided user ID must have a
|
||||
valid signature on the event. If the resident server is receiving
|
||||
the `/send_join` request, the signature must be added before sending
|
||||
or persisting the event to other servers.
|
||||
required:
|
||||
- membership
|
||||
required:
|
||||
- state_key
|
||||
- sender
|
||||
- origin
|
||||
- origin_server_ts
|
||||
- type
|
||||
- content
|
||||
required: true
|
||||
responses:
|
||||
"200":
|
||||
description: The join event has been accepted into the room.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: array
|
||||
minItems: 2
|
||||
maxItems: 2
|
||||
items:
|
||||
anyOf:
|
||||
- type: integer
|
||||
description: The value `200`.
|
||||
example: 200
|
||||
- type: object
|
||||
title: Room State
|
||||
description: The state for the room.
|
||||
properties:
|
||||
auth_chain:
|
||||
type: array
|
||||
description: |-
|
||||
The auth chain for the entire current room state prior to the join event.
|
||||
|
||||
Note that events have a different format depending on the room version - check the
|
||||
[room version specification](/rooms) for precise event formats.
|
||||
items:
|
||||
type: object
|
||||
title: PDU
|
||||
description: |-
|
||||
The [PDUs](/server-server-api/#pdus) that make up the auth chain. The event format varies depending
|
||||
on the room version - check the [room version specification](/rooms) for precise event formats.
|
||||
state:
|
||||
type: array
|
||||
description: |-
|
||||
The resolved current room state prior to the join event.
|
||||
|
||||
The event format varies depending on the room version - check the [room version specification](/rooms)
|
||||
for precise event formats.
|
||||
items:
|
||||
type: object
|
||||
title: PDU
|
||||
description: |-
|
||||
The [PDUs](/server-server-api/#pdus) for the fully resolved state of the room. The event format varies depending
|
||||
on the room version - check the [room version specification](/rooms) for precise event formats.
|
||||
required:
|
||||
- auth_chain
|
||||
- state
|
||||
examples:
|
||||
response:
|
||||
value: [
|
||||
200,
|
||||
{
|
||||
"auth_chain": [
|
||||
{
|
||||
"$ref": "examples/minimal_pdu.json"
|
||||
}
|
||||
],
|
||||
"state": [
|
||||
{
|
||||
"$ref": "examples/minimal_pdu.json"
|
||||
}
|
||||
],
|
||||
"event": {
|
||||
"$ref": "examples/pdu_v4_join_membership.json"
|
||||
}
|
||||
}
|
||||
]
|
||||
"400":
|
||||
description: |-
|
||||
The request is invalid in some way.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: ../client-server/definitions/errors/error.yaml
|
||||
examples:
|
||||
response:
|
||||
value: {
|
||||
"errcode": "M_INVALID_PARAM",
|
||||
"error": "Not a join event."
|
||||
}
|
||||
"403":
|
||||
description: |-
|
||||
The room that the joining server is attempting to join does not permit the user
|
||||
to join.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: ../client-server/definitions/errors/error.yaml
|
||||
examples:
|
||||
response:
|
||||
value: {
|
||||
"errcode": "M_FORBIDDEN",
|
||||
"error": "You are not invited to this room"
|
||||
}
|
||||
servers:
|
||||
- url: "{protocol}://{hostname}{basePath}"
|
||||
variables:
|
||||
|
|
|
|||
|
|
@ -22,15 +22,6 @@ paths:
|
|||
put:
|
||||
summary: Submit a signed join event to a resident server
|
||||
description: |-
|
||||
**Note:**
|
||||
This API is nearly identical to the v1 API with the
|
||||
exception of the response format being fixed.
|
||||
|
||||
This endpoint is preferred over the v1 API as it provides
|
||||
a more standardised response format. Senders which receive
|
||||
a 400, 404, or other status code which indicates this endpoint
|
||||
is not available should retry using the v1 API instead.
|
||||
|
||||
Submits a signed join event to the resident server for it
|
||||
to accept it into the room's graph. Note that events have
|
||||
a different format depending on the room version - check
|
||||
|
|
|
|||
|
|
@ -149,139 +149,6 @@ paths:
|
|||
"errcode": "M_FORBIDDEN",
|
||||
"error": "User is not in the room."
|
||||
}
|
||||
"/send_leave/{roomId}/{eventId}":
|
||||
put:
|
||||
deprecated: true
|
||||
summary: Submit a signed leave event to a resident server
|
||||
description: |-
|
||||
**Note:**
|
||||
Servers should instead prefer to use the v2 `/send_leave` endpoint.
|
||||
|
||||
Submits a signed leave event to the resident server for it
|
||||
to accept it into the room's graph. Note that events have
|
||||
a different format depending on the room version - check
|
||||
the [room version specification](/rooms) for precise event formats.
|
||||
**The request and response body here describe the common
|
||||
event fields in more detail and may be missing other required
|
||||
fields for a PDU.**
|
||||
|
||||
The receiving server MUST apply certain validation before accepting the event.
|
||||
A specific error code is not mandated, but servers SHOULD return `M_INVALID_PARAM` if:
|
||||
|
||||
* The leave event fails a [signature check](/server-server-api/#validating-hashes-and-signatures-on-received-events).
|
||||
* The event type is not `m.room.member`.
|
||||
* The `membership` field inside the event content is not `leave`.
|
||||
* The event sender is not a user ID on the origin server.
|
||||
* The `state_key` is not equal to the `sender`.
|
||||
operationId: sendLeaveV1
|
||||
security:
|
||||
- signedRequest: []
|
||||
parameters:
|
||||
- in: path
|
||||
name: roomId
|
||||
description: The room ID that is about to be left.
|
||||
required: true
|
||||
example: "!abc123:matrix.org"
|
||||
schema:
|
||||
type: string
|
||||
- in: path
|
||||
name: eventId
|
||||
description: The event ID for the leave event.
|
||||
required: true
|
||||
example: $abc123:example.org
|
||||
schema:
|
||||
type: string
|
||||
requestBody:
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
sender:
|
||||
type: string
|
||||
description: The user ID of the leaving member.
|
||||
example: "@someone:example.org"
|
||||
origin:
|
||||
type: string
|
||||
description: The name of the leaving homeserver.
|
||||
example: matrix.org
|
||||
origin_server_ts:
|
||||
type: integer
|
||||
format: int64
|
||||
description: A timestamp added by the leaving homeserver.
|
||||
example: 1234567890
|
||||
type:
|
||||
type: string
|
||||
description: The value `m.room.member`.
|
||||
example: m.room.member
|
||||
state_key:
|
||||
type: string
|
||||
description: The user ID of the leaving member.
|
||||
example: "@someone:example.org"
|
||||
content:
|
||||
type: object
|
||||
title: Membership Event Content
|
||||
description: The content of the event.
|
||||
example:
|
||||
membership: leave
|
||||
properties:
|
||||
membership:
|
||||
type: string
|
||||
description: The value `leave`.
|
||||
example: leave
|
||||
required:
|
||||
- membership
|
||||
depth:
|
||||
type: integer
|
||||
description: This field must be present but is ignored; it may be 0.
|
||||
example: 12
|
||||
required:
|
||||
- state_key
|
||||
- sender
|
||||
- origin
|
||||
- origin_server_ts
|
||||
- type
|
||||
- depth
|
||||
- content
|
||||
required: true
|
||||
responses:
|
||||
"200":
|
||||
description: |-
|
||||
An empty response to indicate the event was accepted into the graph by
|
||||
the receiving homeserver.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: array
|
||||
minItems: 2
|
||||
maxItems: 2
|
||||
items:
|
||||
anyOf:
|
||||
- type: integer
|
||||
description: The value `200`.
|
||||
example: 200
|
||||
- type: object
|
||||
title: Empty Object
|
||||
description: An empty object.
|
||||
examples:
|
||||
response:
|
||||
value: [
|
||||
200,
|
||||
{}
|
||||
]
|
||||
"400":
|
||||
description: |-
|
||||
The request is invalid in some way.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: ../client-server/definitions/errors/error.yaml
|
||||
examples:
|
||||
response:
|
||||
value: {
|
||||
"errcode": "M_INVALID_PARAM",
|
||||
"error": "Not a leave event."
|
||||
}
|
||||
servers:
|
||||
- url: "{protocol}://{hostname}{basePath}"
|
||||
variables:
|
||||
|
|
|
|||
|
|
@ -22,15 +22,6 @@ paths:
|
|||
put:
|
||||
summary: Submit a signed leave event to a resident server
|
||||
description: |-
|
||||
**Note:**
|
||||
This API is nearly identical to the v1 API with the
|
||||
exception of the response format being fixed.
|
||||
|
||||
This endpoint is preferred over the v1 API as it provides
|
||||
a more standardised response format. Senders which receive
|
||||
a 400, 404, or other status code which indicates this endpoint
|
||||
is not available should retry using the v1 API instead.
|
||||
|
||||
Submits a signed leave event to the resident server for it
|
||||
to accept it into the room's graph. Note that events have
|
||||
a different format depending on the room version - check
|
||||
|
|
|
|||
|
|
@ -79,7 +79,7 @@ paths:
|
|||
- keys
|
||||
master_key:
|
||||
type: object
|
||||
description: The user\'s master cross-signing key.
|
||||
description: The user\'s master signing key.
|
||||
allOf:
|
||||
- $ref: ../client-server/definitions/cross_signing_key.yaml
|
||||
- example:
|
||||
|
|
|
|||
|
|
@ -194,8 +194,8 @@ paths:
|
|||
x-addedInMatrixVersion: "1.1"
|
||||
type: object
|
||||
description: |-
|
||||
Information on the master cross-signing keys of the queried users.
|
||||
A map from user ID, to master key information. For each key, the
|
||||
Information on the master signing keys of the queried users.
|
||||
A map from user ID, to master signing key information. For each key, the
|
||||
information returned will be the same as uploaded via
|
||||
`/keys/device_signing/upload`, along with the signatures
|
||||
uploaded via `/keys/signatures/upload` that the user is
|
||||
|
|
|
|||
Loading…
Reference in a new issue