Server ACLs

Implements the proposal for https://github.com/matrix-org/matrix-doc/issues/1383
pull/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.

@ -929,6 +929,32 @@ described in the `Client-Server API`_, being sure to use the ``allow_remote``
parameter (set to ``false``).
Server Access Control Lists (ACLs)
----------------------------------
Server ACLs and their purpose are described in the `Server ACLs`_ section of the
Client-Server API.
When a remote server makes a request, it MUST be verified to be allowed by the
server ACLs. If the server is denied access to a room, the receiving server
MUST reply with a 403 HTTP status code and an ``errcode`` of ``M_FORBIDDEN``.
The following endpoint prefixes MUST be protected:
* ``/_matrix/federation/v1/send`` (on a per-PDU basis)
* ``/_matrix/federation/v1/make_join``
* ``/_matrix/federation/v1/make_leave``
* ``/_matrix/federation/v1/send_join``
* ``/_matrix/federation/v1/send_leave``
* ``/_matrix/federation/v1/invite``
* ``/_matrix/federation/v1/state``
* ``/_matrix/federation/v1/state_ids``
* ``/_matrix/federation/v1/backfill``
* ``/_matrix/federation/v1/event_auth``
* ``/_matrix/federation/v1/query_auth``
* ``/_matrix/federation/v1/get_missing_events``
Signing Events
--------------

@ -67,6 +67,7 @@ groups: # reusable blobs of files when prefixed with 'group:'
- modules/report_content.rst
- modules/third_party_networks.rst
- modules/openid.rst
- modules/server_acls.rst
title_styles: ["=", "-", "~", "+", "^", "`", "@", ":"]

Loading…
Cancel
Save