mirror of
https://github.com/matrix-org/matrix-spec
synced 2026-07-02 12:17:47 +02:00
Merge branch 'main' into patch-10
This commit is contained in:
Kim Brose
GitHub
commit
07ea220e6b
2
.github/CODEOWNERS
vendored
2
.github/CODEOWNERS
vendored
|
|
@ -1 +1 @@
|
|||
* @matrix-org/spec-core-team
|
||||
* @matrix-org/spec-core-team @zecakeh
|
||||
|
|
|
|||
1
changelogs/appendices/newsfragments/2395.clarification
Normal file
1
changelogs/appendices/newsfragments/2395.clarification
Normal file
|
|
@ -0,0 +1 @@
|
|||
Clarify matrix.to RFC 3986 percent encoding requirements. Contributed by @HarHarLinks.
|
||||
1
changelogs/appendices/newsfragments/2398.clarification
Normal file
1
changelogs/appendices/newsfragments/2398.clarification
Normal file
|
|
@ -0,0 +1 @@
|
|||
Add specification of URL-safe unpadded Base64.
|
||||
|
|
@ -0,0 +1 @@
|
|||
Clarify definitions of `EncryptedFile` structure.
|
||||
1
changelogs/client_server/newsfragments/2403.feature
Normal file
1
changelogs/client_server/newsfragments/2403.feature
Normal file
|
|
@ -0,0 +1 @@
|
|||
Specify `unsigned.replaces_state` in client-formatted events. Contributed by @nexy7574.
|
||||
1
changelogs/internal/newsfragments/2400.clarification
Normal file
1
changelogs/internal/newsfragments/2400.clarification
Normal file
|
|
@ -0,0 +1 @@
|
|||
Update CODEOWNERS file.
|
||||
1
changelogs/internal/newsfragments/2402.clarification
Normal file
1
changelogs/internal/newsfragments/2402.clarification
Normal file
|
|
@ -0,0 +1 @@
|
|||
Minor fixes to `check-newsfragments` CI script.
|
||||
|
|
@ -0,0 +1 @@
|
|||
Fix various typos throughout the specification.
|
||||
|
|
@ -0,0 +1 @@
|
|||
Fix various typos throughout the specification.
|
||||
|
|
@ -12,7 +12,7 @@ Specifically, where RFC 4648 requires that encoded data be padded to a
|
|||
multiple of four characters using `=` characters, unpadded Base64 omits
|
||||
this padding.
|
||||
|
||||
For reference, RFC 4648 uses the following alphabet for Base 64:
|
||||
For reference, RFC 4648 uses the following alphabet for Base64:
|
||||
|
||||
Value Encoding Value Encoding Value Encoding Value Encoding
|
||||
0 A 17 R 34 i 51 z
|
||||
|
|
@ -47,6 +47,12 @@ When decoding Base64, implementations SHOULD accept input with or
|
|||
without padding characters wherever possible, to ensure maximum
|
||||
interoperability.
|
||||
|
||||
### URL-safe unpadded Base64
|
||||
|
||||
URL-safe unpadded Base64 is identical to standard unpadded Base64, except that
|
||||
it uses `-` (minus) as the 62nd character in the alphabet, and `_` (underscore)
|
||||
as the 63rd. This matches [RFC4648’s definition of URL-safe base64](https://tools.ietf.org/html/rfc4648#section-5).
|
||||
|
||||
## Binary data
|
||||
|
||||
In some cases it is necessary to encapsulate binary data, for example,
|
||||
|
|
@ -900,9 +906,17 @@ Clients MUST NOT produce incorrectly encoded URIs to avoid ambiguous interpretat
|
|||
Examples of matrix.to URIs are:
|
||||
|
||||
<!-- Author's note: These examples should be consistent with the matrix scheme counterparts. -->
|
||||
* Link to `#somewhere:example.org`: `https://matrix.to/#/%23somewhere:example.org`
|
||||
* Link to `!somewhere:example.org`: `https://matrix.to/#/!somewhere:example.org?via=elsewhere.ca`
|
||||
* Link to `$event` in `!somewhere:example.org`: `https://matrix.to/#/!somewhere:example.org/$event:example.org?via=elsewhere.ca`
|
||||
* Link to `@alice:example.org`: `https://matrix.to/#/@alice:example.org`
|
||||
|
||||
Note that encoding of characters is REQUIRED by RFC 3986 when they could otherwise be misinterpreted, and OPTIONAL for any other character.
|
||||
Hence the following encoding is also valid:
|
||||
|
||||
* Link to `#somewhere:example.org`: `https://matrix.to/#/%23somewhere%3Aexample.org`
|
||||
* Link to `!somewhere:example.org`: `https://matrix.to/#/!somewhere%3Aexample.org?via=elsewhere.ca`
|
||||
* Link to `$event` in `!somewhere:example.org`: `https://matrix.to/#/!somewhere%3Aexample.org/%24event%3Aexample.org?via=elsewhere.ca`
|
||||
* Link to `!somewhere:example.org`: `https://matrix.to/#/%21somewhere%3Aexample.org?via=elsewhere.ca`
|
||||
* Link to `$event` in `!somewhere:example.org`: `https://matrix.to/#/%21somewhere%3Aexample.org/%24event%3Aexample.org?via=elsewhere.ca`
|
||||
* Link to `@alice:example.org`: `https://matrix.to/#/%40alice%3Aexample.org`
|
||||
|
||||
{{% boxes/note %}}
|
||||
|
|
|
|||
|
|
@ -355,7 +355,7 @@ key, and encrypts the file using AES-CTR. The counter is 64 bits long,
|
|||
starting at 0 and prefixed by a random 64-bit Initialization Vector (IV),
|
||||
which together form a 128-bit unique counter block.
|
||||
|
||||
Clients MUST generate both the AES key and IV using a cryptographically
|
||||
Clients MUST generate both the AES key and IV using a cryptographically
|
||||
secure random source and MUST NOT use the same key or IV multiple
|
||||
times. The latter 64 bits of the 128-bit counter block MUST start at zero.
|
||||
|
||||
|
|
@ -385,31 +385,11 @@ Key](https://tools.ietf.org/html/rfc7517#appendix-A.3) format, with a
|
|||
###### Extensions to `m.room.message` msgtypes
|
||||
|
||||
This module adds `file` and `thumbnail_file` properties, of type
|
||||
`EncryptedFile`, to `m.room.message` msgtypes that reference files, such
|
||||
as [m.file](#mfile) and [m.image](#mimage), replacing the `url` and `thumbnail_url`
|
||||
properties.
|
||||
[`EncryptedFile`](#definition-encryptedfile), to `m.room.message` msgtypes that
|
||||
reference files, such as [m.file](#mfile) and [m.image](#mimage), replacing the
|
||||
`url` and `thumbnail_url` properties.
|
||||
|
||||
`EncryptedFile`
|
||||
|
||||
| Parameter | Type | Description |
|
||||
|-----------|------------------|------------------------------------------------------------------------------------------------|
|
||||
| url | string | **Required.** The URL to the file. |
|
||||
| key | JWK | **Required.** A [JSON Web Key](https://tools.ietf.org/html/rfc7517#appendix-A.3) object. |
|
||||
| iv | string | **Required.** The 128-bit unique counter block used by AES-CTR, encoded as unpadded base64. |
|
||||
| hashes | {string: string} | **Required.** A map from an algorithm name to a hash of the ciphertext, encoded as unpadded base64. Clients MUST support the SHA-256 hash, which uses the key `sha256`. |
|
||||
| v | string | **Required.** Version of the encrypted attachment's protocol. Must be `v2`. |
|
||||
|
||||
`JWK`
|
||||
|
||||
| Parameter | Type | Description |
|
||||
| --------- |----------|--------------------------------------------------------------------------------------------------------------------------|
|
||||
| kty | string | **Required.** Key type. Must be `oct`. |
|
||||
| key_ops | [string] | **Required.** Key operations. Must at least contain `encrypt` and `decrypt`. |
|
||||
| alg | string | **Required.** Algorithm. Must be `A256CTR`. |
|
||||
| k | string | **Required.** The key, encoded as urlsafe unpadded base64. |
|
||||
| ext | boolean | **Required.** Extractable. Must be `true`. This is a [W3C extension](https://w3c.github.io/webcrypto/#iana-section-jwk). |
|
||||
|
||||
Example:
|
||||
Example `m.room.message` event containing an encrypted image:
|
||||
|
||||
```json
|
||||
{
|
||||
|
|
@ -470,6 +450,8 @@ Example:
|
|||
}
|
||||
```
|
||||
|
||||
{{% definition path="api/client-server/definitions/encrypted_file" %}}
|
||||
|
||||
#### Device verification
|
||||
|
||||
Before Alice sends Bob encrypted data, or trusts data received from him,
|
||||
|
|
@ -764,7 +746,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:
|
||||
* {{% 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,
|
||||
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.
|
||||
|
|
|
|||
|
|
@ -276,9 +276,8 @@ internal state of the hash function.
|
|||
|
||||
After formatting each query, the string is run through SHA-256 as
|
||||
defined by [RFC 4634](https://tools.ietf.org/html/rfc4634). The
|
||||
resulting bytes are then encoded using URL-Safe [Unpadded
|
||||
Base64](/appendices#unpadded-base64) (similar to [room version
|
||||
4's event ID format](/rooms/v4#event-ids)).
|
||||
resulting bytes are then encoded using [URL-Safe unpadded
|
||||
Base64](/appendices/#url-safe-unpadded-base64).
|
||||
|
||||
An example set of queries when using the pepper `matrixrocks` would be:
|
||||
|
||||
|
|
|
|||
|
|
@ -2,11 +2,8 @@
|
|||
---
|
||||
{{% added-in v=4 %}} The event ID is the [reference
|
||||
hash](/server-server-api#calculating-the-reference-hash-for-an-event) of
|
||||
the event encoded using a variation of [Unpadded
|
||||
Base64](/appendices#unpadded-base64) which replaces the 62nd and
|
||||
63rd characters with `-` and `_` instead of using `+` and `/`. This
|
||||
matches [RFC4648's definition of URL-safe
|
||||
base64](https://tools.ietf.org/html/rfc4648#section-5).
|
||||
the event encoded using [URL-safe unpadded
|
||||
Base64](/appendices/#url-safe-unpadded-base64).
|
||||
|
||||
Event IDs are still prefixed with `$` and might result in looking like
|
||||
`$Rqnc-F-dvnEYJTyHq_iKxU2bZ1CI92-kuZq3a5lr5Zg`.
|
||||
|
|
|
|||
|
|
@ -124,6 +124,8 @@ properties:
|
|||
by the local homeserver, and is only returned if the event is a state event.
|
||||
Unlike `prev_content`, this field is included regardless of history visibility.
|
||||
type: string
|
||||
format: mx-event-id
|
||||
pattern: "^\\$"
|
||||
x-addedInMatrixVersion: "1.19"
|
||||
membership:
|
||||
description: |
|
||||
|
|
|
|||
87
data/api/client-server/definitions/encrypted_file.yaml
Normal file
87
data/api/client-server/definitions/encrypted_file.yaml
Normal file
|
|
@ -0,0 +1,87 @@
|
|||
# Copyright 2018-2026 The Matrix.org Foundation C.I.C.
|
||||
#
|
||||
# Licensed under the Apache License, Version 2.0 (the "License");
|
||||
# you may not use this file except in compliance with the License.
|
||||
# You may obtain a copy of the License at
|
||||
#
|
||||
# http://www.apache.org/licenses/LICENSE-2.0
|
||||
#
|
||||
# Unless required by applicable law or agreed to in writing, software
|
||||
# distributed under the License is distributed on an "AS IS" BASIS,
|
||||
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||||
# See the License for the specific language governing permissions and
|
||||
# limitations under the License.
|
||||
|
||||
type: object
|
||||
title: EncryptedFile
|
||||
description: |
|
||||
Information on an encrypted media blob, including its location in the
|
||||
[content repository](/client-server-api/#content-repository), and the keys
|
||||
necessary to decrypt it.
|
||||
properties:
|
||||
url:
|
||||
type: string
|
||||
format: mx-mxc-uri
|
||||
description: The URL to the file.
|
||||
example: "mxc://example.org/FHyPlCeYUSFFxlgbQYZmoEoe"
|
||||
key:
|
||||
type: object
|
||||
title: JWK
|
||||
description: A [JSON Web Key](https://tools.ietf.org/html/rfc7517#appendix-A.3) object.
|
||||
properties:
|
||||
kty:
|
||||
type: string
|
||||
description: Key type. Must be `oct`.
|
||||
example: "oct"
|
||||
key_ops:
|
||||
type: array
|
||||
items:
|
||||
type: string
|
||||
description: Key operations. Must at least contain `encrypt` and `decrypt`.
|
||||
example: ["encrypt", "decrypt"]
|
||||
alg:
|
||||
type: string
|
||||
description: Algorithm. Must be `A256CTR`.
|
||||
example: A256CTR
|
||||
k:
|
||||
type: string
|
||||
format: mx-urlsafe-unpadded-base64
|
||||
description: The key, encoded as [URL-safe unpadded Base64](/appendices/#url-safe-unpadded-base64).
|
||||
example: "aWF6-32KGYaC3A_FEUCk1Bt0JA37zP0wrStgmdCaW-0"
|
||||
ext:
|
||||
type: boolean
|
||||
description: "Extractable. Must be `true`. This is a [W3C extension](https://w3c.github.io/webcrypto/#iana-section-jwk)."
|
||||
example: true
|
||||
required:
|
||||
- kty
|
||||
- key_ops
|
||||
- alg
|
||||
- k
|
||||
- ext
|
||||
iv:
|
||||
type: string
|
||||
format: mx-unpadded-base64
|
||||
description: The 128-bit unique counter block used by AES-CTR, encoded as [unpadded Base64](/appendices/#unpadded-base64).
|
||||
example: "w+sE15fzSc0AAAAAAAAAAA"
|
||||
hashes:
|
||||
type: object
|
||||
title: EncryptedFileHashes
|
||||
description:
|
||||
A map from an algorithm name to a hash of the ciphertext. Clients MUST support the SHA-256 hash, which uses the key `sha256`.
|
||||
properties:
|
||||
sha256:
|
||||
type: string
|
||||
format: mx-unpadded-base64
|
||||
description: The hash of the ciphertext. encoded as [unpadded Base64](/appendices/#unpadded-base64).
|
||||
example: "fdSLu/YkRx3Wyh3KQabP3rd6+SFiKg5lsJZQHtkSAYA"
|
||||
required: ['sha256']
|
||||
v:
|
||||
type: string
|
||||
description: Version of the encrypted attachment’s protocol. Must be `v2`.
|
||||
example: v2
|
||||
required:
|
||||
- url
|
||||
- key
|
||||
- iv
|
||||
- hashes
|
||||
- v
|
||||
|
|
@ -156,7 +156,7 @@ paths:
|
|||
public_key:
|
||||
type: string
|
||||
description: |
|
||||
The public key, encoded using standard or URL-safe [unpadded Base64](/appendices/#unpadded-base64).
|
||||
The public key, encoded using [standard unpadded Base64](/appendices/#unpadded-base64) or [URL-safe unpadded Base64](/appendices/#url-safe-unpadded-base64).
|
||||
key_validity_url:
|
||||
type: string
|
||||
description: |
|
||||
|
|
|
|||
|
|
@ -27,8 +27,7 @@ properties:
|
|||
pattern: "^mxc:\\/\\/"
|
||||
thumbnail_file:
|
||||
description: |-
|
||||
Information on the encrypted thumbnail file, as specified in
|
||||
[End-to-end encryption](/client-server-api/#sending-encrypted-attachments).
|
||||
An [EncryptedFile](/client-server-api/#definition-encryptedfile) structure.
|
||||
Only present if the thumbnail is encrypted.
|
||||
title: EncryptedFile
|
||||
type: object
|
||||
|
|
|
|||
|
|
@ -58,9 +58,7 @@ properties:
|
|||
pattern: "^mxc:\\/\\/"
|
||||
file:
|
||||
description: |-
|
||||
Required if the file is encrypted. Information on the encrypted
|
||||
file, as specified in
|
||||
[End-to-end encryption](/client-server-api/#sending-encrypted-attachments).
|
||||
Required if the file is encrypted. An [EncryptedFile](/client-server-api/#definition-encryptedfile) structure.
|
||||
title: EncryptedFile
|
||||
type: object
|
||||
required:
|
||||
|
|
|
|||
|
|
@ -48,8 +48,7 @@ properties:
|
|||
pattern: "^mxc:\\/\\/"
|
||||
thumbnail_file:
|
||||
description: |-
|
||||
Information on the encrypted thumbnail file, as specified in
|
||||
[End-to-end encryption](/client-server-api/#sending-encrypted-attachments).
|
||||
An [EncryptedFile](/client-server-api/#definition-encryptedfile) structure.
|
||||
Only present if the thumbnail is encrypted.
|
||||
title: EncryptedFile
|
||||
type: object
|
||||
|
|
@ -72,9 +71,7 @@ properties:
|
|||
pattern: "^mxc:\\/\\/"
|
||||
file:
|
||||
description: |-
|
||||
Required if the file is encrypted. Information on the encrypted
|
||||
file, as specified in
|
||||
[End-to-end encryption](/client-server-api/#sending-encrypted-attachments).
|
||||
Required if the file is encrypted. An [EncryptedFile](/client-server-api/#definition-encryptedfile) structure.
|
||||
title: EncryptedFile
|
||||
type: object
|
||||
required:
|
||||
|
|
|
|||
|
|
@ -48,9 +48,7 @@ properties:
|
|||
pattern: "^mxc:\\/\\/"
|
||||
file:
|
||||
description: |-
|
||||
Required if the file is encrypted. Information on the encrypted
|
||||
file, as specified in
|
||||
[End-to-end encryption](/client-server-api/#sending-encrypted-attachments).
|
||||
Required if the file is encrypted. An [EncryptedFile](/client-server-api/#definition-encryptedfile) structure.
|
||||
title: EncryptedFile
|
||||
type: object
|
||||
required:
|
||||
|
|
|
|||
|
|
@ -31,8 +31,7 @@ properties:
|
|||
pattern: "^mxc:\\/\\/"
|
||||
thumbnail_file:
|
||||
description: |-
|
||||
Information on the encrypted thumbnail file, as specified in
|
||||
[End-to-end encryption](/client-server-api/#sending-encrypted-attachments).
|
||||
An [EncryptedFile](/client-server-api/#definition-encryptedfile) structure.
|
||||
Only present if the thumbnail is encrypted.
|
||||
title: EncryptedFile
|
||||
type: object
|
||||
|
|
|
|||
|
|
@ -58,8 +58,7 @@ properties:
|
|||
pattern: "^mxc:\\/\\/"
|
||||
thumbnail_file:
|
||||
description: |-
|
||||
Information on the encrypted thumbnail file, as specified in
|
||||
[End-to-end encryption](/client-server-api/#sending-encrypted-attachments).
|
||||
An [EncryptedFile](/client-server-api/#definition-encryptedfile) structure.
|
||||
Only present if the thumbnail is encrypted.
|
||||
title: EncryptedFile
|
||||
type: object
|
||||
|
|
@ -82,9 +81,7 @@ properties:
|
|||
pattern: "^mxc:\\/\\/"
|
||||
file:
|
||||
description: |-
|
||||
Required if the file is encrypted. Information on the encrypted
|
||||
file, as specified in
|
||||
[End-to-end encryption](/client-server-api/#sending-encrypted-attachments).
|
||||
Required if the file is encrypted. An [EncryptedFile](/client-server-api/#definition-encryptedfile) structure.
|
||||
title: EncryptedFile
|
||||
type: object
|
||||
required:
|
||||
|
|
|
|||
|
|
@ -71,6 +71,11 @@ mx-unpadded-base64:
|
|||
url: appendices#unpadded-base64
|
||||
# no regex
|
||||
|
||||
mx-urlsafe-unpadded-base64:
|
||||
title: URL-safe unpadded Base64
|
||||
url: appendices/#url-safe-unpadded-base64
|
||||
# no regex
|
||||
|
||||
uri:
|
||||
title: URI
|
||||
url: https://datatracker.ietf.org/doc/html/rfc3986
|
||||
|
|
|
|||
|
|
@ -26,6 +26,7 @@ while read f; do
|
|||
# check that each changelog file has a known extension
|
||||
if ! [[ "$extension" == "new" || "$extension" == "feature" || "$extension" == "clarification" || "$extension" == "breaking" || "$extension" == "deprecation" ]]; then
|
||||
echo -e "\e[31mERROR: newsfragment $f does not have one of the required file extensions for a changelog entry: .new, .feature, .clarification, .breaking, .deprecation\e[39m" >&2
|
||||
failed=1
|
||||
fi
|
||||
|
||||
# check that there is nothing that looks like a newsfile outside one of the
|
||||
|
|
|
|||
Loading…
Reference in a new issue