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