Merge pull request #1773 from matrix-org/travis/spec/rooms
Add a room version specificationpull/977/head
Travis Ralston
6 years ago
committed by
GitHub
commit
6c7eea555a
@ -0,0 +1,98 @@
|
|||||||
|
.. Copyright 2017,2019 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.
|
||||||
|
|
||||||
|
Room Version 1
|
||||||
|
==============
|
||||||
|
|
||||||
|
This room version is the first ever version for rooms, and contains the building
|
||||||
|
blocks for other room versions.
|
||||||
|
|
||||||
|
Server implementation components
|
||||||
|
--------------------------------
|
||||||
|
|
||||||
|
.. WARNING::
|
||||||
|
The information contained in this section is strictly for server implementors.
|
||||||
|
Applications which use the Client-Server API are generally unaffected by the
|
||||||
|
details contained here, and can safely ignore their presence.
|
||||||
|
|
||||||
|
|
||||||
|
The algorithms defined here should only apply to version 1 rooms. Other algorithms
|
||||||
|
may be used by other room versions, and as such servers should be aware of which
|
||||||
|
version room they are dealing with prior to executing a given algorithm.
|
||||||
|
|
||||||
|
.. WARNING::
|
||||||
|
Although room version 1 is the most popular room version, it is known to have
|
||||||
|
undesirable effects. Servers implementing support for room version 1 should be
|
||||||
|
aware that restrictions should be generally relaxed and that inconsistencies
|
||||||
|
may occur until room version 2 (or later) is ready and adopted.
|
||||||
|
|
||||||
|
State resolution
|
||||||
|
~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
.. WARNING::
|
||||||
|
This section documents the state resolution algorithm as implemented by
|
||||||
|
Synapse as of December 2017 (and therefore the de-facto Matrix protocol).
|
||||||
|
However, this algorithm is known to have some problems.
|
||||||
|
|
||||||
|
The room state :math:`S'(E)` after an event :math:`E` is defined in terms of
|
||||||
|
the room state :math:`S(E)` before :math:`E`, and depends on whether
|
||||||
|
:math:`E` is a state event or a message event:
|
||||||
|
|
||||||
|
* If :math:`E` is a message event, then :math:`S'(E) = S(E)`.
|
||||||
|
|
||||||
|
* If :math:`E` is a state event, then :math:`S'(E)` is :math:`S(E)`, except
|
||||||
|
that its entry corresponding to :math:`E`'s ``event_type`` and ``state_key``
|
||||||
|
is replaced by :math:`E`'s ``event_id``.
|
||||||
|
|
||||||
|
The room state :math:`S(E)` before :math:`E` is the *resolution* of the set of
|
||||||
|
states :math:`\{ S'(E'), S'(E''), … \}` consisting of the states after each of
|
||||||
|
:math:`E`'s ``prev_event``\s :math:`\{ E', E'', … \}`.
|
||||||
|
|
||||||
|
The *resolution* of a set of states is defined as follows. The resolved state
|
||||||
|
is built up in a number of passes; here we use :math:`R` to refer to the
|
||||||
|
results of the resolution so far.
|
||||||
|
|
||||||
|
* Start by setting :math:`R` to the union of the states to be resolved,
|
||||||
|
excluding any *conflicting* events.
|
||||||
|
|
||||||
|
* First we resolve conflicts between ``m.room.power_levels`` events. If there
|
||||||
|
is no conflict, this step is skipped, otherwise:
|
||||||
|
|
||||||
|
* Assemble all the ``m.room.power_levels`` events from the states to
|
||||||
|
be resolved into a list.
|
||||||
|
|
||||||
|
* Sort the list by ascending ``depth`` then descending ``sha1(event_id)``.
|
||||||
|
|
||||||
|
* Add the first event in the list to :math:`R`.
|
||||||
|
|
||||||
|
* For each subsequent event in the list, check that the event would be
|
||||||
|
allowed by the `authorization rules`_ for a room in state :math:`R`. If the
|
||||||
|
event would be allowed, then update :math:`R` with the event and continue
|
||||||
|
with the next event in the list. If it would not be allowed, stop and
|
||||||
|
continue below with ``m.room.join_rules`` events.
|
||||||
|
|
||||||
|
* Repeat the above process for conflicts between ``m.room.join_rules`` events.
|
||||||
|
|
||||||
|
* Repeat the above process for conflicts between ``m.room.member`` events.
|
||||||
|
|
||||||
|
* No other events affect the authorization rules, so for all other conflicts,
|
||||||
|
just pick the event with the highest depth and lowest ``sha1(event_id)`` that
|
||||||
|
passes authentication in :math:`R` and add it to :math:`R`.
|
||||||
|
|
||||||
|
A *conflict* occurs between states where those states have different
|
||||||
|
``event_ids`` for the same ``(state_type, state_key)``. The events thus
|
||||||
|
affected are said to be *conflicting* events.
|
||||||
|
|
||||||
|
|
||||||
|
.. _`authorization rules`: ../server_server/unstable.html#authorization-rules
|
||||||
@ -0,0 +1,202 @@
|
|||||||
|
.. Copyright 2018-2019 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.
|
||||||
|
|
||||||
|
Room Version 2
|
||||||
|
==============
|
||||||
|
|
||||||
|
This room version builds off of `version 1 <v1.html>`_ with an improved state
|
||||||
|
resolution algorithm.
|
||||||
|
|
||||||
|
Server implementation components
|
||||||
|
--------------------------------
|
||||||
|
|
||||||
|
.. WARNING::
|
||||||
|
The information contained in this section is strictly for server implementors.
|
||||||
|
Applications which use the Client-Server API are generally unaffected by the
|
||||||
|
details contained here, and can safely ignore their presence.
|
||||||
|
|
||||||
|
|
||||||
|
The algorithms defined here should only apply to version 2 rooms. Other algorithms
|
||||||
|
may be used by other room versions, and as such servers should be aware of which
|
||||||
|
version room they are dealing with prior to executing a given algorithm.
|
||||||
|
|
||||||
|
|
||||||
|
State resolution
|
||||||
|
~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
The room state :math:`S'(E)` after an event :math:`E` is defined in terms of
|
||||||
|
the room state :math:`S(E)` before :math:`E`, and depends on whether
|
||||||
|
:math:`E` is a state event or a message event:
|
||||||
|
|
||||||
|
* If :math:`E` is a message event, then :math:`S'(E) = S(E)`.
|
||||||
|
|
||||||
|
* If :math:`E` is a state event, then :math:`S'(E)` is :math:`S(E)`, except
|
||||||
|
that its entry corresponding to :math:`E`'s ``event_type`` and ``state_key``
|
||||||
|
is replaced by :math:`E`'s ``event_id``.
|
||||||
|
|
||||||
|
The room state :math:`S(E)` before :math:`E` is the *resolution* of the set of
|
||||||
|
states :math:`\{ S'(E_1), S'(E_2), … \}` consisting of the states after each of
|
||||||
|
:math:`E`'s ``prev_event``\s :math:`\{ E_1, E_2, … \}`, where the resolution of
|
||||||
|
a set of states is given in the algorithm below.
|
||||||
|
|
||||||
|
Definitions
|
||||||
|
+++++++++++
|
||||||
|
|
||||||
|
The state resolution algorithm for version 2 rooms uses the following
|
||||||
|
definitions, given the set of room states :math:`\{ S_1, S_2, \ldots \}`:
|
||||||
|
|
||||||
|
Power events
|
||||||
|
A *power event* is a state event with type ``m.room.power_levels`` or
|
||||||
|
``m.room.join_rules``, or a state event with type ``m.room.member`` where the
|
||||||
|
``membership`` is ``leave`` or ``ban`` and the ``sender`` does not match the
|
||||||
|
``state_key``. The idea behind this is that power events are events that might
|
||||||
|
remove someone's ability to do something in the room.
|
||||||
|
|
||||||
|
Unconflicted state map and conflicted state set
|
||||||
|
The *unconflicted state map* is the state where the value of each key exists
|
||||||
|
and is the same in each state :math:`S_i`. The *conflicted state set* is the
|
||||||
|
set of all other state events. Note that the unconflicted state map only has
|
||||||
|
one event per ``(event_type, state_key)``, whereas the conflicted state set
|
||||||
|
may have multiple events.
|
||||||
|
|
||||||
|
Auth difference
|
||||||
|
The *auth difference* is calculated by first calculating the full auth chain
|
||||||
|
for each state :math:`S_i`, that is the union of the auth chains for each
|
||||||
|
event in :math:`S_i`, and then taking every event that doesn't appear in
|
||||||
|
every auth chain. If :math:`C_i` is the full auth chain of :math:`S_i`, then
|
||||||
|
the auth difference is :math:`\cup C_i - \cap C_i`.
|
||||||
|
|
||||||
|
Full conflicted set
|
||||||
|
The *full conflicted set* is the union of the conflicted state set and the
|
||||||
|
auth difference.
|
||||||
|
|
||||||
|
Reverse topological power ordering
|
||||||
|
The *reverse topological power ordering* of a set of events is the
|
||||||
|
lexicographically smallest topological ordering based on the DAG formed by
|
||||||
|
auth events. The reverse topological power ordering is ordered from earliest
|
||||||
|
event to latest. For comparing two topological orderings to determine which
|
||||||
|
is the lexicographically smallest, the following comparison relation on
|
||||||
|
events is used: for events :math:`x` and :math:`y`, :math:`x<y` if
|
||||||
|
|
||||||
|
1. :math:`x`'s sender has *greater* power level than :math:`y`'s sender,
|
||||||
|
when looking at their respective ``auth_event``\s; or
|
||||||
|
2. the senders have the same power level, but :math:`x`'s
|
||||||
|
``origin_server_ts`` is *less* than :math:`y`'s ``origin_server_ts``; or
|
||||||
|
3. the senders have the same power level and the events have the same
|
||||||
|
``origin_server_ts``, but :math:`x`'s ``event_id`` is *less* than
|
||||||
|
:math:`y`'s ``event_id``.
|
||||||
|
|
||||||
|
The reverse topological power ordering can be found by sorting the events
|
||||||
|
using Kahn's algorithm for topological sorting, and at each step selecting,
|
||||||
|
among all the candidate vertices, the smallest vertex using the above
|
||||||
|
comparison relation.
|
||||||
|
|
||||||
|
Mainline ordering
|
||||||
|
Given an ``m.room.power_levels`` event :math:`P`, the *mainline of* :math:`P`
|
||||||
|
is the list of events generated by starting with :math:`P` and recursively
|
||||||
|
taking the ``m.room.power_levels`` events from the ``auth_events``, ordered
|
||||||
|
such that :math:`P` is last. Given another event :math:`e`, the *closest
|
||||||
|
mainline event to* :math:`e` is the first event encountered in the mainline
|
||||||
|
when iteratively descending through the ``m.room.power_levels`` events in the
|
||||||
|
``auth_events`` starting at :math:`e`. If no mainline event is encountered
|
||||||
|
when iteratively descending through the ``m.room.power_levels`` events, then
|
||||||
|
the closest mainline event to :math:`e` can be considered to be a dummy event
|
||||||
|
that is before any other event in the mainline of :math:`P` for the purposes
|
||||||
|
of condition 1 below.
|
||||||
|
|
||||||
|
The *mainline ordering based on* :math:`P` of a set of events is the
|
||||||
|
ordering, from smallest to largest, using the following comparision relation
|
||||||
|
on events: for events :math:`x` and :math:`y`, :math:`x<y` if
|
||||||
|
|
||||||
|
1. the closest mainline event to :math:`x` appears *before* the closest
|
||||||
|
mainline event to :math:`y`; or
|
||||||
|
2. the closest mainline events are the same, but :math:`x`\'s
|
||||||
|
``origin_server_ts`` is *less* than :math:`y`\'s ``origin_server_ts``; or
|
||||||
|
3. the closest mainline events are the same and the events have the same
|
||||||
|
``origin_server_ts``, but :math:`x`\'s ``event_id`` is *less* than
|
||||||
|
:math:`y`\'s ``event_id``.
|
||||||
|
|
||||||
|
Iterative auth checks
|
||||||
|
The *iterative auth checks algorithm* takes as input an initial room state
|
||||||
|
and a sorted list of state events, and constructs a new room state by
|
||||||
|
iterating through the event list and applying the state event to the room
|
||||||
|
state if the state event is allowed by the `authorization rules`_. If the
|
||||||
|
state event is not allowed by the authorization rules, then the event is
|
||||||
|
ignored. If a ``(event_type, state_key)`` key that is required for checking
|
||||||
|
the authorization rules is not present in the state, then the appropriate
|
||||||
|
state event from the event's ``auth_events`` is used if the auth event is
|
||||||
|
not rejected.
|
||||||
|
|
||||||
|
Algorithm
|
||||||
|
+++++++++
|
||||||
|
|
||||||
|
The *resolution* of a set of states is obtained as follows:
|
||||||
|
|
||||||
|
1. Take all *power events* and any events in their auth chains, recursively,
|
||||||
|
that appear in the *full conflicted set* and order them by the *reverse
|
||||||
|
topological power ordering*.
|
||||||
|
2. Apply the *iterative auth checks algorithm* on the *unconflicted state map*
|
||||||
|
and the list of events from the previous step to get a partially resolved
|
||||||
|
state.
|
||||||
|
3. Take all remaining events that weren't picked in step 1 and order them by
|
||||||
|
the mainline ordering based on the power level in the partially resolved
|
||||||
|
state obtained in step 2.
|
||||||
|
4. Apply the *iterative auth checks algorithm* on the partial resolved
|
||||||
|
state and the list of events from the previous step.
|
||||||
|
5. Update the result by replacing any event with the event with the same key
|
||||||
|
from the *unconflicted state map*, if such an event exists, to get the final
|
||||||
|
resolved state.
|
||||||
|
|
||||||
|
|
||||||
|
.. _`authorization rules`: ../server_server/unstable.html#authorization-rules
|
||||||
|
|
||||||
|
Rejected events
|
||||||
|
+++++++++++++++
|
||||||
|
|
||||||
|
Events that have been rejected due to failing auth based on the state at the
|
||||||
|
event (rather than based on their auth chain) are handled as usual by the
|
||||||
|
algorithm, unless otherwise specified.
|
||||||
|
|
||||||
|
Note that no events rejected due to failure to auth against their auth chain
|
||||||
|
should appear in the process, as they should not appear in state (the algorithm
|
||||||
|
only uses events that appear in either the state sets or in the auth chain of
|
||||||
|
the events in the state sets).
|
||||||
|
|
||||||
|
.. admonition:: Rationale
|
||||||
|
|
||||||
|
This helps ensure that different servers' view of state is more likely to
|
||||||
|
converge, since rejection state of an event may be different. This can happen if
|
||||||
|
a third server gives an incorrect version of the state when a server joins a
|
||||||
|
room via it (either due to being faulty or malicious). Convergence of state is a
|
||||||
|
desirable property as it ensures that all users in the room have a (mostly)
|
||||||
|
consistent view of the state of the room. If the view of the state on different
|
||||||
|
servers diverges it can lead to bifurcation of the room due to e.g. servers
|
||||||
|
disagreeing on who is in the room.
|
||||||
|
|
||||||
|
Intuitively, using rejected events feels dangerous, however:
|
||||||
|
|
||||||
|
1. Servers cannot arbitrarily make up state, since they still need to pass the
|
||||||
|
auth checks based on the event's auth chain (e.g. they can't grant themselves
|
||||||
|
power levels if they didn't have them before).
|
||||||
|
2. For a previously rejected event to pass auth there must be a set of state
|
||||||
|
that allows said event. A malicious server could therefore produce a
|
||||||
|
fork where it claims the state is that particular set of state, duplicate the
|
||||||
|
rejected event to point to that fork, and send the event. The
|
||||||
|
duplicated event would then pass the auth checks. Ignoring rejected events
|
||||||
|
would therefore not eliminate any potential attack vectors.
|
||||||
|
|
||||||
|
|
||||||
|
Rejected auth events are deliberately excluded from use in the iterative auth
|
||||||
|
checks, as auth events aren't re-authed (although non-auth events are) during
|
||||||
|
the iterative auth checks.
|
||||||
Loading…
Reference in New Issue