Add specification for room version 3: Event IDs as hashes
Original proposal: https://github.com/matrix-org/matrix-doc/pull/1659 Implementation proofs (some traversing of the PR tree may be required to get all of them): * https://github.com/matrix-org/synapse/pull/4483 * https://github.com/matrix-org/synapse/pull/4499 This doesn't intentionally change anything from the proposal. **Implementation details**: The simple part of this is the introduction of a rooms/v3.html document. The somewhat unclear part is the stuff done to the s2s definitions. This pulls `unsigned_pdu` out to `unsigned_pdu_base` (all fields except `event_id`) where it can be reused in `pdu` and `pdu_v3` (for rooms v3). These definitions are further moved into the room version specifications where they can highlight the exact schemas in detail. Version 1 has been updated to include the pre-existing event format, however the core principles of the room have not been changed. The same applies to room version 2. Room versions have immutable core principles once in the spec, otherwise these format changes would land in a pre-existing version. The client-server API event formats will need updating, however that is being punted to a different commit to try and keep these changes reviewable.pull/1828/head
Travis Ralston
5 years ago
parent
4437c383bb
commit
ff75996524
@ -0,0 +1,73 @@
|
||||
# Copyright 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.
|
||||
type: object
|
||||
title: Persistent Data Unit
|
||||
description: A persistent data unit (event) for room version 3.
|
||||
example:
|
||||
$ref: "../examples/pdu_v3.json"
|
||||
allOf:
|
||||
- $ref: "unsigned_pdu_base.yaml"
|
||||
- type: object
|
||||
properties:
|
||||
auth_events:
|
||||
type: array
|
||||
items:
|
||||
type: string
|
||||
description: Event ID.
|
||||
description: |-
|
||||
Event IDs and reference hashes for the authorization events that would
|
||||
allow this event to be in the room.
|
||||
example: ["$abase64encodedhash", "$anotherevent"]
|
||||
prev_events:
|
||||
type: array
|
||||
items:
|
||||
type: string
|
||||
description: Event ID.
|
||||
description: |-
|
||||
Event IDs and reference hashes for the most recent events in the room
|
||||
that the homeserver was aware of when it made this event.
|
||||
example: ["$abase64encodedhash", "$anotherevent"]
|
||||
hashes:
|
||||
type: object
|
||||
title: Event Hash
|
||||
description: |-
|
||||
Content hashes of the PDU, following the algorithm specified in `Signing Events`_.
|
||||
example: {
|
||||
"sha256": "thishashcoversallfieldsincasethisisredacted"
|
||||
}
|
||||
properties:
|
||||
sha256:
|
||||
type: string
|
||||
description: The hash.
|
||||
example: thishashcoversallfieldsincasthisisredacted
|
||||
required: ['sha256']
|
||||
signatures:
|
||||
type: object
|
||||
description: |-
|
||||
Signatures for the PDU, following the algorithm specified in `Signing Events`_.
|
||||
example: {
|
||||
"example.com": {
|
||||
"ed25519:key_version:": "these86bytesofbase64signaturecoveressentialfieldsincludinghashessocancheckredactedpdus"
|
||||
}
|
||||
}
|
||||
additionalProperties:
|
||||
type: object
|
||||
title: Server Signatures
|
||||
additionalProperties:
|
||||
type: string
|
||||
required:
|
||||
- auth_events
|
||||
- prev_events
|
||||
- hashes
|
||||
- signatures
|
||||
@ -0,0 +1,151 @@
|
||||
# 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.
|
||||
type: object
|
||||
title: Unsigned Persistent Data Unit
|
||||
description: An unsigned persistent data unit (event)
|
||||
example:
|
||||
$ref: "../examples/unsigned_pdu_base.json"
|
||||
properties:
|
||||
room_id:
|
||||
type: string
|
||||
description: Room identifier.
|
||||
example: "!abc123:matrix.org"
|
||||
sender:
|
||||
type: string
|
||||
description: The ID of the user sending the event.
|
||||
example: "@someone:matrix.org"
|
||||
origin:
|
||||
type: string
|
||||
description: The ``server_name`` of the homeserver that created this event.
|
||||
example: "matrix.org"
|
||||
origin_server_ts:
|
||||
type: integer
|
||||
format: int64
|
||||
description: Timestamp in milliseconds on origin homeserver when this event was created.
|
||||
example: 1234567890
|
||||
type:
|
||||
type: string
|
||||
description: Event type
|
||||
example: "m.room.message"
|
||||
state_key:
|
||||
type: string
|
||||
description: |-
|
||||
If this key is present, the event is a state event, and it will replace previous events
|
||||
with the same ``type`` and ``state_key`` in the room state.
|
||||
example: "my_key"
|
||||
content:
|
||||
type: object
|
||||
description: The content of the event.
|
||||
example: {"key": "value"}
|
||||
prev_events:
|
||||
type: array
|
||||
description: |-
|
||||
Event IDs and reference hashes for the most recent events in the room
|
||||
that the homeserver was aware of when it made this event.
|
||||
items:
|
||||
type: array
|
||||
maxItems: 2
|
||||
minItems: 2
|
||||
items:
|
||||
- type: string
|
||||
title: Event ID
|
||||
example: "$abc123:matrix.org"
|
||||
- type: object
|
||||
title: Event Hash
|
||||
example: {
|
||||
"sha256": "abase64encodedsha256hashshouldbe43byteslong"
|
||||
}
|
||||
properties:
|
||||
sha256:
|
||||
type: string
|
||||
description: The event hash.
|
||||
example: abase64encodedsha256hashshouldbe43byteslong
|
||||
required: ['sha256']
|
||||
depth:
|
||||
type: integer
|
||||
description: |-
|
||||
The maximum depth of the ``prev_events``, plus one. Must be less than the
|
||||
maximum value for an integer (2^63 - 1). If the room's depth is already at
|
||||
the limit, the depth must be set to the limit.
|
||||
example: 12
|
||||
auth_events:
|
||||
type: array
|
||||
description: |-
|
||||
Event IDs and reference hashes for the authorization events that would
|
||||
allow this event to be in the room.
|
||||
items:
|
||||
type: array
|
||||
maxItems: 2
|
||||
minItems: 2
|
||||
items:
|
||||
- type: string
|
||||
title: Event ID
|
||||
example: "$abc123:matrix.org"
|
||||
- type: object
|
||||
title: Event Hash
|
||||
example: {
|
||||
"sha256": "abase64encodedsha256hashshouldbe43byteslong"
|
||||
}
|
||||
properties:
|
||||
sha256:
|
||||
type: string
|
||||
description: The event hash.
|
||||
example: abase64encodedsha256hashshouldbe43byteslong
|
||||
required: ['sha256']
|
||||
redacts:
|
||||
type: string
|
||||
description: For redaction events, the ID of the event being redacted.
|
||||
example: "$def456:matrix.org"
|
||||
unsigned:
|
||||
type: object
|
||||
title: Example Unsigned Data
|
||||
description: |-
|
||||
Additional data added by the origin server but not covered by the ``signatures``. More
|
||||
keys than those defined here may be used.
|
||||
example: {"key": "value"}
|
||||
properties:
|
||||
age:
|
||||
type: integer
|
||||
description: The number of milliseconds that have passed since this message was sent.
|
||||
example: 4612
|
||||
replaces_state:
|
||||
type: string
|
||||
description: The event ID of the state event this event replaces.
|
||||
example: "$state_event:example.org"
|
||||
prev_sender:
|
||||
type: string
|
||||
description: The sender of the replaced state event.
|
||||
example: "@someone:example.org"
|
||||
prev_content:
|
||||
type: object
|
||||
description: The content of the replaced state event.
|
||||
example: {
|
||||
"membership": "join",
|
||||
"displayname": "Bob"
|
||||
}
|
||||
redacted_because:
|
||||
type: string
|
||||
description: A reason for why the event was redacted.
|
||||
example: "Inappropriate content"
|
||||
required:
|
||||
- event_id
|
||||
- room_id
|
||||
- sender
|
||||
- origin
|
||||
- origin_server_ts
|
||||
- type
|
||||
- content
|
||||
- prev_events
|
||||
- depth
|
||||
- auth_events
|
||||
@ -0,0 +1,19 @@
|
||||
{
|
||||
"$ref": "unsigned_pdu_base.json",
|
||||
"hashes": {
|
||||
"sha256": "thishashcoversallfieldsincasethisisredacted"
|
||||
},
|
||||
"signatures": {
|
||||
"example.com": {
|
||||
"ed25519:key_version:": "these86bytesofbase64signaturecoveressentialfieldsincludinghashessocancheckredactedpdus"
|
||||
}
|
||||
},
|
||||
"auth_events": [
|
||||
"$base64encodedeventid",
|
||||
"$adifferenteventid"
|
||||
],
|
||||
"prev_events": [
|
||||
"$base64encodedeventid",
|
||||
"$adifferenteventid"
|
||||
]
|
||||
}
|
||||
@ -1,27 +1,4 @@
|
||||
{
|
||||
"room_id": "!UcYsUzyxTGDxLBEvLy:example.org",
|
||||
"sender": "@alice:example.com",
|
||||
"origin": "example.com",
|
||||
"event_id": "$a4ecee13e2accdadf56c1025:example.com",
|
||||
"origin_server_ts": 1404838188000,
|
||||
"depth": 12,
|
||||
"auth_events": [
|
||||
[
|
||||
"$af232176:example.org",
|
||||
{"sha256": "abase64encodedsha256hashshouldbe43byteslong"}
|
||||
]
|
||||
],
|
||||
"type": "m.room.message",
|
||||
"prev_events": [
|
||||
[
|
||||
"$af232176:example.org",
|
||||
{"sha256": "abase64encodedsha256hashshouldbe43byteslong"}
|
||||
]
|
||||
],
|
||||
"content": {
|
||||
"key": "value"
|
||||
},
|
||||
"unsigned": {
|
||||
"age": 4612
|
||||
}
|
||||
}
|
||||
"$ref": "unsigned_pdu_base.json",
|
||||
"event_id": "$a4ecee13e2accdadf56c1025:example.com"
|
||||
}
|
||||
|
||||
@ -0,0 +1,26 @@
|
||||
{
|
||||
"room_id": "!UcYsUzyxTGDxLBEvLy:example.org",
|
||||
"sender": "@alice:example.com",
|
||||
"origin": "example.com",
|
||||
"origin_server_ts": 1404838188000,
|
||||
"depth": 12,
|
||||
"auth_events": [
|
||||
[
|
||||
"$af232176:example.org",
|
||||
{"sha256": "abase64encodedsha256hashshouldbe43byteslong"}
|
||||
]
|
||||
],
|
||||
"type": "m.room.message",
|
||||
"prev_events": [
|
||||
[
|
||||
"$af232176:example.org",
|
||||
{"sha256": "abase64encodedsha256hashshouldbe43byteslong"}
|
||||
]
|
||||
],
|
||||
"content": {
|
||||
"key": "value"
|
||||
},
|
||||
"unsigned": {
|
||||
"age": 4612
|
||||
}
|
||||
}
|
||||
@ -0,0 +1,122 @@
|
||||
.. 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 3
|
||||
==============
|
||||
|
||||
This room version builds off of `version 2 <v2.html>`_ with an improved event format.
|
||||
|
||||
.. note:
|
||||
All requirements listed in this room version specification are scoped to rooms
|
||||
which actually use this room version. For example, a requirement of "all APIs must
|
||||
accept the new event format" does in fact apply to all APIs, but only so much as
|
||||
where the contextual room of the request is using this room version. Rooms using
|
||||
other room versions should not be affected by these sweeping requirements.
|
||||
|
||||
|
||||
Client considerations
|
||||
---------------------
|
||||
|
||||
This room version changes the format for event IDs sent to clients. Clients should be
|
||||
aware that these event IDs may contain slashes and other potentially problematic
|
||||
characters. Clients should be treating event IDs as opaque identifiers and should not
|
||||
be attempting to parse them into a usable form, just like with other room versions.
|
||||
|
||||
Clients should expect to see event IDs changed from the format of ``$randomstring:example.org``
|
||||
to something like ``$acR1l0raoZnm60CBwAVgqbZqoO/mYU81xysh1u7XcJk`` (note the lack of
|
||||
domain and the potentially problematic slash).
|
||||
|
||||
|
||||
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 3 uses the state resolution algorithm defined in `room version 2 <v2.html>`_,
|
||||
and the event format defined here. Other event formats and applicable algorithms
|
||||
may be used in other room versions.
|
||||
|
||||
Event IDs
|
||||
~~~~~~~~~
|
||||
|
||||
In other room versions (namely version 1 and 2) the event ID is a distinct field
|
||||
from the remainder of the event, which must be tracked as such. This leads to
|
||||
complications where servers receive multiple events with the same ID in either the
|
||||
same or different rooms where the server cannot easily keep track of which event it
|
||||
should be using. By removing the use of a dedicated event ID, servers are required
|
||||
to track the hashes on an event to determine its ID.
|
||||
|
||||
The event ID must be a sha256 hash of the event, encoded using `Unpadded Base64`_
|
||||
and prefixed with `$`. For example, an event ID might be
|
||||
``$CD66HAED5npg6074c6pDtLKalHjVfYb2q4Q3LZgrW6o``.
|
||||
|
||||
The hash itself is calculated the same as previous reference hashes are:
|
||||
|
||||
1. Redact the event.
|
||||
2. Remove the `signatures` field from the event.
|
||||
3. Serialize the event into `Canonical JSON`_.
|
||||
4. Compute the hash of the JSON bytes.
|
||||
|
||||
Event IDs should not be sent over federation to servers when the room uses
|
||||
this room version. On the receiving end of an event, the server should compute
|
||||
the relevant event ID for itself.
|
||||
|
||||
Additionally, the ``auth_events`` and ``prev_events`` have had a format change
|
||||
compared to other room versions to make it easier to handle. Instead of a tuple
|
||||
of values, they are now plain lists of events.
|
||||
|
||||
{{definition_ss_pdu_v3}}
|
||||
|
||||
Changes to APIs
|
||||
~~~~~~~~~~~~~~~
|
||||
|
||||
Due to the event ID being removed from the event, some APIs need to change. All
|
||||
APIs which currently accept an event ID must do so with the new format. Servers
|
||||
must append the calculated event ID to all events sent to clients where an event
|
||||
ID would normally be expected.
|
||||
|
||||
Because servers are not communicating the event ID over the wire to each other,
|
||||
servers must be aware of the room version where the event resides so that the
|
||||
server may parse and handle the event. The federation API has taken this concern
|
||||
into consideration by ensuring that servers are aware of (or can find) the room
|
||||
version during a request.
|
||||
|
||||
Authorization rules for events
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The authorization rules for a given event have changed in this room version due
|
||||
to the change in event format:
|
||||
|
||||
* The event no longer needs to be signed by the domain of the event ID (as there
|
||||
is no domain in the event ID), but still needs to be signed by the sender's
|
||||
domain.
|
||||
|
||||
* Previously, redactions were allowed if the sender's domain matched the domain
|
||||
in the event ID it was redacting, allowing self redaction. This check is removed
|
||||
and redaction events are always accepted. Redaction events only take effect
|
||||
when the original event is received, and the domain of the each event matches.
|
||||
Servers should not send redactions down to clients until the redaction has
|
||||
taken effect.
|
||||
|
||||
The remaining rules are the same as room version 1.
|
||||
|
||||
|
||||
.. _`Unpadded Base64`: ../../appendices.html#unpadded-base64
|
||||
.. _`Canonical JSON`: ../../appendices.html#canonical-json
|
||||
.. _`Signing Events`: ../../server_server/unstable.html#signing-events
|
||||
Loading…
Reference in New Issue