wholetrans/docs-matrix-spec
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Merge remote-tracking branch 'origin/master' into cross-signing-spec

Browse source
This commit is contained in:
Hubert Chathi 2020-05-29 17:25:19 -04:00
commit ec0b9badc7
70 changed files with 1748 additions and 298 deletions
Download patch file Download diff file Expand all files Collapse all files

2
specification/appendices/identifier_grammar.rst
View file

@ -45,7 +45,7 @@ following grammar::
IPv6char = DIGIT / %x41-46 / %x61-66 / ":" / "."
; 0-9, A-F, a-f, :, .
dns-name = *255dns-char
dns-name = 1*255dns-char
dns-char = DIGIT / ALPHA / "-" / "."

11
specification/appendices/signing_json.rst
View file

@ -39,6 +39,17 @@ range where they can be accurately represented using IEEE double precision
floating point numbers since a number of JSON libraries represent all numbers
using this representation.
.. WARNING::
Events in room versions 1, 2, 3, 4, and 5 might not be fully compliant with
these restrictions. Servers SHOULD be capable of handling JSON which is considered
invalid by these restrictions where possible.
The most notable consideration is that integers might not be in the range
specified above.
.. Note::
Float values are not permitted by this encoding.
.. code:: python
import json

117
specification/client_server_api.rst
View file

@ -45,6 +45,7 @@ Other versions of this specification
The following other versions are also available, in reverse chronological order:
- `HEAD <https://matrix.org/docs/spec/client_server/unstable.html>`_: Includes all changes since the latest versioned release.
- `r0.6.1 <https://matrix.org/docs/spec/client_server/r0.6.1.html>`_
- `r0.6.0 <https://matrix.org/docs/spec/client_server/r0.6.0.html>`_
- `r0.5.0 <https://matrix.org/docs/spec/client_server/r0.5.0.html>`_
- `r0.4.0 <https://matrix.org/docs/spec/client_server/r0.4.0.html>`_
@ -123,6 +124,10 @@ The common error codes are:
:``M_UNKNOWN_TOKEN``:
The access token specified was not recognised.
An additional response parameter, ``soft_logout``, might be present on the response
for 401 HTTP status codes. See `the soft logout section <#soft-logout>`_ for more
information.
:``M_MISSING_TOKEN``:
No access token was specified for the request.
@ -404,6 +409,22 @@ should pass the ``device_id`` in the request body. If the client sets the
to that device. There is therefore at most one active access token assigned to
each device at any one time.
Soft logout
~~~~~~~~~~~
When a request fails due to a 401 status code per above, the server can
include an extra response parameter, ``soft_logout``, to indicate if the client's
persisted information can be retained. This defaults to ``false``, indicating
that the server has destroyed the session. Any persisted state held by the client,
such as encryption keys and device information, must not be reused and must be discarded.
When ``soft_logout`` is true, the client can acquire a new access token by
specifying the device ID it is already using to the login API. In most cases
a ``soft_logout: true`` response indicates that the user's session has expired
on the server-side and the user simply needs to provide their credentials again.
In either case, the client's previously known access token will no longer function.
User-Interactive Authentication API
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@ -643,6 +664,7 @@ This specification defines the following auth types:
- ``m.login.password``
- ``m.login.recaptcha``
- ``m.login.oauth2``
- ``m.login.sso``
- ``m.login.email.identity``
- ``m.login.msisdn``
- ``m.login.token``
@ -782,6 +804,38 @@ the auth code. Homeservers can choose any path for the ``redirect URI``. Once
the OAuth flow has completed, the client retries the request with the session
only, as above.
Single Sign-On
<<<<<<<<<<<<<<
:Type:
``m.login.sso``
:Description:
Authentication is supported by authorising with an external single sign-on
provider.
A client wanting to complete authentication using SSO should use the
`Fallback`_ authentication flow by opening a browser window for
``/_matrix/client/r0/auth/m.login.sso/fallback/web?session=<...>`` with the
session parameter set to the session ID provided by the server.
The homeserver should return a page which asks for the user's confirmation
before proceeding. For example, the page could say words to the effect of:
A client is trying to remove a device/add an email address/take over your
account. To confirm this action, re-authenticate with single sign-on. If you
did not expect this, your account may be compromised!
Once the user has confirmed they should be redirected to the single sign-on
provider's login page. Once the provider has validated the user, the browser is
redirected back to the homeserver.
The homeserver then validates the response from the single sign-on provider and
updates the user-interactive authentication session to mark the single sign-on
stage has been completed. The browser is shown the fallback authentication
completion page.
Once the flow has completed, the client retries the request with the session
only, as above.
Email-based (identity / homeserver)
<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
:Type:
@ -1561,8 +1615,6 @@ Room Events
This specification outlines several standard event types, all of which are
prefixed with ``m.``
{{m_room_aliases_event}}
{{m_room_canonical_alias_event}}
{{m_room_create_event}}
@ -1575,6 +1627,15 @@ prefixed with ``m.``
{{m_room_redaction_event}}
Historical events
+++++++++++++++++
Some events within the ``m.`` namespace might appear in rooms, however they
serve no significant meaning in this version of the specification. They are:
* ``m.room.aliases``
Previous versions of the specification have more information on these events.
Syncing
~~~~~~~
@ -1746,39 +1807,7 @@ redacted include a ``redacted_because`` key whose value is the event that caused
it to be redacted, which may include a reason.
Upon receipt of a redaction event, the server should strip off any keys not in
the following list:
- ``event_id``
- ``type``
- ``room_id``
- ``sender``
- ``state_key``
- ``content``
- ``hashes``
- ``signatures``
- ``depth``
- ``prev_events``
- ``prev_state``
- ``auth_events``
- ``origin``
- ``origin_server_ts``
- ``membership``
.. Note:
Some of the keys, such as ``hashes``, will appear on the federation-formatted
event and therefore the client may not be aware of them.
The content object should also be stripped of all keys, unless it is one of
one of the following event types:
- ``m.room.member`` allows key ``membership``.
- ``m.room.create`` allows key ``creator``.
- ``m.room.join_rules`` allows key ``join_rule``.
- ``m.room.power_levels`` allows keys ``ban``, ``events``, ``events_default``,
``kick``, ``redact``, ``state_default``, ``users``, ``users_default``.
- ``m.room.aliases`` allows key ``aliases``.
- ``m.room.history_visibility`` allows key ``history_visibility``.
The exact algorithm to apply against an event is defined in the `room version specification`_.
The server should add the event causing the redaction to the ``unsigned``
property of the redacted event, under the ``redacted_because`` key. When a
@ -1838,15 +1867,15 @@ send update requests to other servers. However, homeservers MUST handle
``GET`` requests to resolve aliases on other servers; they should do this using
the federation API if necessary.
Rooms store a *partial* list of room aliases via the ``m.room.aliases`` state
event. This alias list is partial because it cannot guarantee that the alias
list is in any way accurate or up-to-date, as room aliases can point to
different room IDs over time. Crucially, the aliases in this event are
**purely informational** and SHOULD NOT be treated as accurate. They SHOULD
be checked before they are used or shared with another user. If a room
appears to have a room alias of ``#alias:example.com``, this SHOULD be checked
to make sure that the room's ID matches the ``room_id`` returned from the
request.
Rooms do not store a list of all aliases present on a room, though members
of the room with relevant permissions may publish preferred aliases through
the ``m.room.canonical_alias`` state event. The aliases in the state event
should point to the room ID they are published within, however room aliases
can and do drift to other room IDs over time. Clients SHOULD NOT treat the
aliases as accurate. They SHOULD be checked before they are used or shared
with another user. If a room appears to have a room alias of ``#alias:example.com``,
this SHOULD be checked to make sure that the room's ID matches the ``room_id``
returned from the request.
{{directory_cs_http_api}}

1
specification/index.rst
View file

@ -550,6 +550,7 @@ The available room versions are:
* `Version 3 <rooms/v3.html>`_ - **Stable**. Introduces events whose IDs are the event's hash.
* `Version 4 <rooms/v4.html>`_ - **Stable**. Builds on v3 by using URL-safe base64 for event IDs.
* `Version 5 <rooms/v5.html>`_ - **Stable**. Introduces enforcement of signing key validity periods.
* `Version 6 <rooms/v6.html>`_ - **Stable**. Alters several authorization rules for events.
Specification Versions
----------------------

38
specification/modules/end_to_end_encryption.rst
View file

@ -83,9 +83,23 @@ Base64`_. Example:
"JGLn/yafz74HB2AbPLYJWIVGnKAtqECOBf11yyXac2Y"
The name ``signed_curve25519`` also corresponds to the Curve25519 algorithm,
but keys using this algorithm are objects with the properties ``key`` (giving
the Base64-encoded 32-byte Curve25519 public key), and ``signatures`` (giving a
signature for the key object, as described in `Signing JSON`_). Example:
but a key using this algorithm is represented by an object with a the following
properties:
``KeyObject``
========== ================ =====================================================
Parameter Type Description
========== ================ =====================================================
key string **Required.** The unpadded Base64-encoded 32-byte
Curve25519 public key.
signatures Signatures **Required.** Signatures of the key object.
The signature is calculated using the process described
at `Signing JSON`_.
========== ================ =====================================================
Example:
.. code:: json
@ -513,7 +527,7 @@ received the other party's part. Thus an attacker essentially only has one attem
attack the Diffie-Hellman exchange, and hence we can verify fewer bits while still
achieving a high degree of security: if we verify n bits, then an attacker has a 1 in
2\ :sup:`n` chance of success. For example, if we verify 40 bits, then an attacker has
a 1 in 1,099,511,627,776 chance (or less than 1 in 1012 chance) of success. A failed
a 1 in 1,099,511,627,776 chance (or less than 1 in 10\ :sup:`12` chance) of success. A failed
attack would result in a mismatched Short Authentication String, alerting users to the
attack.
@ -565,9 +579,9 @@ The process between Alice and Bob verifying each other would be:
they match or not.
#. Assuming they match, Alice and Bob's devices calculate the HMAC of their own device keys
and a comma-separated sorted list of of the key IDs that they wish the other user
to verify, using SHA-256 as the hash function. HMAC is defined in [RFC 2104](https://tools.ietf.org/html/rfc2104).
to verify, using SHA-256 as the hash function. HMAC is defined in `RFC 2104 <https://tools.ietf.org/html/rfc2104>`_.
The key for the HMAC is different for each item and is calculated by generating
32 bytes (256 bits) using `the key verification HKDF <#SAS-HKDF>`_.
32 bytes (256 bits) using `the key verification HKDF <#sas-hkdf>`_.
#. Alice's device sends Bob's device a ``m.key.verification.mac`` message containing the
MAC of Alice's device keys and the MAC of her key IDs to be verified. Bob's device does
the same for Bob's device keys and key IDs concurrently with Alice.
@ -653,14 +667,14 @@ are used in addition to those already specified:
{{m_key_verification_mac_event}}
.. _`SAS-HKDF`:
.. _sas-hkdf:
HKDF calculation
<<<<<<<<<<<<<<<<
In all of the SAS methods, HKDF is as defined in [RFC 5869](https://tools.ietf.org/html/rfc5869)
In all of the SAS methods, HKDF is as defined in `RFC 5869 <https://tools.ietf.org/html/rfc5869>`_
and uses the previously agreed-upon hash function for the hash function. The shared
secret is supplied as the input keying material. No salt is used, and the input
secret is supplied as the input keying material. No salt is used, and the info
parameter is the concatenation of:
* The string ``MATRIX_KEY_VERIFICATION_SAS``.
@ -677,7 +691,7 @@ parameter is the concatenation of:
For verification of each party's device keys, HKDF is as defined in RFC 5869 and
uses SHA-256 as the hash function. The shared secret is supplied as the input keying
material. No salt is used, and in the input parameter is the concatenation of:
material. No salt is used, and in the info parameter is the concatenation of:
* The string ``MATRIX_KEY_VERIFICATION_MAC``.
* The Matrix ID of the user whose key is being MAC-ed.
@ -691,7 +705,7 @@ material. No salt is used, and in the input parameter is the concatenation of:
SAS method: ``decimal``
<<<<<<<<<<<<<<<<<<<<<<<
Generate 5 bytes using `HKDF <#SAS-HKDF>`_ then take sequences of 13 bits to
Generate 5 bytes using `HKDF <#sas-hkdf>`_ then take sequences of 13 bits to
convert to decimal numbers (resulting in 3 numbers between 0 and 8191 inclusive
each). Add 1000 to each calculated number.
@ -708,7 +722,7 @@ such as dashes, or with the numbers on individual lines.
SAS method: ``emoji``
<<<<<<<<<<<<<<<<<<<<<
Generate 6 bytes using `HKDF <#SAS-HKDF>`_ then split the first 42 bits into
Generate 6 bytes using `HKDF <#sas-hkdf>`_ then split the first 42 bits into
7 groups of 6 bits, similar to how one would base64 encode something. Convert
each group of 6 bits to a number and use the following table to get the corresponding
emoji:

10
specification/modules/instant_messaging.rst
View file

@ -275,13 +275,9 @@ choose a name:
1. If the room has an `m.room.name`_ state event with a non-empty ``name``
field, use the name given by that field.
#. If the room has an `m.room.canonical_alias`_ state event with a non-empty
``alias`` field, use the alias given by that field as the name.
#. If neither of the above conditions are met, the client can optionally guess
an alias from the ``m.room.alias`` events in the room. This is a temporary
measure while clients do not promote canonical aliases as prominently. This
step may be removed in a future version of the specification.
#. If the room has an `m.room.canonical_alias`_ state event with a valid
``alias`` field, use the alias given by that field as the name. Note that
clients should avoid using ``alt_aliases`` when calculating the room name.
#. If none of the above conditions are met, a name should be composed based
on the members of the room. Clients should consider `m.room.member`_ events

4
specification/modules/read_markers.rst
View file

@ -47,7 +47,7 @@ The read markers API can additionally update the user's read receipt (``m.read``
location in the same operation as setting the fully read marker location. This is
because read receipts and read markers are commonly updated at the same time,
and therefore the client might wish to save an extra HTTP call. Providing an
``m.read`` location performs the same task as a request to ``/receipts/m.read/$event:example.org``.
``m.read`` location performs the same task as a request to ``/receipt/m.read/$event:example.org``.
{{read_markers_cs_http_api}}
@ -56,7 +56,7 @@ Server behaviour
The server MUST prevent clients from setting ``m.fully_read`` directly in
room account data. The server must additionally ensure that it treats the
presence of ``m.read`` in the ``/read_markers`` request the same as how it
would for a request to ``/receipts/m.read/$event:example.org``.
would for a request to ``/receipt/m.read/$event:example.org``.
Upon updating the ``m.fully_read`` event due to a request to ``/read_markers``,
the server MUST send the updated account data event through to the client via

2
specification/modules/tags.rst
View file

@ -55,7 +55,7 @@ The tag namespace is defined as follows:
display name directly). These non-namespaced tags are supported for historical reasons. New tags should use
one of the defined namespaces above.
Two special names are listed in the specification:
Several special names are listed in the specification:
The following tags are defined in the ``m.*`` namespace:
* ``m.favourite``: The user's favourite rooms. These should be shown with higher precedence than other rooms.

97
specification/proposals_intro.rst
View file

@ -230,7 +230,8 @@ follows:
comments and in relevant rooms on Matrix. Discussion outside of GitHub should
be summarised in a comment on the PR.
- When a member of the Spec Core Team believes that no new discussion points are
being made, they will propose a motion for a final comment period (FCP),
being made, and the proposal has suitable evidence of working (see `implementing a
proposal`_ below), they will propose a motion for a final comment period (FCP),
along with a *disposition* of either merge, close or postpone. This FCP is
provided to allow a short period of time for any invested party to provide a
final objection before a major decision is made. If sufficient reasoning is
@ -371,6 +372,100 @@ though that can always change as priorities evolve. We still encourage that MSCs
opened, even if not the focus for the time being, as they can still make progress and
even be merged without the Spec Core Team focusing on them specifically.
Implementing a proposal
-----------------------
As part of the proposal process the spec core team will require evidence of the MSC
working in order for it to move into FCP. This can usually be a branch/pull request
to whichever implementation of choice that proves the MSC works in practice, though
in some cases the MSC itself will be small enough to be considered proven. Where it's
unclear if a MSC will require an implementation proof, ask in `#matrix-spec:matrix.org
<https://matrix.to/#/#matrix-spec:matrix.org>`_.
Early release of a MSC/idea
~~~~~~~~~~~~~~~~~~~~~~~~~~~
To help facilitate early releases of software dependent on a spec release, implementations
are required to use the following process to ensure that the official Matrix namespace
is not cluttered with development or testing data.
.. Note::
Unreleased implementations (including proofs-of-concept demonstrating that a
particular MSC works) do not have to follow this process.
1. Have an idea for a feature.
2. Implement the feature using unstable endpoints, vendor prefixes, and unstable
feature flags as appropriate.
* When using unstable endpoints, they MUST include a vendor prefix. For example:
``/_matrix/client/unstable/com.example/login``. Vendor prefixes throughout Matrix
always use the Java package naming convention. The MSC for the feature should
identify which preferred vendor prefix is to be used by early adopters.
* Note that unstable namespaces do not automatically inherit endpoints from stable
namespaces: for example, the fact that ``/_matrix/client/r0/sync`` exists does
not imply that ``/_matrix/client/unstable/com.example/sync`` exists.
* If the client needs to be sure the server supports the feature, an unstable
feature flag that MUST be vendor prefixed is to be used. This kind of flag shows
up in the ``unstable_features`` section of ``/versions`` as, for example,
``com.example.new_login``. The MSC for the feature should identify which preferred
feature flag is to be used by early adopters.
* When using this approach correctly, the implementation can ship/release the
feature at any time, so long as the implementation is able to accept the technical
debt that results from needing to provide adequate backwards and forwards
compatibility. The implementation MUST support the flag (and server-side implementation) disappearing and be
generally safe for users. Note that implementations early in the MSC review
process may also be required to provide backwards compatibility with earlier
editions of the proposal.
* If the implementation cannot support the technical debt (or if it's impossible
to provide forwards/backwards compatibility - e.g. a user authentication change
which can't be safely rolled back), the implementation should not attempt to
implement the feature and should instead wait for a spec release.
* If at any point after early release, the idea changes in a backwards-incompatible way, the feature flag should also change so that
implementations can adapt as needed.
3. In parallel, or ahead of implementation, open an MSC and solicit review per above.
4. Before FCP can be called, the Spec Core Team will require evidence of the MSC
working as proposed. A typical example of this is an implementation of the MSC,
though the implementation does not need to be shipped anywhere and can therefore
avoid the forwards/backwards compatibility concerns mentioned here.
5. The FCP process is completed, and assuming nothing is flagged the MSC lands.
6. A spec PR is written to incorporate the changes into Matrix.
7. A spec release happens.
8. Implementations switch to using stable prefixes (e.g.: ``/r0``) if the server
supports the specification version released. If the server doesn't advertise the
specification version, but does have the feature flag, unstable prefixes should
still be used.
9. A transition period of about 2 months starts immediately after the spec release,
before implementations start to encourage other implementations to switch
to stable endpoints. For example, a server implementation should start asking
client implementations to support the stable endpoints 2 months after the spec
release, if they haven't already. The same applies in the reverse: if clients
cannot switch to stable prefixes because server implementations haven't started
supporting the new spec release, some noise should be raised in the general direction
of the implementation.
.. Note::
MSCs MUST still describe what the stable endpoints/feature looks like with a note
towards the bottom for what the unstable feature flag/prefixes are. For example,
a MSC would propose `/_matrix/client/r0/new/endpoint`, not `/_matrix/client/unstable/
com.example/new/endpoint`.
In summary:
* Implementations MUST NOT use stable endpoints before the MSC is in the spec. This
includes NOT using stable endpoints in the period between completion of FCP and release of the spec.
passed.
* Implementations are able to ship features that are exposed to users by default before
an MSC has been merged to the spec, provided they follow the process above.
* Implementations SHOULD be wary of the technical debt they are incurring by moving faster
than the spec.
* The vendor prefix is chosen by the developer of the feature, using the Java package
naming convention. The foundation's preferred vendor prefix is `org.matrix`.
* The vendor prefixes, unstable feature flags, and unstable endpoints should be included
in the MSC, though the MSC MUST be written in a way that proposes new stable endpoints.
Typically this is solved by a small table at the bottom mapping the various values
from stable to unstable.
Proposal Tracking
-----------------

65
specification/rooms/v1.rst
View file

@ -1,4 +1,5 @@
.. Copyright 2017,2019 New Vector Ltd
.. Copyright 2020 The Matrix.org Foundation C.I.C.
..
.. Licensed under the Apache License, Version 2.0 (the "License");
.. you may not use this file except in compliance with the License.
@ -21,13 +22,57 @@ blocks for other room versions.
.. contents:: Table of Contents
.. sectnum::
Client considerations
---------------------
Clients may need to consider some algorithms performed by the server for their own
implementation.
Redactions
~~~~~~~~~~
Upon receipt of a redaction event, the server must strip off any keys not in
the following list:
- ``event_id``
- ``type``
- ``room_id``
- ``sender``
- ``state_key``
- ``content``
- ``hashes``
- ``signatures``
- ``depth``
- ``prev_events``
- ``prev_state``
- ``auth_events``
- ``origin``
- ``origin_server_ts``
- ``membership``
.. Note:
Some of the keys, such as ``hashes``, will appear on the federation-formatted
event and therefore the client may not be aware of them.
The content object must also be stripped of all keys, unless it is one of
one of the following event types:
- ``m.room.member`` allows key ``membership``.
- ``m.room.create`` allows key ``creator``.
- ``m.room.join_rules`` allows key ``join_rule``.
- ``m.room.power_levels`` allows keys ``ban``, ``events``, ``events_default``,
``kick``, ``redact``, ``state_default``, ``users``, ``users_default``.
- ``m.room.aliases`` allows key ``aliases``.
- ``m.room.history_visibility`` allows key ``history_visibility``.
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.
intricacies contained here. The section above regarding client considerations
is the resource that Client-Server API use cases should reference.
The algorithms defined here should only apply to version 1 rooms. Other algorithms
@ -112,7 +157,7 @@ The types of state events that affect authorization are:
.. NOTE::
Power levels are inferred from defaults when not explicitly supplied.
For example, mentions of the ``sender``'s power level can also refer
For example, mentions of the ``sender``'s power level can also refer
to the default power level for users in the room.
The rules are as follows:
@ -250,7 +295,7 @@ The rules are as follows:
#. If there is no previous ``m.room.power_levels`` event in the room, allow.
#. For the keys ``users_default``, ``events_default``,
``state_default``, ``ban``, ``redact``, ``kick``, ``invite`` check if they
``state_default``, ``ban``, ``redact``, ``kick``, ``invite`` check if they
were added, changed or removed. For each found alteration:
i. If the current value is higher than the ``sender``'s current power level,
@ -258,13 +303,13 @@ The rules are as follows:
#. If the new value is higher than the ``sender``'s current power level,
reject.
#. For each entry being added, changed or removed in both the ``events`` and
#. For each entry being added, changed or removed in both the ``events`` and
``users`` keys:
i. If the current value is higher than the ``sender``'s current power level,
reject.
#. If the new value is higher than the ``sender``'s current power level,
reject.
@ -307,6 +352,12 @@ Events in version 1 rooms have the following structure:
{{definition_ss_pdu}}
Canonical JSON
~~~~~~~~~~~~~~
Servers MUST NOT strictly enforce the JSON format specified in the
`appendices <../appendices.html#canonical-json>`_ for the reasons described there.
.. _`auth events selection`: ../server_server/%SERVER_RELEASE_LABEL%.html#auth-events-selection
.. _`Signing Events`: ../server_server/%SERVER_RELEASE_LABEL%.html#signing-events

100
specification/rooms/v6.rst Normal file
View file

@ -0,0 +1,100 @@
.. Copyright 2020 The Matrix.org Foundation C.I.C.
..
.. 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 6
==============
This room version builds on `version 5 <v5.html>`_ while changing various
authorization rules performed on events.
.. contents:: Table of Contents
.. sectnum::
Client considerations
---------------------
The redaction algorithm has changed from `room version 1 <v1.html>`_ to remove
all rules against events of type ``m.room.aliases``. Room versions 2, 3, 4, and
5 all use v1's redaction algorithm. The algorithm is otherwise unchanged.
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
intricacies contained here. The section above regarding client considerations
is the resource that Client-Server API use cases should reference.
Room version 6 makes the following alterations to algorithms described in `room version 5 <v5.html>`_.
Redactions
~~~~~~~~~~
As mentioned in the client considerations portion of this specification, all
special meaning has been removed for events of type ``m.room.aliases``. The
algorithm is otherwise unchanged.
Authorization rules for events
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Like redactions, all rules relating specifically to events of type ``m.room.aliases``
are removed. They must still pass authorization checks relating to state events.
Additionally, the authorization rules for events of type ``m.room.power_levels``
now include the content key ``notifications``. This new rule takes the place of the
rule which checks the ``events`` and ``users`` keys.
For completeness, the changes to the auth rules can be represented as follows:
.. code:: diff
...
-If type is `m.room.aliases`:
-
- a. If event has no `state_key`, reject.
- b. If sender's domain doesn't matches `state_key`, reject.
- c. Otherwise, allow.
...
If type is `m.room.power_levels`:
...
- * For each entry being added, changed or removed in both the `events` and `users` keys:
+ * For each entry being added, changed or removed in the `events`, `users`, and `notifications` keys:
i. If the current value is higher than the `sender`'s current power level, reject.
ii. If the new value is higher than the `sender`'s current power level, reject.
...
The remaining rules are the same as in `room version 3 <v3.html#authorization-rules-for-events>`_
(the last inherited room version to specify the authorization rules).
Canonical JSON
~~~~~~~~~~~~~~
Servers MUST strictly enforce the JSON format specified in the
`appendices <../appendices.html#canonical-json>`_. This translates to a 400 ``M_BAD_JSON`` error
on most endpoints, or discarding of events over federation. For example, the Federation API's
``/send`` endpoint would discard the event whereas the Client Server API's ``/send/{eventType}``
endpoint would return a ``M_BAD_JSON`` error.

19
specification/server_server_api.rst
View file

@ -80,6 +80,8 @@ Other versions of this specification
The following other versions are also available, in reverse chronological order:
- `HEAD <https://matrix.org/docs/spec/server_server/unstable.html>`_: Includes all changes since the latest versioned release.
- `r0.1.4 <https://matrix.org/docs/spec/server_server/r0.1.4.html>`_
- `r0.1.3 <https://matrix.org/docs/spec/server_server/r0.1.3.html>`_
- `r0.1.2 <https://matrix.org/docs/spec/server_server/r0.1.2.html>`_
- `r0.1.1 <https://matrix.org/docs/spec/server_server/r0.1.1.html>`_
- `r0.1.0 <https://matrix.org/docs/spec/server_server/r0.1.0.html>`_
@ -291,6 +293,11 @@ Step 1 sign JSON:
}
}
The server names in the JSON above are the server names for each homeserver involved. Delegation from
the `server name resolution section <#resolving-server-names>`_ above do not affect
these - the server names from before delegation would take place are used. This
same condition applies throughout the request signing process.
Step 2 add Authorization header:
.. code::
@ -780,7 +787,9 @@ and responds to the joining server with the full set of state for the
newly-joined room. The resident server must also send the event to other servers
participating in the room.
{{joins_ss_http_api}}
{{joins_v1_ss_http_api}}
{{joins_v2_ss_http_api}}
.. TODO-spec
- (paul) I don't really understand why the full auth_chain events are given
@ -817,7 +826,9 @@ signs the event and replaces the ``event_id`` with it's own. This is then sent t
the resident server via ``/send_leave``. The resident server will then send the
event to other servers in the room.
{{leaving_ss_http_api}}
{{leaving_v1_ss_http_api}}
{{leaving_v2_ss_http_api}}
Third-party invites
-------------------
@ -1073,8 +1084,11 @@ The following endpoint prefixes MUST be protected:
* ``/_matrix/federation/v1/make_join``
* ``/_matrix/federation/v1/make_leave``
* ``/_matrix/federation/v1/send_join``
* ``/_matrix/federation/v2/send_join``
* ``/_matrix/federation/v1/send_leave``
* ``/_matrix/federation/v2/send_leave``
* ``/_matrix/federation/v1/invite``
* ``/_matrix/federation/v2/invite``
* ``/_matrix/federation/v1/state``
* ``/_matrix/federation/v1/state_ids``
* ``/_matrix/federation/v1/backfill``
@ -1252,3 +1266,4 @@ issue.
.. _`Device Management module`: ../client_server/%CLIENT_RELEASE_LABEL%.html#device-management
.. _`End-to-End Encryption module`: ../client_server/%CLIENT_RELEASE_LABEL%.html#end-to-end-encryption
.. _`room version specification`: ../index.html#room-versions
.. _`Client-Server Key Algorithms`: ../client_server/%CLIENT_RELEASE_LABEL%.html#key-algorithms

4
specification/targets.yaml
View file

@ -45,6 +45,10 @@ targets:
files:
- rooms/v5.rst
version_label: v5
rooms@v6: # this is translated to be rooms/v6.html
files:
- rooms/v6.rst
version_label: v6
appendices:
files:
- appendices.rst