Merge branch 'master' into travis/spec/MSC2320-identity-versions
Travis Ralston
4 years ago
committed by
Richard van der Hoff
commit
fc6aa30000
@ -0,0 +1 @@
|
||||
Add support for spoilers ([MSC2010](https://github.com/matrix-org/matrix-doc/pull/2010) and [MSC2557](https://github.com/matrix-org/matrix-doc/pull/2557)), and `color` attribute ([MSC2422](https://github.com/matrix-org/matrix-doc/pull/2422)).
|
||||
@ -0,0 +1 @@
|
||||
Clarify that event bodies are untrusted, as per [MSC2801](https://github.com/matrix-org/matrix-doc/pull/2801).
|
||||
@ -0,0 +1 @@
|
||||
Add `<details>` and `<summary>` to the suggested HTML subset as per [MSC2184](https://github.com/matrix-org/matrix-doc/pull/2184).
|
||||
@ -0,0 +1 @@
|
||||
Fix various typos throughout the specification.
|
||||
@ -0,0 +1 @@
|
||||
Fix the maximum event size restriction (65535 bytes -> 65536).
|
||||
@ -0,0 +1 @@
|
||||
Add `m.key.verification.ready` and `m.key.verification.done` to key verification framework as per [MSC2366](https://github.com/matrix-org/matrix-doc/pull/2366).
|
||||
@ -0,0 +1 @@
|
||||
Add key verification using in-room messages as per [MSC2241](https://github.com/matrix-org/matrix-doc/pull/2241).
|
||||
@ -0,0 +1 @@
|
||||
Add information about using SSSS for cross-signing and key backup.
|
||||
@ -0,0 +1 @@
|
||||
Add key verification method using QR codes ([MSC1544](https://github.com/matrix-org/matrix-doc/pull/1544)).
|
||||
@ -0,0 +1 @@
|
||||
Add key verification using in-room messages as per [MSC2241](https://github.com/matrix-org/matrix-doc/pull/2241).
|
||||
@ -0,0 +1 @@
|
||||
Document how clients can simplify usage of Secure Secret Storage ([MSC2874](https://github.com/uhoreg/matrix-doc/pull/new/single_ssss_spec)).
|
||||
@ -0,0 +1 @@
|
||||
Add support for knocking, as per [MSC2403](https://github.com/matrix-org/matrix-doc/pull/2403).
|
||||
@ -0,0 +1 @@
|
||||
Add `/knock` endpoint as per [MSC2403](https://github.com/matrix-org/matrix-doc/pull/2403).
|
||||
@ -0,0 +1 @@
|
||||
Fix various typos throughout the specification.
|
||||
@ -0,0 +1 @@
|
||||
Fix various typos throughout the specification.
|
||||
@ -0,0 +1 @@
|
||||
Add support for knocking, as per [MSC2403](https://github.com/matrix-org/matrix-doc/pull/2403).
|
||||
@ -0,0 +1 @@
|
||||
Add `/make_knock` and `/send_knock` endpoints as per [MSC2403](https://github.com/matrix-org/matrix-doc/pull/2403).
|
||||
@ -0,0 +1,52 @@
|
||||
---
|
||||
title: Room Version 7
|
||||
type: docs
|
||||
weight: 60
|
||||
---
|
||||
|
||||
This room version builds on [version 6](/rooms/v6) to introduce knocking
|
||||
as a possible join rule and membership state.
|
||||
|
||||
## Client considerations
|
||||
|
||||
This is the first room version to support knocking completely. As such,
|
||||
users will not be able to knock on rooms which are not based off v7.
|
||||
|
||||
## Server implementation components
|
||||
|
||||
{{% boxes/warning %}}
|
||||
The information contained in this section is strictly for server
|
||||
implementors. Applications which use the Client-Server API are generally
|
||||
unaffected by the intricacies contained here. The section above
|
||||
regarding client considerations is the resource that Client-Server API
|
||||
use cases should reference.
|
||||
{{% /boxes/warning %}}
|
||||
|
||||
Room version 7 adds new authorization rules for events to support knocking.
|
||||
[Room version 6](/rooms/v6) has details of other authorization rule changes,
|
||||
as do the versions v6 is based upon.
|
||||
|
||||
For checks perfomed upon `m.room.member` events, the following conditions
|
||||
are added in context:
|
||||
|
||||
If type is `m.room.member`:
|
||||
|
||||
...
|
||||
|
||||
* If `membership` is `ban`:
|
||||
|
||||
...
|
||||
|
||||
* If `membership` is `knock`:
|
||||
|
||||
i. If the `join_rule` is anything other than `knock`, reject.
|
||||
|
||||
ii. If `sender` does not match `state_key`, reject.
|
||||
|
||||
iii. If the `sender`'s current membership is not `ban`, `invite`, or `join`, allow.
|
||||
|
||||
iv. Otherwise, reject.
|
||||
|
||||
...
|
||||
|
||||
The remaining rules are the same as in [room version 6](/rooms/v6#authorization-rules-for-events).
|
||||
@ -0,0 +1,28 @@
|
||||
{
|
||||
"Folder": "Asdaw",
|
||||
"Guitar": "Agiṭaṛ",
|
||||
"Ball": "Tcama",
|
||||
"Flag": "Acenyal",
|
||||
"Telephone": "Atilifun",
|
||||
"Key": "Tasarut",
|
||||
"Book": "Adlis",
|
||||
"Hat": "Taraza",
|
||||
"Robot": "Aṛubu",
|
||||
"Heart": "Ul",
|
||||
"Apple": "Tadeffuyt",
|
||||
"Banana": "Tabanant",
|
||||
"Fire": "Timessi",
|
||||
"Moon": "Ayyur",
|
||||
"Mushroom": "Agursel",
|
||||
"Tree": "Aseklu",
|
||||
"Fish": "Aselm",
|
||||
"Turtle": "Ifker",
|
||||
"Rooster": "Ayaẓiḍ",
|
||||
"Rabbit": "Agnin",
|
||||
"Elephant": "Ilu",
|
||||
"Pig": "Ilef",
|
||||
"Horse": "Ayyis",
|
||||
"Lion": "Izem",
|
||||
"Cat": "Amuc",
|
||||
"Dog": "Aydi"
|
||||
}
|
||||
@ -0,0 +1,124 @@
|
||||
# Copyright 2021 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.
|
||||
swagger: '2.0'
|
||||
info:
|
||||
title: "Matrix Client-Server Room Knocking API"
|
||||
version: "1.0.0"
|
||||
host: localhost:8008
|
||||
schemes:
|
||||
- https
|
||||
- http
|
||||
basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
|
||||
consumes:
|
||||
- application/json
|
||||
produces:
|
||||
- application/json
|
||||
securityDefinitions:
|
||||
$ref: definitions/security.yaml
|
||||
paths:
|
||||
"/knock/{roomIdOrAlias}":
|
||||
post:
|
||||
summary: Knock on a room, requesting permission to join.
|
||||
description: |-
|
||||
*Note that this API takes either a room ID or alias, unlike other membership APIs.*
|
||||
|
||||
This API "knocks" on the room to ask for permission to join, if the user
|
||||
is allowed to knock on the room. Acceptance of the knock happens out of
|
||||
band from this API, meaning that the client will have to watch for updates
|
||||
regarding the acceptance/rejection of the knock.
|
||||
|
||||
If the room history settings allow, the user will still be able to see
|
||||
history of the room while being in the "knock" state. The user will have
|
||||
to accept the invitation to join the room (acceptance of knock) to see
|
||||
messages reliably. See the `/join` endpoints for more information about
|
||||
history visibility to the user.
|
||||
|
||||
The knock will appear as an entry in the response of the
|
||||
[`/sync`](/client-server-api/#get_matrixclientr0sync) API.
|
||||
operationId: knockRoom
|
||||
security:
|
||||
- accessToken: []
|
||||
parameters:
|
||||
- in: path
|
||||
type: string
|
||||
name: roomIdOrAlias
|
||||
description: The room identifier or alias to knock upon.
|
||||
required: true
|
||||
x-example: "#monkeys:matrix.org"
|
||||
- in: query
|
||||
type: array
|
||||
items:
|
||||
type: string
|
||||
name: server_name
|
||||
description: |-
|
||||
The servers to attempt to knock on the room through. One of the servers
|
||||
must be participating in the room.
|
||||
x-example: ["matrix.org", "elsewhere.ca"]
|
||||
- in: body
|
||||
name: body
|
||||
required: true
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
reason:
|
||||
type: string
|
||||
description: |-
|
||||
Optional reason to be included as the `reason` on the subsequent
|
||||
membership event.
|
||||
example: "Looking for support"
|
||||
responses:
|
||||
200:
|
||||
description: |-
|
||||
The room has been knocked upon.
|
||||
|
||||
The knocked room ID must be returned in the `room_id` field.
|
||||
examples:
|
||||
application/json: {
|
||||
"room_id": "!d41d8cd:matrix.org"
|
||||
}
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
room_id:
|
||||
type: string
|
||||
description: The knocked room ID.
|
||||
required: ["room_id"]
|
||||
403:
|
||||
description: |-
|
||||
You do not have permission to knock on the room. A meaningful `errcode`
|
||||
and description error text will be returned. Example reasons for rejection are:
|
||||
|
||||
- The room is not set up for knocking.
|
||||
- The user has been banned from the room.
|
||||
examples:
|
||||
application/json: {
|
||||
"errcode": "M_FORBIDDEN", "error": "You are not allowed to knock on this room."
|
||||
}
|
||||
schema:
|
||||
"$ref": "definitions/errors/error.yaml"
|
||||
404:
|
||||
description: |-
|
||||
The room could not be found or resolved to a room ID.
|
||||
examples:
|
||||
application/json: {
|
||||
"errcode": "M_NOT_FOUND", "error": "That room does not appear to exist."
|
||||
}
|
||||
schema:
|
||||
"$ref": "definitions/errors/error.yaml"
|
||||
429:
|
||||
description: This request was rate-limited.
|
||||
schema:
|
||||
"$ref": "definitions/errors/rate_limited.yaml"
|
||||
tags:
|
||||
- Room membership
|
||||
@ -0,0 +1,322 @@
|
||||
# Copyright 2021 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.
|
||||
|
||||
swagger: '2.0'
|
||||
info:
|
||||
title: "Matrix Federation Knock Room API"
|
||||
version: "1.0.0"
|
||||
host: localhost:8448
|
||||
schemes:
|
||||
- https
|
||||
basePath: /_matrix/federation/v1
|
||||
consumes:
|
||||
- application/json
|
||||
produces:
|
||||
- application/json
|
||||
securityDefinitions:
|
||||
$ref: definitions/security.yaml
|
||||
paths:
|
||||
"/make_knock/{roomId}/{userId}":
|
||||
get:
|
||||
summary: Get information required to make a knock event for a room.
|
||||
description: |-
|
||||
Asks the receiving server to return information that the sending
|
||||
server will need to prepare a knock event for the room.
|
||||
operationId: makeKnock
|
||||
security:
|
||||
- signedRequest: []
|
||||
parameters:
|
||||
- in: path
|
||||
name: roomId
|
||||
type: string
|
||||
description: The room ID that is about to be knocked.
|
||||
required: true
|
||||
x-example: "!abc123:example.org"
|
||||
- in: path
|
||||
name: userId
|
||||
type: string
|
||||
description: The user ID the knock event will be for.
|
||||
required: true
|
||||
x-example: "@someone:example.org"
|
||||
- in: query
|
||||
type: array
|
||||
items:
|
||||
type: string
|
||||
name: ver
|
||||
description: |-
|
||||
The room versions the sending server has support for.
|
||||
required: true # knocking was supported in v7
|
||||
x-example: ["1", "7"]
|
||||
responses:
|
||||
200:
|
||||
description: |-
|
||||
A template to be used for the rest of the [Knocking Rooms](/server-server-api/#knocking-rooms)
|
||||
handshake. Note that events have a different format depending on room version - check the
|
||||
[room version specification](/#room-versions) for precise event formats. **The response body
|
||||
here describes the common event fields in more detail and may be missing other
|
||||
required fields for a PDU.**
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
room_version:
|
||||
type: string
|
||||
description: |-
|
||||
The version of the room where the server is trying to knock.
|
||||
example: "7"
|
||||
event:
|
||||
description: |-
|
||||
An unsigned template event. Note that events have a different format
|
||||
depending on the room version - check the [room version specification](/#room-versions)
|
||||
for precise event formats.
|
||||
type: object
|
||||
title: Event Template
|
||||
properties:
|
||||
sender:
|
||||
type: string
|
||||
description: The user ID of the knocking member.
|
||||
example: "@someone:example.org"
|
||||
origin:
|
||||
type: string
|
||||
description: The name of the resident homeserver.
|
||||
example: "matrix.org"
|
||||
origin_server_ts:
|
||||
type: integer
|
||||
format: int64
|
||||
description: A timestamp added by the resident 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 knocking member.
|
||||
example: "@someone:example.org"
|
||||
content:
|
||||
type: object
|
||||
title: Membership Event Content
|
||||
description: The content of the event.
|
||||
example: {"membership": "knock"}
|
||||
properties:
|
||||
membership:
|
||||
type: string
|
||||
description: The value `knock`.
|
||||
example: "knock"
|
||||
required: ['membership']
|
||||
required:
|
||||
- state_key
|
||||
- origin
|
||||
- origin_server_ts
|
||||
- type
|
||||
- content
|
||||
- sender
|
||||
required:
|
||||
- room_version # knocking was added in v7
|
||||
- event
|
||||
examples:
|
||||
application/json: {
|
||||
"room_version": "7",
|
||||
"event": {
|
||||
"$ref": "examples/minimal_pdu.json",
|
||||
"type": "m.room.member",
|
||||
"state_key": "@someone:example.org",
|
||||
"origin": "example.org",
|
||||
"origin_server_ts": 1549041175876,
|
||||
"sender": "@someone:example.org",
|
||||
"content": {
|
||||
"membership": "knock"
|
||||
}
|
||||
}
|
||||
}
|
||||
400:
|
||||
description: |-
|
||||
The request is invalid or the room the server is attempting
|
||||
to knock upon has a version that is not listed in the `ver`
|
||||
parameters.
|
||||
|
||||
The error should be passed through to clients so that they
|
||||
may give better feedback to users.
|
||||
schema:
|
||||
allOf:
|
||||
- $ref: "../client-server/definitions/errors/error.yaml"
|
||||
- type: object
|
||||
properties:
|
||||
room_version:
|
||||
type: string
|
||||
description: |-
|
||||
The version of the room. Required if the `errcode`
|
||||
is `M_INCOMPATIBLE_ROOM_VERSION`.
|
||||
examples:
|
||||
application/json: {
|
||||
"errcode": "M_INCOMPATIBLE_ROOM_VERSION",
|
||||
"error": "Your homeserver does not support the features required to knock on this room",
|
||||
"room_version": "7"
|
||||
}
|
||||
404:
|
||||
description: |-
|
||||
The room that the knocking server is attempting to knock upon is unknown
|
||||
to the receiving server.
|
||||
schema:
|
||||
allOf:
|
||||
- $ref: "../client-server/definitions/errors/error.yaml"
|
||||
examples:
|
||||
application/json: {
|
||||
"errcode": "M_NOT_FOUND",
|
||||
"error": "Unknown room",
|
||||
}
|
||||
403:
|
||||
description: |-
|
||||
The knocking server or user is not permitted to knock on the room, such as when the
|
||||
server/user is banned or the room is not set up for receiving knocks.
|
||||
schema:
|
||||
allOf:
|
||||
- $ref: "../client-server/definitions/errors/error.yaml"
|
||||
examples:
|
||||
application/json: {
|
||||
"errcode": "M_FORBIDDEN",
|
||||
"error": "You are not permitted to knock on this room",
|
||||
}
|
||||
|
||||
"/send_knock/{roomId}/{eventId}":
|
||||
put:
|
||||
summary: Submit a signed knock event to a resident server.
|
||||
description: |-
|
||||
Submits a signed knock event to the resident server for it to
|
||||
accept into the room's graph. Note that events have
|
||||
a different format depending on the room version - check
|
||||
the [room version specification](/#room-versions) 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.**
|
||||
operationId: sendKnock
|
||||
security:
|
||||
- signedRequest: []
|
||||
parameters:
|
||||
- in: path
|
||||
name: roomId
|
||||
type: string
|
||||
description: The room ID that is about to be knocked upon.
|
||||
required: true
|
||||
x-example: "!abc123:example.org"
|
||||
- in: path
|
||||
name: eventId
|
||||
type: string
|
||||
description: The event ID for the knock event.
|
||||
required: true
|
||||
x-example: "$abc123:example.org"
|
||||
- in: body
|
||||
name: body
|
||||
type: object
|
||||
required: true
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
sender:
|
||||
type: string
|
||||
description: The user ID of the knocking member.
|
||||
example: "@someone:example.org"
|
||||
origin:
|
||||
type: string
|
||||
description: The name of the knocking homeserver.
|
||||
example: "matrix.org"
|
||||
origin_server_ts:
|
||||
type: integer
|
||||
format: int64
|
||||
description: A timestamp added by the knocking 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 knocking member.
|
||||
example: "@someone:example.org"
|
||||
content:
|
||||
type: object
|
||||
title: Membership Event Content
|
||||
description: The content of the event.
|
||||
example: {"membership": "knock"}
|
||||
properties:
|
||||
membership:
|
||||
type: string
|
||||
description: The value `knock`.
|
||||
example: "knock"
|
||||
required: ['membership']
|
||||
required:
|
||||
- state_key
|
||||
- sender
|
||||
- origin
|
||||
- origin_server_ts
|
||||
- type
|
||||
- content
|
||||
example: {
|
||||
"$ref": "examples/minimal_pdu.json",
|
||||
"type": "m.room.member",
|
||||
"state_key": "@someone:example.org",
|
||||
"origin": "example.org",
|
||||
"origin_server_ts": 1549041175876,
|
||||
"sender": "@someone:example.org",
|
||||
"content": {
|
||||
"membership": "knock"
|
||||
}
|
||||
}
|
||||
responses:
|
||||
200:
|
||||
description: |-
|
||||
Information about the room to pass along to clients regarding the
|
||||
knock.
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
knock_room_state:
|
||||
type: array
|
||||
items:
|
||||
$ref: "../../event-schemas/schema/stripped_state.yaml"
|
||||
description: |-
|
||||
A list of simplified events to help the initiator of the knock identify
|
||||
the room. The recommended events to include are the join rules, canonical
|
||||
alias, avatar, name, and encryption state of the room.
|
||||
example:
|
||||
$ref: "../../event-schemas/examples/knock_room_state.json"
|
||||
required: ['knock_room_state']
|
||||
examples:
|
||||
application/json: {
|
||||
"knock_room_state": {"$ref": "../../event-schemas/examples/knock_room_state.json"}
|
||||
}
|
||||
404:
|
||||
description: |-
|
||||
The room that the knocking server is attempting to knock upon is unknown
|
||||
to the receiving server.
|
||||
schema:
|
||||
allOf:
|
||||
- $ref: "../client-server/definitions/errors/error.yaml"
|
||||
examples:
|
||||
application/json: {
|
||||
"errcode": "M_NOT_FOUND",
|
||||
"error": "Unknown room",
|
||||
}
|
||||
403:
|
||||
description: |-
|
||||
The knocking server or user is not permitted to knock on the room, such as when the
|
||||
server/user is banned or the room is not set up for receiving knocks.
|
||||
schema:
|
||||
allOf:
|
||||
- $ref: "../client-server/definitions/errors/error.yaml"
|
||||
examples:
|
||||
application/json: {
|
||||
"errcode": "M_FORBIDDEN",
|
||||
"error": "You are not permitted to knock on this room",
|
||||
}
|
||||
|
||||
@ -0,0 +1,18 @@
|
||||
[
|
||||
{
|
||||
"type": "m.room.name",
|
||||
"sender": "@bob:example.org",
|
||||
"state_key": "",
|
||||
"content": {
|
||||
"name": "Example Room"
|
||||
}
|
||||
},
|
||||
{
|
||||
"type": "m.room.join_rules",
|
||||
"sender": "@bob:example.org",
|
||||
"state_key": "",
|
||||
"content": {
|
||||
"join_rule": "knock"
|
||||
}
|
||||
}
|
||||
]
|
||||
@ -0,0 +1,6 @@
|
||||
{
|
||||
"type": "m.key.verification.done",
|
||||
"content": {
|
||||
"transaction_id": "S0meUniqueAndOpaqueString"
|
||||
}
|
||||
}
|
||||
@ -0,0 +1,10 @@
|
||||
{
|
||||
"type": "m.key.verification.ready",
|
||||
"content": {
|
||||
"from_device": "BobDevice1",
|
||||
"transaction_id": "S0meUniqueAndOpaqueString",
|
||||
"methods": [
|
||||
"m.sas.v1"
|
||||
]
|
||||
}
|
||||
}
|
||||
@ -0,0 +1,15 @@
|
||||
{
|
||||
"$ref": "m.room.member.yaml",
|
||||
"content": {
|
||||
"membership": "knock",
|
||||
"avatar_url": "mxc://example.org/SEsfnsuifSDFSSEF",
|
||||
"displayname": "Alice Margatroid",
|
||||
"reason": "Looking for support"
|
||||
},
|
||||
"unsigned": {
|
||||
"age": 1234,
|
||||
"knock_room_state": {
|
||||
"$ref": "knock_room_state.json"
|
||||
}
|
||||
}
|
||||
}
|
||||
@ -0,0 +1,23 @@
|
||||
---
|
||||
allOf:
|
||||
- $ref: core-event-schema/event.yaml
|
||||
|
||||
description: |-
|
||||
Indicates that a verification process/request has completed successfully.
|
||||
properties:
|
||||
content:
|
||||
properties:
|
||||
transaction_id:
|
||||
type: string
|
||||
description: |-
|
||||
Required when sent as a to-device message. The opaque identifier for
|
||||
the verification process/request.
|
||||
m.relates_to:
|
||||
allOf:
|
||||
- $ref: m.key.verification.m.relates_to.yaml
|
||||
type: object
|
||||
type:
|
||||
enum:
|
||||
- m.key.verification.done
|
||||
type: string
|
||||
type: object
|
||||
@ -0,0 +1,21 @@
|
||||
---
|
||||
description: |-
|
||||
Required when sent as an in-room message. Indicates the
|
||||
`m.key.verification.request` that this message is related to. Note that for
|
||||
encrypted messages, this property should be in the unencrypted portion of the
|
||||
event.
|
||||
properties:
|
||||
rel_type:
|
||||
type: string
|
||||
enum:
|
||||
- m.reference
|
||||
description: |-
|
||||
The relationship type.
|
||||
event_id:
|
||||
type: string
|
||||
description: |-
|
||||
The event ID of the `m.key.verification.request` that this message is
|
||||
related to.
|
||||
type: object
|
||||
type: object
|
||||
title: VerificationRelatesTo
|
||||
@ -0,0 +1,40 @@
|
||||
---
|
||||
allOf:
|
||||
- $ref: core-event-schema/event.yaml
|
||||
|
||||
description: |-
|
||||
Accepts a key verification request. Sent in response to an
|
||||
`m.key.verification.request` event.
|
||||
properties:
|
||||
content:
|
||||
properties:
|
||||
from_device:
|
||||
type: string
|
||||
description: |-
|
||||
The device ID which is accepting the request.
|
||||
transaction_id:
|
||||
type: string
|
||||
description: |-
|
||||
Required when sent as a to-device message. The transaction ID of the
|
||||
verification request, as given in the `m.key.verification.request`
|
||||
message.
|
||||
methods:
|
||||
type: array
|
||||
description: |-
|
||||
The verification methods supported by the sender, corresponding to
|
||||
the verification methods indicated in the
|
||||
`m.key.verification.request` message.
|
||||
items:
|
||||
type: string
|
||||
m.relates_to:
|
||||
allOf:
|
||||
- $ref: m.key.verification.m.relates_to.yaml
|
||||
required:
|
||||
- from_device
|
||||
- methods
|
||||
type: object
|
||||
type:
|
||||
enum:
|
||||
- m.key.verification.ready
|
||||
type: string
|
||||
type: object
|
||||
@ -0,0 +1,44 @@
|
||||
---
|
||||
allOf:
|
||||
- $ref: core-event-schema/event.yaml
|
||||
|
||||
description: |-
|
||||
Begins a key verification process using the `m.reciprocate.v1` method, after
|
||||
scanning a QR code.
|
||||
properties:
|
||||
content:
|
||||
properties:
|
||||
from_device:
|
||||
type: string
|
||||
description: |-
|
||||
The device ID which is initiating the process.
|
||||
transaction_id:
|
||||
type: string
|
||||
description: |-
|
||||
Required when sent as a to-device message. An opaque identifier for
|
||||
the verification process. Must be unique with respect to the devices
|
||||
involved. Must be the same as the `transaction_id` given in the
|
||||
`m.key.verification.request` if this process is originating from a
|
||||
request.
|
||||
method:
|
||||
type: string
|
||||
enum: ["m.reciprocate.v1"]
|
||||
description: |-
|
||||
The verification method to use.
|
||||
secret:
|
||||
type: string
|
||||
description: |-
|
||||
The shared secret from the QR code, encoded using unpadded base64.
|
||||
m.relates_to:
|
||||
allOf:
|
||||
- $ref: m.key.verification.m.relates_to.yaml
|
||||
required:
|
||||
- from_device
|
||||
- method
|
||||
- secret
|
||||
type: object
|
||||
type:
|
||||
enum:
|
||||
- m.key.verification.start
|
||||
type: string
|
||||
type: object
|
||||
@ -0,0 +1,314 @@
|
||||
# Key verification in DMs
|
||||
|
||||
Currently, key verification is done using `to_device` messages. However, since
|
||||
`to_device` messages are not part of a timeline, there is no user-visible
|
||||
record of the key verification.
|
||||
|
||||
As well, the current key verification framework does not provide any feedback
|
||||
when interacting with clients that do not support it; if a client does not
|
||||
support the key verification framework, there is no way for users to discover
|
||||
this other than waiting for a while and noticing that nothing is happening.
|
||||
|
||||
This proposal will solve both problems.
|
||||
|
||||
## Proposal
|
||||
|
||||
The current [key verification
|
||||
framework](https://matrix.org/docs/spec/client_server/r0.5.0#key-verification-framework)
|
||||
will be replaced by a new framework that uses room messages rather than
|
||||
`to_device` messages. Key verification messages will be sent in a [Direct
|
||||
Messaging](https://matrix.org/docs/spec/client_server/r0.5.0#id185) room. If
|
||||
there is no Direct Messaging room between the two users involved, the client
|
||||
that initiates the key verification will create one.
|
||||
|
||||
In this proposal, we use "Alice" to denote the user who initiates the key
|
||||
verification, and "Bob" to denote the other user involved in the key
|
||||
verification.
|
||||
|
||||
### General framework
|
||||
|
||||
#### Requesting a key verification
|
||||
|
||||
To request a key verification, Alice will send an `m.room.message` event with the
|
||||
following properties in its contents:
|
||||
|
||||
- `body`: a fallback message to alert users that their client does not support
|
||||
the key verification framework, and that they should use a different method
|
||||
to verify keys. For example, "Alice is requesting to verify keys with you.
|
||||
However, your client does not support this method, so you will need to use
|
||||
the legacy method of key verification."
|
||||
|
||||
Clients that do support the key verification framework should hide the body
|
||||
and instead present the user with an interface to accept or reject the key
|
||||
verification.
|
||||
|
||||
The event may also contain `format` and `formatted_body` properties as
|
||||
described in the [m.room.message
|
||||
msgtypes](https://matrix.org/docs/spec/client_server/r0.5.0#m-room-message-msgtypes)
|
||||
section of the spec. Clients that support the key verification should
|
||||
similarly hide these from the user.
|
||||
- `msgtype`: `m.key.verification.request`
|
||||
- `methods`: the verification methods supported by Alice's client
|
||||
- `to`: Bob's Matrix ID. Users should only respond to verification requests if
|
||||
they are named in this field. Users who are not named in this field and who
|
||||
did not send this event should ignore all other events that have a
|
||||
`m.reference` relationship with this event.
|
||||
- `from_device`: Alice's device ID. This is required since some verification
|
||||
methods may use the device IDs as part of the verification process.
|
||||
|
||||
Key verifications will be identified by the event ID of the key verification
|
||||
request event.
|
||||
|
||||
Clients should ignore verification requests that have been accepted or
|
||||
cancelled, or if they do not belong to the sending or target users.
|
||||
|
||||
The way that clients display this event can depend on which user and device the
|
||||
client belongs to, and what state the verification is in. For example:
|
||||
|
||||
- If the verification has been completed (there is an `m.key.verification.done`
|
||||
or `m.key.verification.cancel` event), the client can indicate that the
|
||||
verification was successful or had an error.
|
||||
- If the verification has been accepted (there is an `m.key.verification.start`
|
||||
event) but has not been completed, the two devices involved can indicate that
|
||||
the verification is in progress and can use this event as a place in the
|
||||
room's timeline to display progress of the key verification and to interact
|
||||
with the user as necessary. Other devices can indicate that the verification
|
||||
is in progress on other devices.
|
||||
- If the verification has not been accepted, clients for the target user can
|
||||
indicate that a verification has been requested and allow the user to accept
|
||||
the verification on that device. The sending client can indicate that it is
|
||||
waiting for the request to be accepted, and the sending user's other clients
|
||||
can indicate the that a request was initiated on a different device.
|
||||
|
||||
Clients may choose to display or not to display events of any other type that
|
||||
reference the original request event; but it must not have any effect on the
|
||||
verification itself.
|
||||
|
||||
#### Accepting a key verification
|
||||
|
||||
To accept a key verification, Bob will send an `m.key.verification.ready` event
|
||||
with the following properties in its contents:
|
||||
|
||||
- `m.relates_to`: an object with the properties:
|
||||
- `rel_type`: `m.reference`
|
||||
- `event_id`: the event ID of the key verification request that is being
|
||||
accepted
|
||||
- `methods`: an array of verification methods that the device supports
|
||||
- `from_device`: Bob's device ID. This is required since some verification
|
||||
methods may use the device IDs as part of the verification process.
|
||||
|
||||
(Note: the form of the `m.relates_to` property is based on the current state of
|
||||
[MSC2674](https://github.com/matrix-org/matrix-doc/pull/2674), but is
|
||||
independent from it since this MSC does not rely on any aggregations features.)
|
||||
|
||||
Clients should ignore `m.key.verification.ready` events that correspond to
|
||||
verification requests that they did not send.
|
||||
|
||||
After this, either Alice or Bob may start the verification by sending an
|
||||
`m.key.verification.start` event with the following properties in its contents:
|
||||
|
||||
- `m.relates_to`: an object with the properties:
|
||||
- `rel_type`: `m.reference`
|
||||
- `event_id`: the event ID of the key verification request that is being
|
||||
started
|
||||
- `method`: the key verification method that is being used. This should be a
|
||||
method that both Alice's and Bob's devices support.
|
||||
- `from_device`: The user's device ID.
|
||||
|
||||
If both Alice and Bob send an `m.key.verification.start` message, and they both
|
||||
specify the same verification method, then the event sent by the user whose
|
||||
user ID is the smallest is used, and the other event is ignored. If they both
|
||||
send an `m.key.verification.start` message and the method is different, then
|
||||
the verification should be cancelled with a `code` of `m.unexpected_message`.
|
||||
|
||||
After the `m.key.verification.start` event is sent, the devices may exchange
|
||||
messages (if any) according to the verification method in use.
|
||||
|
||||
#### Rejecting a key verification
|
||||
|
||||
To reject a key verification, Alice or Bob will send an
|
||||
`m.key.verification.cancel` event with the following properties in its
|
||||
contents:
|
||||
|
||||
- `m.relates_to`: an object with the properties:
|
||||
- `rel_type`: `m.reference`
|
||||
- `event_id`: the event ID of the key verification that is being cancelled
|
||||
- `reason`: A human readable description of the `code`. The client should only
|
||||
rely on this string if it does not understand the `code`.
|
||||
- `code`: The error code for why the process/request was cancelled by the
|
||||
user. The contents are the same as the `code` property of the currently
|
||||
defined [`m.key.verification.cancel` to-device
|
||||
event](https://matrix.org/docs/spec/client_server/r0.5.0#m-key-verification-cancel),
|
||||
or as defined for specific key verification methods.
|
||||
|
||||
This message may be sent at any point in the key verification process. Any
|
||||
subsequent key verification messages relating to the same request are ignored.
|
||||
However, this does not undo any verifications that have already been done.
|
||||
|
||||
#### Concluding a key verification
|
||||
|
||||
When the other user's key is verified and no more messages are expected, each
|
||||
party will send an `m.key.verification.done` event with the following
|
||||
properties in its contents:
|
||||
|
||||
- `m.relates_to`: an object with the properties:
|
||||
- `rel_type`: `m.reference`
|
||||
- `event_id`: the event ID of the key verification that is being concluded
|
||||
|
||||
This provides a record within the room of the result of the verification.
|
||||
|
||||
Any subsequent key verification messages relating to the same request are
|
||||
ignored.
|
||||
|
||||
Although a client may have successfully completed its side of the verification,
|
||||
it may wait until receiving an `m.key.verification.done` (or
|
||||
`m.key.verification.cancel`) event from the other device before informing the
|
||||
user that the verification was successful or unsuccessful.
|
||||
|
||||
#### Other events
|
||||
|
||||
Key verification methods may define their own event types, or extensions to the
|
||||
above event types. All events sent as part of a key verification process
|
||||
should have an `m.relates_to` property as defined for
|
||||
`m.key.verification.accept` or `m.key.verification.cancel` events.
|
||||
|
||||
Clients should ignore events with an `m.relates_to` that have a `rel_type` of
|
||||
`m.reference` that refer to a verification where it is neither the requester
|
||||
nor the accepter.
|
||||
|
||||
Clients should not redact or edit verification messages. A client may ignore
|
||||
redactions or edits of key verification messages, or may cancel the
|
||||
verification with a `code` of `m.unexpected_message` when it receives a
|
||||
redaction or edit.
|
||||
|
||||
### SAS verification
|
||||
|
||||
The messages used in SAS verification are the same as those currently defined,
|
||||
except that instead of the `transaction_id` property, an `m.relates_to`
|
||||
property, as defined above, is used instead.
|
||||
|
||||
If the key verification messages are encrypted, the hash commitment sent in the
|
||||
`m.key.verification.accept` message MUST be based on the decrypted
|
||||
`m.key.verification.start` message contents, and include the `m.relates_to`
|
||||
field, even if the decrypted message contents do not include that field. For
|
||||
example, if Alice sends a message to start the SAS verification:
|
||||
|
||||
```json
|
||||
{
|
||||
"content": {
|
||||
"algorithm": "m.megolm.v1.aes-sha2",
|
||||
"ciphertext": "ABCDEFG...",
|
||||
"device_id": "Dynabook",
|
||||
"sender_key": "alice+sender+key",
|
||||
"session_id": "session+id",
|
||||
"m.relates_to": {
|
||||
"rel_type": "m.reference",
|
||||
"event_id": "$verification_request_event"
|
||||
}
|
||||
},
|
||||
"event_id": "$event_id",
|
||||
"origin_server_ts": 1234567890,
|
||||
"sender": "@alice:example.org",
|
||||
"type": "m.room.encrypted",
|
||||
"room_id": "!room_id:example.org"
|
||||
}
|
||||
```
|
||||
|
||||
which, when decrypted, yields:
|
||||
|
||||
```json
|
||||
{
|
||||
"room_id": "!room_id:example.org",
|
||||
"type": "m.key.verification.start",
|
||||
"content": {
|
||||
"from_device": "Dynabook",
|
||||
"hashes": [
|
||||
"sha256"
|
||||
],
|
||||
"key_agreement_protocols": [
|
||||
"curve25519"
|
||||
],
|
||||
"message_authentication_codes": [
|
||||
"hkdf-hmac-sha256"
|
||||
],
|
||||
"method": "m.sas.v1",
|
||||
"short_authentication_string": [
|
||||
"decimal",
|
||||
"emoji"
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
then the hash commitment will be based on the message contents:
|
||||
|
||||
```json
|
||||
{
|
||||
"from_device": "Dynabook",
|
||||
"hashes": [
|
||||
"sha256"
|
||||
],
|
||||
"key_agreement_protocols": [
|
||||
"curve25519"
|
||||
],
|
||||
"message_authentication_codes": [
|
||||
"hkdf-hmac-sha256"
|
||||
],
|
||||
"method": "m.sas.v1",
|
||||
"short_authentication_string": [
|
||||
"decimal",
|
||||
"emoji"
|
||||
],
|
||||
"m.relates_to": {
|
||||
"rel_type": "m.reference",
|
||||
"event_id": "$verification_request_event"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Alternatives
|
||||
|
||||
Messages sent by the verification methods, after the initial key verification
|
||||
request message, could be sent as to-device messages. The
|
||||
`m.key.verification.ready`, `m.key.verification.cancel`, and
|
||||
`m.key.verification.done` messages must be still be sent in the room, as the
|
||||
`m.key.verification.ready` notifies the sender's other devices that the request
|
||||
has been acknowledged, and the `m.key.verification.cancel` and
|
||||
`m.key.verification.done` provide a record of the status of the key
|
||||
verification.
|
||||
|
||||
However, it seems more natural to have all messages sent via the same
|
||||
mechanism.
|
||||
|
||||
## Potential issues
|
||||
|
||||
If a user wants to verify their own device, this will require the creation of a
|
||||
Direct Messaging room with themselves. Instead, clients may use the current
|
||||
`to_device` messages for verifying the user's other devices.
|
||||
|
||||
Direct Messaging rooms could have end-to-end encryption enabled, and some
|
||||
clients can be configured to only send decryption keys to verified devices.
|
||||
Key verification messages should be granted an exception to this (so that
|
||||
decryption keys are sent to all of the target user's devices), or should be
|
||||
sent unencrypted, so that unverified devices will be able to be verified.
|
||||
|
||||
Users might have multiple Direct Messaging rooms with other users. In this
|
||||
case, clients could need to prompt the user to select the room in which they
|
||||
want to perform the verification, or could select a room.
|
||||
|
||||
## Security considerations
|
||||
|
||||
Key verification is subject to the room's visibility settings, and may be
|
||||
visible to other users in the room. However, key verification does not rely on
|
||||
secrecy, so this will no affect the security of the key verification. This may
|
||||
reveal to others in the room that Alice and Bob know each other, but this is
|
||||
already revealed by the fact that they share a Direct Messaging room.
|
||||
|
||||
This framework allows users to see what key verifications they have performed
|
||||
in the past. However, since key verification messages are not secured, this
|
||||
should not be considered as authoritative.
|
||||
|
||||
## Conclusion
|
||||
|
||||
By using room messages to perform key verification rather than `to_device`
|
||||
messages, the user experience of key verification can be improved.
|
||||
@ -0,0 +1,26 @@
|
||||
# MSC2713: Remove deprecated Identity Service endpoints
|
||||
|
||||
Implementations will have had plenty of time to adopt the new v2 API for Identity Servers, so
|
||||
we should clean out the old endpoints.
|
||||
|
||||
All deprecated endpoints in the r0.3.0 Identity Service API specification are to be removed.
|
||||
|
||||
For completeness, this includes:
|
||||
|
||||
* `GET /_matrix/identity/api/v1`
|
||||
* `GET /_matrix/identity/api/v1/pubkey/{keyId}`
|
||||
* `GET /_matrix/identity/api/v1/pubkey/isvalid`
|
||||
* `GET /_matrix/identity/api/v1/pubkey/ephemeral/isvalid`
|
||||
* `GET /_matrix/identity/api/v1/lookup`
|
||||
* `POST /_matrix/identity/api/v1/bulk_lookup`
|
||||
* `POST /_matrix/identity/api/v1/validate/email/requestToken`
|
||||
* `POST /_matrix/identity/api/v1/validate/email/submitToken`
|
||||
* `GET /_matrix/identity/api/v1/validate/email/submitToken`
|
||||
* `POST /_matrix/identity/api/v1/validate/msisdn/requestToken`
|
||||
* `POST /_matrix/identity/api/v1/validate/msisdn/submitToken`
|
||||
* `GET /_matrix/identity/api/v1/validate/msisdn/submitToken`
|
||||
* `GET /_matrix/identity/api/v1/3pid/getValidated3pid`
|
||||
* `POST /_matrix/identity/api/v1/3pid/bind`
|
||||
* `POST /_matrix/identity/api/v1/3pid/unbind`
|
||||
* `POST /_matrix/identity/api/v1/store-invite`
|
||||
* `POST /_matrix/identity/api/v1/sign-ed25519`
|
||||
@ -0,0 +1,17 @@
|
||||
# Spec diagrams
|
||||
|
||||
Non-ascii diagrams for the spec can be placed here for reference in the actual spec.
|
||||
Please include source material so the diagram can be recreated by a future editor.
|
||||
|
||||
https://www.diagrams.net/ is a great ([open source](https://github.com/jgraph/drawio))
|
||||
tool for these sorts of things - include your `.drawio` file next to your diagram.
|
||||
|
||||
Suggested settings for diagrams.net:
|
||||
* Export as PNG.
|
||||
* 100% size.
|
||||
* `20` for a border width.
|
||||
* No transparent background, shadow, or grid.
|
||||
* Include a copy of the diagram.
|
||||
|
||||
To reference a diagram, use the absolute path when compiled. For example,
|
||||
``
|
||||
@ -0,0 +1 @@
|
||||
<mxfile host="app.diagrams.net" modified="2021-04-28T19:35:50.494Z" agent="5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/90.0.4430.85 Safari/537.36" etag="-IOh23FjJiPnGlGWLseU" version="14.6.6" type="device"><diagram id="4a_pTli-mcEMNPq0ciXK" name="Page-1">3Vvdb6M4EP9rIt09NMIGA3ncZtvbh73TSn243X1ZOYmT0BIcOaZJ9q8/E0z4cggEgulVqoqHsbHHv/nwjDsyp5vDXwxv13/TBfFH0FgcRubnEYTAAa74E1GOMWViopiwYt5CMqWEF+83kURDUkNvQXY5Rk6pz71tnjinQUDmPEfDjNF9nm1J/fxXt3hFSoSXOfbL1H+9BV/HVBc6Kf0L8Vbr5MvAnsRvNjhhlivZrfGC7jMk82lkThmlPH7aHKbEj4SXyCXu93zh7XlijAS8TodvBvr96euj/xL83G+Dn2gaTvgDkMO8Yz+UKxYjvFIvkJPmx0QSZCEEI5uU8TVd0QD7Tyn1kdEwWJDoc4ZopTxfKd0KIhDEV8L5Ue4yDjkVpDXf+PJt/M3oQxfXKEk7GrI5qVqYxApmK8Ir+OB5JwSECd0Qzo6iHyM+5t57fh5YYml15pNdPzGGjxmGrZAf32VG/hYRBINUCziRmJBKYdqFrWvGLx7iGSStzFJS0gkOTaBhqaDhEyykogEb5ODx75nnH9FQY4hk8/NBDn1qHJNGIGTwPcMZtX9kX6b9Tq2kY4dIhKgmFC01FCUGjDEwHDMeqhk6S3Cy3DycoDUZ25kfx8qPGM9cDpLCrinqLVD4rG1Wot4CqIo/j/q0dzIdulzuCC/06EYzSorhBe8eL6tFHvT7teB52eITWvbCXaqM3zthnByqQXcRI9ApSBjJ9j51XcCQtHXGbSV8KgzlpNdYVHaFETEoG0VO6/nNm799cH8DO1JysRduOyW/P/4hVG3qDGuJGRK/YIxRxjOA29wC6NEt1ASMWQmYB2NsI6ulW+gBMSXAKEPMRvZySQP+jDeeH23OVIjbI5E5+Yfs72NMLUu7MXVVehcGujUvF5HVDMhAVu1kr34Uz2xnqWsrWautNks7rdrkQekLQoVDiqldX5R+KrY8hreMVhfOfG8+grYv5vI4E/KwV9FTxPOLhT7Z6XVp8Caf5ug66lg1VavtobsdKsq6Jca5EMH3sduXNq7HYKT2xqFr0QgaeigCnEEGr05W0426mq4tqVEXMBei1340vZzAUmevBuVGzWKuT7sbVUadGu1lO53RFnfCSWdG1rVdq52dPddnCgkjB+WHiFdVSv31arCNjx3F5RPW1ccjLXBraaLrIcuy6yGrs4yDsrCly82nHrtRhHdLbksHhK7mqFxogrsYLGTVg1XTWgUo1CqQWV2hs41Kfn21CqhMwA/Ae9+SNGp6tM3Fal+I/064N8cdK0lHZycRzN+iIU2BbVr5ohqYoIEAVXkuG0qlqGWV4eOitrpeJUy7A4ZffjAHFQzcEBf+L6B0NUpwEGoZJfRgpspJhbeAKozSoJMK5zBKW1IhuRXT8SWKvouC+m9YJEF6RpBPB06YMEknl1k8FP8R0JOmiN8N2cwI+7NC4qChxMsmpl1JqXCGVKXCoELY9r2EbSpzEdIAxMmIU+MBz4QwB5qQKJSVaiebu/E8r+Fmmyw0oAFJSPGsHV1JkKtxjuvCm3JuTQP0wt08YFUfPM+3EtT8Gi/Jle2S/pjrVug3O3ZmIY7ZvGNI171OejXcmvRy4ISTwoETXcmkwEr+ewBaNNNr+DF7+s8M5tN/</diagram></mxfile>
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 28 KiB |
Loading…
Reference in New Issue