Server ACLs
Implements the proposal for https://github.com/matrix-org/matrix-doc/issues/1383pull/977/head
Travis Ralston
6 years ago
parent
6172d5986a
commit
ef41b5c2bf
@ -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,69 @@
|
|||||||
|
---
|
||||||
|
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 are recommended to be
|
||||||
|
added to the denied hosts list.
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
.. 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.
|
||||||
|
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.
|
||||||
|
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 one or more characters.
|
||||||
|
|
||||||
|
**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 one or more characters.
|
||||||
|
|
||||||
|
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: enum
|
||||||
@ -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.
|
||||||
|
|
||||||
|
Server Access Control Lists (ACLs) for rooms
|
||||||
|
============================================
|
||||||
|
|
||||||
|
.. _module:server-acls:
|
||||||
|
|
||||||
|
In some scenarios room operators may wish to prevent a malicous 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.
|
||||||
|
|
||||||
|
.. 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.
|
||||||
|
|
||||||
|
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.
|
||||||
Loading…
Reference in New Issue