Merge remote-tracking branch 'matrix-org/master' into travis/s2s/key-mgmt
Travis Ralston
6 years ago
commit
f09db16027
@ -0,0 +1,18 @@
|
|||||||
|
# Copyright 2018 New Vector Ltd
|
||||||
|
#
|
||||||
|
# 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.
|
||||||
|
homeserverAccessToken:
|
||||||
|
type: apiKey
|
||||||
|
description: The ``hs_token`` provided by the application service's registration.
|
||||||
|
name: access_token
|
||||||
|
in: query
|
||||||
@ -0,0 +1,78 @@
|
|||||||
|
# Copyright 2016 OpenMarket Ltd
|
||||||
|
# Copyright 2018 New Vector Ltd
|
||||||
|
#
|
||||||
|
# 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 Application Service API"
|
||||||
|
version: "1.0.0"
|
||||||
|
host: localhost:8008
|
||||||
|
schemes:
|
||||||
|
- https
|
||||||
|
- http
|
||||||
|
basePath: /_matrix/app/v1
|
||||||
|
produces:
|
||||||
|
- application/json
|
||||||
|
securityDefinitions:
|
||||||
|
$ref: definitions/security.yaml
|
||||||
|
paths:
|
||||||
|
"/transactions/{txnId}":
|
||||||
|
put:
|
||||||
|
summary: Send some events to the application service.
|
||||||
|
description: |-
|
||||||
|
This API is called by the homeserver when it wants to push an event
|
||||||
|
(or batch of events) to the application service.
|
||||||
|
|
||||||
|
Note that the application service should distinguish state events
|
||||||
|
from message events via the presence of a ``state_key``, rather than
|
||||||
|
via the event type.
|
||||||
|
operationId: sendTransaction
|
||||||
|
security:
|
||||||
|
- homeserverAccessToken: []
|
||||||
|
parameters:
|
||||||
|
- in: path
|
||||||
|
name: txnId
|
||||||
|
type: string
|
||||||
|
description: |-
|
||||||
|
The transaction ID for this set of events. Homeservers generate
|
||||||
|
these IDs and they are used to ensure idempotency of requests.
|
||||||
|
required: true
|
||||||
|
x-example: "35"
|
||||||
|
- in: body
|
||||||
|
name: body
|
||||||
|
description: A list of events.
|
||||||
|
schema:
|
||||||
|
type: object
|
||||||
|
example: {
|
||||||
|
"events": [
|
||||||
|
{"$ref": "../../event-schemas/examples/m.room.member"},
|
||||||
|
{"$ref": "../../event-schemas/examples/m.room.message#m.text"}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
description: Transaction information
|
||||||
|
properties:
|
||||||
|
events:
|
||||||
|
type: array
|
||||||
|
description: |-
|
||||||
|
A list of events, formatted as per the Client-Server API.
|
||||||
|
items:
|
||||||
|
type: object
|
||||||
|
title: Event
|
||||||
|
required: ["events"]
|
||||||
|
responses:
|
||||||
|
200:
|
||||||
|
description: The transaction was processed successfully.
|
||||||
|
examples:
|
||||||
|
application/json: {}
|
||||||
|
schema:
|
||||||
|
type: object
|
||||||
@ -0,0 +1,88 @@
|
|||||||
|
# Copyright 2018 New Vector Ltd
|
||||||
|
#
|
||||||
|
# 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 Application Service Room Directory API"
|
||||||
|
version: "1.0.0"
|
||||||
|
host: localhost:8008
|
||||||
|
schemes:
|
||||||
|
- https
|
||||||
|
- http
|
||||||
|
basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
|
||||||
|
consumes:
|
||||||
|
- application/json
|
||||||
|
produces:
|
||||||
|
- application/json
|
||||||
|
securityDefinitions:
|
||||||
|
# Note: this is the same access_token definition used elsewhere in the client
|
||||||
|
# server API, however this expects an access token for an application service.
|
||||||
|
$ref: definitions/security.yaml
|
||||||
|
paths:
|
||||||
|
"/directory/list/appservice/{networkId}/{roomId}":
|
||||||
|
put:
|
||||||
|
summary: |-
|
||||||
|
Updates a room's visibility in the application service's room directory.
|
||||||
|
description: |-
|
||||||
|
Updates the visibility of a given room on the application service's room
|
||||||
|
directory.
|
||||||
|
|
||||||
|
This API is similar to the room directory visibility API used by clients
|
||||||
|
to update the homeserver's more general room directory.
|
||||||
|
|
||||||
|
This API requires the use of an application service access token (``as_token``)
|
||||||
|
instead of a typical client's access_token. This API cannot be invoked by
|
||||||
|
users who are not identified as application services.
|
||||||
|
operationId: updateAppserviceRoomDirectoryVsibility
|
||||||
|
parameters:
|
||||||
|
- in: path
|
||||||
|
type: string
|
||||||
|
name: networkId
|
||||||
|
description: |-
|
||||||
|
The protocol (network) ID to update the room list for. This would
|
||||||
|
have been provided by the application service as being listed as
|
||||||
|
a supported protocol.
|
||||||
|
required: true
|
||||||
|
x-example: "irc"
|
||||||
|
- in: path
|
||||||
|
type: string
|
||||||
|
name: roomId
|
||||||
|
description: The room ID to add to the directory.
|
||||||
|
required: true
|
||||||
|
x-example: "!somewhere:domain.com"
|
||||||
|
- in: body
|
||||||
|
name: body
|
||||||
|
required: true
|
||||||
|
schema:
|
||||||
|
type: object
|
||||||
|
properties:
|
||||||
|
visibility:
|
||||||
|
type: string
|
||||||
|
enum: ["public", "private"]
|
||||||
|
description: |-
|
||||||
|
Whether the room should be visible (public) in the directory
|
||||||
|
or not (private).
|
||||||
|
example: "public"
|
||||||
|
required: ['visibility']
|
||||||
|
security:
|
||||||
|
# again, this is the appservice's token - not a typical client's
|
||||||
|
- accessToken: []
|
||||||
|
responses:
|
||||||
|
200:
|
||||||
|
description: The room's directory visibility has been updated.
|
||||||
|
schema:
|
||||||
|
type: object
|
||||||
|
examples:
|
||||||
|
application/json: {}
|
||||||
|
tags:
|
||||||
|
- Application service room directory management
|
||||||
@ -0,0 +1,24 @@
|
|||||||
|
# Copyright 2018 New Vector Ltd
|
||||||
|
#
|
||||||
|
# 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.
|
||||||
|
title: Homeserver Information
|
||||||
|
description: |-
|
||||||
|
Used by clients to discover homeserver information.
|
||||||
|
type: object
|
||||||
|
properties:
|
||||||
|
base_url:
|
||||||
|
type: string
|
||||||
|
description: The base URL for the homeserver for client-server connections.
|
||||||
|
example: https://matrix.example.com
|
||||||
|
required:
|
||||||
|
- base_url
|
||||||
@ -0,0 +1,24 @@
|
|||||||
|
# Copyright 2018 New Vector Ltd
|
||||||
|
#
|
||||||
|
# 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.
|
||||||
|
title: Identity Server Information
|
||||||
|
description: |-
|
||||||
|
Used by clients to discover identity server information.
|
||||||
|
type: object
|
||||||
|
properties:
|
||||||
|
base_url:
|
||||||
|
type: string
|
||||||
|
description: The base URL for the identity server for client-server connections.
|
||||||
|
example: https://identity.example.com
|
||||||
|
required:
|
||||||
|
- base_url
|
||||||
@ -0,0 +1,66 @@
|
|||||||
|
# Copyright 2018 New Vector Ltd
|
||||||
|
#
|
||||||
|
# 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 Server Discovery API"
|
||||||
|
version: "1.0.0"
|
||||||
|
host: localhost:8008
|
||||||
|
schemes:
|
||||||
|
- https
|
||||||
|
basePath: /.well-known
|
||||||
|
produces:
|
||||||
|
- application/json
|
||||||
|
paths:
|
||||||
|
"/matrix/client":
|
||||||
|
get:
|
||||||
|
summary: Gets Matrix server discovery information about the domain.
|
||||||
|
description: |-
|
||||||
|
Gets discovery information about the domain. The file may include
|
||||||
|
additional keys, which MUST follow the Java package naming convention,
|
||||||
|
e.g. ``com.example.myapp.property``. This ensures property names are
|
||||||
|
suitably namespaced for each application and reduces the risk of
|
||||||
|
clashes.
|
||||||
|
|
||||||
|
Note that this endpoint is not necessarily handled by the homeserver,
|
||||||
|
but by another webserver, to be used for discovering the homeserver URL.
|
||||||
|
operationId: getWellknown
|
||||||
|
responses:
|
||||||
|
200:
|
||||||
|
description: Server discovery information.
|
||||||
|
examples:
|
||||||
|
application/json: {
|
||||||
|
"m.homeserver": {
|
||||||
|
"base_url": "https://matrix.example.com"
|
||||||
|
},
|
||||||
|
"m.identity_server": {
|
||||||
|
"base_url": "https://identity.example.com"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
schema:
|
||||||
|
type: object
|
||||||
|
properties:
|
||||||
|
m.homeserver:
|
||||||
|
description: Information about the homeserver to connect to.
|
||||||
|
"$ref": "definitions/wellknown/homeserver.yaml"
|
||||||
|
m.identity_server:
|
||||||
|
description: Optional. Information about the identity server to connect to.
|
||||||
|
"$ref": "definitions/wellknown/identity_server.yaml"
|
||||||
|
additionalProperties:
|
||||||
|
description: Application-dependent keys using Java package naming convention.
|
||||||
|
required:
|
||||||
|
- m.homeserver
|
||||||
|
404:
|
||||||
|
description: No server discovery information available.
|
||||||
|
tags:
|
||||||
|
- Server administration
|
||||||
@ -0,0 +1 @@
|
|||||||
|
!.gitignore
|
||||||
@ -0,0 +1,30 @@
|
|||||||
|
[tool.towncrier]
|
||||||
|
filename = "../application_service.rst"
|
||||||
|
directory = "newsfragments"
|
||||||
|
issue_format = "`#{issue} <https://github.com/matrix-org/matrix-doc/issues/{issue}>`_"
|
||||||
|
title_format = "{version}"
|
||||||
|
|
||||||
|
[[tool.towncrier.type]]
|
||||||
|
directory = "breaking"
|
||||||
|
name = "Breaking Changes"
|
||||||
|
showcontent = true
|
||||||
|
|
||||||
|
[[tool.towncrier.type]]
|
||||||
|
directory = "deprecation"
|
||||||
|
name = "Deprecations"
|
||||||
|
showcontent = true
|
||||||
|
|
||||||
|
[[tool.towncrier.type]]
|
||||||
|
directory = "new"
|
||||||
|
name = "New Endpoints"
|
||||||
|
showcontent = true
|
||||||
|
|
||||||
|
[[tool.towncrier.type]]
|
||||||
|
directory = "feature"
|
||||||
|
name = "Backwards Compatible Changes"
|
||||||
|
showcontent = true
|
||||||
|
|
||||||
|
[[tool.towncrier.type]]
|
||||||
|
directory = "clarification"
|
||||||
|
name = "Spec Clarifications"
|
||||||
|
showcontent = true
|
||||||
@ -0,0 +1 @@
|
|||||||
|
Specify how to control the power level required for ``@room``
|
||||||
@ -0,0 +1 @@
|
|||||||
|
Add ``.well-known`` server discovery method
|
||||||
@ -0,0 +1 @@
|
|||||||
|
Share room decryption keys between devices
|
||||||
@ -0,0 +1 @@
|
|||||||
|
Add a common standard for user, room, and group mentions in messages.
|
||||||
@ -0,0 +1 @@
|
|||||||
|
Add server ACLs as an option for controlling federation in a room.
|
||||||
@ -0,0 +1 @@
|
|||||||
|
Clarify that new push rules should be enabled by default, and that unrecognised conditions should not match.
|
||||||
@ -0,0 +1 @@
|
|||||||
|
Add new push rules for encrypted events and ``@room`` notifications.
|
||||||
@ -0,0 +1 @@
|
|||||||
|
Add third party network room directories, as provided by application services.
|
||||||
@ -0,0 +1 @@
|
|||||||
|
Clarify the supported HTML features for room messages.
|
||||||
@ -0,0 +1 @@
|
|||||||
|
Move the ``invite_room_state`` definition under ``unsigned`` where it actually resides.
|
||||||
@ -0,0 +1 @@
|
|||||||
|
Clarify the object structures and defaults for Filters.
|
||||||
@ -0,0 +1 @@
|
|||||||
|
Clarify instances of ``type: number`` in the swagger/OpenAPI schema definitions.
|
||||||
@ -0,0 +1 @@
|
|||||||
|
Clarify that left rooms also have account data in ``/sync``.
|
||||||
@ -0,0 +1 @@
|
|||||||
|
Fix naming of the body field in ``PUT /directory/room``.
|
||||||
@ -0,0 +1 @@
|
|||||||
|
Clarify the filter object schema used in room searching.
|
||||||
@ -0,0 +1 @@
|
|||||||
|
Document the 403 error for sending state events.
|
||||||
@ -0,0 +1 @@
|
|||||||
|
specify how to handle multiple olm sessions with the same device
|
||||||
@ -0,0 +1 @@
|
|||||||
|
Add more presence options to the ``set_presence`` parameter of ``/sync``. (Thanks @mujx!)
|
||||||
@ -0,0 +1,6 @@
|
|||||||
|
r0.1.0
|
||||||
|
======
|
||||||
|
|
||||||
|
The first release of the Push Gateway specification. This release contains
|
||||||
|
a single endpoint, ``/notify``, that pushers may use to send push notifications
|
||||||
|
to clients.
|
||||||
@ -0,0 +1 @@
|
|||||||
|
!.gitignore
|
||||||
@ -0,0 +1,30 @@
|
|||||||
|
[tool.towncrier]
|
||||||
|
filename = "../push_gateway.rst"
|
||||||
|
directory = "newsfragments"
|
||||||
|
issue_format = "`#{issue} <https://github.com/matrix-org/matrix-doc/issues/{issue}>`_"
|
||||||
|
title_format = "{version}"
|
||||||
|
|
||||||
|
[[tool.towncrier.type]]
|
||||||
|
directory = "breaking"
|
||||||
|
name = "Breaking Changes"
|
||||||
|
showcontent = true
|
||||||
|
|
||||||
|
[[tool.towncrier.type]]
|
||||||
|
directory = "deprecation"
|
||||||
|
name = "Deprecations"
|
||||||
|
showcontent = true
|
||||||
|
|
||||||
|
[[tool.towncrier.type]]
|
||||||
|
directory = "new"
|
||||||
|
name = "New Endpoints"
|
||||||
|
showcontent = true
|
||||||
|
|
||||||
|
[[tool.towncrier.type]]
|
||||||
|
directory = "feature"
|
||||||
|
name = "Backwards Compatible Changes"
|
||||||
|
showcontent = true
|
||||||
|
|
||||||
|
[[tool.towncrier.type]]
|
||||||
|
directory = "clarification"
|
||||||
|
name = "Spec Clarifications"
|
||||||
|
showcontent = true
|
||||||
@ -0,0 +1,14 @@
|
|||||||
|
{
|
||||||
|
"content": {
|
||||||
|
"algorithm": "m.megolm.v1.aes-sha2",
|
||||||
|
"room_id": "!Cuyf34gef24t:localhost",
|
||||||
|
"session_id": "X3lUlvLELLYxeTx4yOVu6UDpasGEVO0Jbu+QFnm0cKQ",
|
||||||
|
"session_key": "AgAAAADxKHa9uFxcXzwYoNueL5Xqi69IkD4sni8Llf...",
|
||||||
|
"sender_key": "RF3s+E7RkTQTGF2d8Deol0FkQvgII2aJDf3/Jp5mxVU",
|
||||||
|
"sender_claimed_ed25519_key": "aj40p+aw64yPIdsxoog8jhPu9i7l7NcFRecuOQblE3Y",
|
||||||
|
"forwarding_curve25519_key_chain": [
|
||||||
|
"hPQNcabIABgGnx3/ACv/jmMmiQHoeFfuLB17tzWp6Hw"
|
||||||
|
]
|
||||||
|
},
|
||||||
|
"type": "m.forwarded_room_key"
|
||||||
|
}
|
||||||
@ -0,0 +1,14 @@
|
|||||||
|
{
|
||||||
|
"age": 242352,
|
||||||
|
"content": {
|
||||||
|
"allow_ip_literals": false,
|
||||||
|
"allow": ["*"],
|
||||||
|
"deny": ["*.evil.com", "evil.com"]
|
||||||
|
},
|
||||||
|
"state_key": "",
|
||||||
|
"origin_server_ts": 1431961217939,
|
||||||
|
"event_id": "$WLGTSEFSEF:localhost",
|
||||||
|
"type": "m.room.server_acl",
|
||||||
|
"room_id": "!Cuyf34gef24t:localhost",
|
||||||
|
"sender": "@example:localhost"
|
||||||
|
}
|
||||||
@ -0,0 +1,8 @@
|
|||||||
|
{
|
||||||
|
"content": {
|
||||||
|
"action": "cancel_request",
|
||||||
|
"requesting_device_id": "RJYKSTBOIE",
|
||||||
|
"request_id": "1495474790150.19"
|
||||||
|
},
|
||||||
|
"type": "m.room_key_request"
|
||||||
|
}
|
||||||
@ -0,0 +1,14 @@
|
|||||||
|
{
|
||||||
|
"content": {
|
||||||
|
"body": {
|
||||||
|
"algorithm": "m.megolm.v1.aes-sha2",
|
||||||
|
"room_id": "!Cuyf34gef24t:localhost",
|
||||||
|
"session_id": "X3lUlvLELLYxeTx4yOVu6UDpasGEVO0Jbu+QFnm0cKQ",
|
||||||
|
"sender_key": "RF3s+E7RkTQTGF2d8Deol0FkQvgII2aJDf3/Jp5mxVU"
|
||||||
|
},
|
||||||
|
"action": "request",
|
||||||
|
"requesting_device_id": "RJYKSTBOIE",
|
||||||
|
"request_id": "1495474790150.19"
|
||||||
|
},
|
||||||
|
"type": "m.room_key_request"
|
||||||
|
}
|
||||||
@ -0,0 +1,59 @@
|
|||||||
|
---
|
||||||
|
allOf:
|
||||||
|
- $ref: core-event-schema/event.yaml
|
||||||
|
|
||||||
|
description: |-
|
||||||
|
This event type is used to forward keys for end-to-end encryption. Typically
|
||||||
|
it is encrypted as an ``m.room.encrypted`` event, then sent as a `to-device`_
|
||||||
|
event.
|
||||||
|
properties:
|
||||||
|
content:
|
||||||
|
properties:
|
||||||
|
algorithm:
|
||||||
|
type: string
|
||||||
|
description: |-
|
||||||
|
The encryption algorithm the key in this event is to be used with.
|
||||||
|
room_id:
|
||||||
|
type: string
|
||||||
|
description: The room where the key is used.
|
||||||
|
sender_key:
|
||||||
|
type: string
|
||||||
|
description: |-
|
||||||
|
The Curve25519 key of the device which initiated the session originally.
|
||||||
|
session_id:
|
||||||
|
type: string
|
||||||
|
description: The ID of the session that the key is for.
|
||||||
|
session_key:
|
||||||
|
type: string
|
||||||
|
description: The key to be exchanged.
|
||||||
|
sender_claimed_ed25519_key:
|
||||||
|
type: string
|
||||||
|
description: |-
|
||||||
|
The Ed25519 key of the device which initiated the session originally.
|
||||||
|
It is 'claimed' because the receiving device has no way to tell that the
|
||||||
|
original room_key actually came from a device which owns the private part of
|
||||||
|
this key unless they have done device verification.
|
||||||
|
forwarding_curve25519_key_chain:
|
||||||
|
type: array
|
||||||
|
items:
|
||||||
|
type: string
|
||||||
|
description: |-
|
||||||
|
Chain of Curve25519 keys. It starts out empty, but each time the
|
||||||
|
key is forwarded to another device, the previous sender in the chain is added
|
||||||
|
to the end of the list. For example, if the key is forwarded from A to B to
|
||||||
|
C, this field is empty between A and B, and contains A's Curve25519 key between
|
||||||
|
B and C.
|
||||||
|
required:
|
||||||
|
- algorithm
|
||||||
|
- room_id
|
||||||
|
- session_id
|
||||||
|
- session_key
|
||||||
|
- sender_claimed_ed25519_key
|
||||||
|
- forwarding_curve25519_key_chain
|
||||||
|
- sender_key
|
||||||
|
type: object
|
||||||
|
type:
|
||||||
|
enum:
|
||||||
|
- m.forwarded_room_key
|
||||||
|
type: string
|
||||||
|
type: object
|
||||||
@ -0,0 +1,88 @@
|
|||||||
|
---
|
||||||
|
title: Server ACL
|
||||||
|
description: |-
|
||||||
|
An event to indicate which servers are permitted to participate in the
|
||||||
|
room. Server ACLs may allow or deny groups of hosts. All servers participating
|
||||||
|
in the room, including those that are denied, are expected to uphold the
|
||||||
|
server ACL. Servers that do not uphold the ACLs MUST be added to the denied hosts
|
||||||
|
list in order for the ACLs to remain effective.
|
||||||
|
|
||||||
|
The ``allow`` and ``deny`` lists are lists of globs supporting ``?`` and ``*``
|
||||||
|
as wildcards. When comparing against the server ACLs, the suspect server's port
|
||||||
|
number must not be considered. Therefore ``evil.com``, ``evil.com:8448``, and
|
||||||
|
``evil.com:1234`` would all match rules that apply to ``evil.com``, for example.
|
||||||
|
|
||||||
|
The ACLs are applied to servers when they make requests, and are applied in
|
||||||
|
the following order:
|
||||||
|
|
||||||
|
1. If there is no ``m.room.server_acl`` event in the room state, allow.
|
||||||
|
#. If the server name is an IP address (v4 or v6) literal, and ``allow_ip_literals``
|
||||||
|
is present and ``false``, deny.
|
||||||
|
#. If the server name matches an entry in the ``deny`` list, deny.
|
||||||
|
#. If the server name matches an entry in the ``allow`` list, allow.
|
||||||
|
#. Otherwise, deny.
|
||||||
|
|
||||||
|
.. Note::
|
||||||
|
Server ACLs do not restrict the events relative to the room DAG via authorisation
|
||||||
|
rules, but instead act purely at the network layer to determine which servers are
|
||||||
|
allowed to connect and interact with a given room.
|
||||||
|
|
||||||
|
.. WARNING::
|
||||||
|
Failing to provide an ``allow`` rule of some kind will prevent **all**
|
||||||
|
servers from participating in the room, including the sender. This renders
|
||||||
|
the room unusable. A common allow rule is ``[ "*" ]`` which would still
|
||||||
|
permit the use of the ``deny`` list without losing the room.
|
||||||
|
|
||||||
|
.. WARNING::
|
||||||
|
All compliant servers must implement server ACLs. However, legacy or noncompliant
|
||||||
|
servers exist which do not uphold ACLs, and these MUST be manually appended to
|
||||||
|
the denied hosts list when setting an ACL to prevent them from leaking events from
|
||||||
|
banned servers into a room. Currently, the only way to determine noncompliant hosts is
|
||||||
|
to check the ``prev_events`` of leaked events, therefore detecting servers which
|
||||||
|
are not upholding the ACLs. Server versions can also be used to try to detect hosts that
|
||||||
|
will not uphold the ACLs, although this is not comprehensive. Server ACLs were added
|
||||||
|
in Synapse v0.32.0, although other server implementations and versions exist in the world.
|
||||||
|
allOf:
|
||||||
|
- $ref: core-event-schema/state_event.yaml
|
||||||
|
type: object
|
||||||
|
properties:
|
||||||
|
content:
|
||||||
|
properties:
|
||||||
|
allow_ip_literals:
|
||||||
|
type: boolean
|
||||||
|
description: |-
|
||||||
|
True to allow server names that are IP address literals. False to
|
||||||
|
deny. Defaults to true if missing or otherwise not a boolean.
|
||||||
|
|
||||||
|
This is strongly recommended to be set to ``false`` as servers running
|
||||||
|
with IP literal names are strongly discouraged in order to require
|
||||||
|
legitimate homeservers to be backed by a valid registered domain name.
|
||||||
|
allow:
|
||||||
|
type: array
|
||||||
|
description: |-
|
||||||
|
The server names to allow in the room, excluding any port information.
|
||||||
|
Wildcards may be used to cover a wider range of hosts, where ``*``
|
||||||
|
matches zero or more characters and ``?`` matches exactly one character.
|
||||||
|
|
||||||
|
**This defaults to an empty list when not provided, effectively disallowing
|
||||||
|
every server.**
|
||||||
|
items:
|
||||||
|
type: string
|
||||||
|
deny:
|
||||||
|
type: array
|
||||||
|
description: |-
|
||||||
|
The server names to disallow in the room, excluding any port information.
|
||||||
|
Wildcards may be used to cover a wider range of hosts, where ``*``
|
||||||
|
matches zero or more characters and ``?`` matches exactly one character.
|
||||||
|
|
||||||
|
This defaults to an empty list when not provided.
|
||||||
|
items:
|
||||||
|
type: string
|
||||||
|
type: object
|
||||||
|
state_key:
|
||||||
|
description: A zero-length string.
|
||||||
|
pattern: '^$'
|
||||||
|
type: string
|
||||||
|
type:
|
||||||
|
enum: ['m.room.server_acl']
|
||||||
|
type: string
|
||||||
@ -0,0 +1,61 @@
|
|||||||
|
---
|
||||||
|
allOf:
|
||||||
|
- $ref: core-event-schema/event.yaml
|
||||||
|
|
||||||
|
description: |-
|
||||||
|
This event type is used to request keys for end-to-end encryption. It is sent as an
|
||||||
|
unencrypted `to-device`_ event.
|
||||||
|
properties:
|
||||||
|
content:
|
||||||
|
properties:
|
||||||
|
body:
|
||||||
|
description: |-
|
||||||
|
Information about the requested key. Required when ``action`` is
|
||||||
|
``request``.
|
||||||
|
properties:
|
||||||
|
algorithm:
|
||||||
|
type: string
|
||||||
|
description: |-
|
||||||
|
The encryption algorithm the requested key in this event is to be used
|
||||||
|
with.
|
||||||
|
room_id:
|
||||||
|
type: string
|
||||||
|
description: The room where the key is used.
|
||||||
|
sender_key:
|
||||||
|
type: string
|
||||||
|
description: |-
|
||||||
|
The Curve25519 key of the device which initiated the session originally.
|
||||||
|
session_id:
|
||||||
|
type: string
|
||||||
|
description: The ID of the session that the key is for.
|
||||||
|
required:
|
||||||
|
- algorithm
|
||||||
|
- room_id
|
||||||
|
- session_id
|
||||||
|
- sender_key
|
||||||
|
type: object
|
||||||
|
title: RequestedKeyInfo
|
||||||
|
action:
|
||||||
|
enum:
|
||||||
|
- request
|
||||||
|
- cancel_request
|
||||||
|
type: string
|
||||||
|
requesting_device_id:
|
||||||
|
description: ID of the device requesting the key.
|
||||||
|
type: string
|
||||||
|
request_id:
|
||||||
|
description: |-
|
||||||
|
A random string uniquely identifying the request for a key. If the key is
|
||||||
|
requested multiple times, it should be reused. It should also reused in order
|
||||||
|
to cancel a request.
|
||||||
|
type: string
|
||||||
|
required:
|
||||||
|
- action
|
||||||
|
- requesting_device_id
|
||||||
|
- request_id
|
||||||
|
type: object
|
||||||
|
type:
|
||||||
|
enum:
|
||||||
|
- m.room_key_request
|
||||||
|
type: string
|
||||||
|
type: object
|
||||||
@ -0,0 +1,48 @@
|
|||||||
|
# How to release a specification
|
||||||
|
|
||||||
|
There are several specifications that belong to matrix, such as the client-server
|
||||||
|
specification, server-server specification, and identity server specification. Each
|
||||||
|
of these gets released independently of each other with their own version numbers.
|
||||||
|
|
||||||
|
Once a specification is ready for release, a branch should be created to track the
|
||||||
|
changes in and to hold potential future hotfixes. This should be the name of the
|
||||||
|
specification (as it appears in the directory structure of this project) followed
|
||||||
|
by "release-" and the release version. For example, if the Client-Server Specification
|
||||||
|
was getting an r0.4.0 release, the branch name would be `client_server/release-r0.4.0`.
|
||||||
|
|
||||||
|
*Note*: Historical releases prior to this process may or may not have an appropriate
|
||||||
|
release branch. Releases after this document came into place will have an appropriate
|
||||||
|
branch.
|
||||||
|
|
||||||
|
The remainder of the process is as follows:
|
||||||
|
1. Activate your Python 3 virtual environment.
|
||||||
|
1. Having checked out the new release branch, navigate your way over to `./changelogs`.
|
||||||
|
1. Follow the release instructions provided in the README.md located there.
|
||||||
|
1. Update the changelog section of the specification you're releasing to make a reference
|
||||||
|
to the new version.
|
||||||
|
1. Update any version/link references across all specifications.
|
||||||
|
1. Ensure the `targets.yml` file lists the version correctly.
|
||||||
|
1. Commit the changes and PR them to master.
|
||||||
|
1. Tag the release with the format `client_server/r0.4.0`.
|
||||||
|
1. Add the changes to the matrix-org/matrix.org repository (for historic tracking).
|
||||||
|
* This is done by making a PR to the `unstyled_docs/spec` folder for the version and
|
||||||
|
specification you're releasing.
|
||||||
|
* Don't forget to symlink the new release as `latest`.
|
||||||
|
1. Perform a release on GitHub to tag the release.
|
||||||
|
1. Yell from the mountaintop to the world about the new release.
|
||||||
|
|
||||||
|
### Creating a release for a brand-new specification
|
||||||
|
|
||||||
|
Some specifications may not have ever had a release, and therefore need a bit more work
|
||||||
|
to become ready.
|
||||||
|
|
||||||
|
1. Activate your Python 3 virtual environment.
|
||||||
|
1. Having checked out the new release branch, navigate your way over to `./changelogs`.
|
||||||
|
1. Follow the "new changelog" instructions provided in the README.md located there.
|
||||||
|
1. Open the specification RST file and make some changes:
|
||||||
|
* Using a released specification as a template, update the changelog section.
|
||||||
|
* Use the appropriate changelog variable in the RST.
|
||||||
|
1. Create/define the appropriate variables in `gendoc.py`.
|
||||||
|
1. Update `targets.yml`.
|
||||||
|
1. Update any version/link references across all specifications.
|
||||||
|
1. Follow the regular release process.
|
||||||
@ -0,0 +1,24 @@
|
|||||||
|
# Copyright 2018 New Vector Ltd
|
||||||
|
#
|
||||||
|
# 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
|
||||||
|
example: {
|
||||||
|
"example.com": {
|
||||||
|
"ed25519:0": "these86bytesofbase64signaturecoveressentialfieldsincludinghashessocancheckredactedpdus"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
additionalProperties:
|
||||||
|
type: object
|
||||||
|
title: Server Signatures
|
||||||
|
additionalProperties:
|
||||||
|
type: string
|
||||||
@ -0,0 +1,74 @@
|
|||||||
|
.. Copyright 2018 New Vector Ltd.
|
||||||
|
..
|
||||||
|
.. 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.
|
||||||
|
|
||||||
|
User, room, and group mentions
|
||||||
|
==============================
|
||||||
|
|
||||||
|
.. _module:mentions:
|
||||||
|
|
||||||
|
This module allows users to mention other users, rooms, and groups within
|
||||||
|
a room message. This is achieved by including a `matrix.to URI`_ in the HTML
|
||||||
|
body of an `m.room.message`_ event. This module does not have any server-specific
|
||||||
|
behaviour to it.
|
||||||
|
|
||||||
|
Mentions apply only to `m.room.message`_ events where the ``msgtype`` is ``m.text``,
|
||||||
|
``m.emote``, or ``m.notice``. The ``format`` for the event must be ``org.matrix.custom.html``
|
||||||
|
and therefore requires a ``formatted_body``.
|
||||||
|
|
||||||
|
To make a mention, reference the entity being mentioned in the ``formatted_body``
|
||||||
|
using an anchor, like so::
|
||||||
|
|
||||||
|
{
|
||||||
|
"body": "Hello Alice!",
|
||||||
|
"msgtype": "m.text",
|
||||||
|
"format": "org.matrix.custom.html",
|
||||||
|
"formatted_body": "Hello <a href='https://matrix.to/#/@alice:example.org'>Alice</a>!"
|
||||||
|
}
|
||||||
|
|
||||||
|
|
||||||
|
Client behaviour
|
||||||
|
----------------
|
||||||
|
|
||||||
|
In addition to using the appropriate ``matrix.to URI`` for the mention,
|
||||||
|
clients should use the following guidelines when making mentions in events
|
||||||
|
to be sent:
|
||||||
|
|
||||||
|
* When mentioning users, use the user's potentially ambigious display name for
|
||||||
|
the anchor's text. If the user does not have a display name, use the user's
|
||||||
|
ID.
|
||||||
|
|
||||||
|
* When mentioning rooms, use the canonical alias for the room. If the room
|
||||||
|
does not have a canonical alias, prefer one of the aliases listed on the
|
||||||
|
room. If no alias can be found, fall back to the room ID. In all cases,
|
||||||
|
use the alias/room ID being linked to as the anchor's text.
|
||||||
|
|
||||||
|
* When referencing groups, use the group ID as the anchor's text.
|
||||||
|
|
||||||
|
The text component of the anchor should be used in the event's ``body`` where
|
||||||
|
the mention would normally be represented, as shown in the example above.
|
||||||
|
|
||||||
|
Clients should display mentions differently from other elements. For example,
|
||||||
|
this may be done by changing the background color of the mention to indicate
|
||||||
|
that it is different from a normal link.
|
||||||
|
|
||||||
|
If the current user is mentioned in a message (either by a mention as defined
|
||||||
|
in this module or by a push rule), the client should show that mention differently
|
||||||
|
from other mentions, such as by using a red background color to signify to the
|
||||||
|
user that they were mentioned.
|
||||||
|
|
||||||
|
When clicked, the mention should navigate the user to the appropriate room, group,
|
||||||
|
or user information.
|
||||||
|
|
||||||
|
|
||||||
|
.. _`matrix.to URI`: ../appendices.html#matrix-to-navigation
|
||||||
@ -0,0 +1,70 @@
|
|||||||
|
.. Copyright 2018 New Vector Ltd
|
||||||
|
..
|
||||||
|
.. 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.
|
||||||
|
|
||||||
|
Server Access Control Lists (ACLs) for rooms
|
||||||
|
============================================
|
||||||
|
|
||||||
|
.. _module:server-acls:
|
||||||
|
|
||||||
|
In some scenarios room operators may wish to prevent a malicious or untrusted
|
||||||
|
server from participating in their room. Sending an `m.room.server_acl`_ state
|
||||||
|
event into a room is an effective way to prevent the server from participating
|
||||||
|
in the room at the federation level.
|
||||||
|
|
||||||
|
Server ACLs can also be used to make rooms only federate with a limited set of
|
||||||
|
servers, or retroactively make the room no longer federate with any other server,
|
||||||
|
similar to setting the ``m.federate`` value on the `m.room.create`_ event.
|
||||||
|
|
||||||
|
{{m_room_server_acl_event}}
|
||||||
|
|
||||||
|
.. Note::
|
||||||
|
Port numbers are not supported because it is unclear to parsers whether a
|
||||||
|
port number should be matched or an IP address literal. Additionally, it
|
||||||
|
is unlikely that one would trust a server running on a particular domain's
|
||||||
|
port but not a different port, especially considering the server host can
|
||||||
|
easily change ports.
|
||||||
|
|
||||||
|
.. Note::
|
||||||
|
CIDR notation is not supported for IP addresses because Matrix does not
|
||||||
|
encourage the use of IPs for identifying servers. Instead, a blanket
|
||||||
|
``allow_ip_literals`` is provided to cover banning them.
|
||||||
|
|
||||||
|
Client behaviour
|
||||||
|
----------------
|
||||||
|
Clients are not expected to perform any additional duties beyond sending the
|
||||||
|
event. Clients should describe changes to the server ACLs to the user in the
|
||||||
|
user interface, such as in the timeline.
|
||||||
|
|
||||||
|
Clients may wish to kick affected users from the room prior to denying a server
|
||||||
|
access to the room to help prevent those servers from participating and to
|
||||||
|
provide feedback to the users that they have been excluded from the room.
|
||||||
|
|
||||||
|
Server behaviour
|
||||||
|
----------------
|
||||||
|
Servers MUST prevent blacklisted servers from sending events or participating
|
||||||
|
in the room when an `m.room.server_acl`_ event is present in the room state.
|
||||||
|
Which APIs are specifically affected are described in the Server-Server API
|
||||||
|
specification.
|
||||||
|
|
||||||
|
Servers should still send events to denied servers if they are still residents
|
||||||
|
of the room.
|
||||||
|
|
||||||
|
|
||||||
|
Security considerations
|
||||||
|
-----------------------
|
||||||
|
Server ACLs are only effective if every server in the room honours them. Servers
|
||||||
|
that do not honour the ACLs may still permit events sent by denied servers into
|
||||||
|
the room, leaking them to other servers in the room. To effectively enforce an
|
||||||
|
ACL in a room, the servers that do not honour the ACLs should be denied in the
|
||||||
|
room as well.
|
||||||
Some files were not shown because too many files have changed in this diff Show More
Loading…
Reference in New Issue