Server Access Control Lists (ACLs) for rooms

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`

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:

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.

Event type:	State event
State key	A zero-length string.

Content

Name Type Description

Name	Type	Description
`allow`	`[string]`	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.*
`allow_ip_literals`	`boolean`	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.
`deny`	`[string]`	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.

allow

[string]

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.

allow_ip_literals

boolean

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.

deny

[string]

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.

Examples

{
  "content": {
    "allow": [
      "*"
    ],
    "allow_ip_literals": false,
    "deny": [
      "*.evil.com",
      "evil.com"
    ]
  },
  "event_id": "$143273582443PhrSn:example.org",
  "origin_server_ts": 1432735824653,
  "room_id": "!jEsUZKDJdhlrceRyVU:example.org",
  "sender": "@example:example.org",
  "state_key": "",
  "type": "m.room.server_acl",
  "unsigned": {
    "age": 1234
  }
}

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.

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.