diff --git a/assets-hugo/scss/custom.scss b/assets-hugo/scss/custom.scss index 13676acb..70efdfcf 100644 --- a/assets-hugo/scss/custom.scss +++ b/assets-hugo/scss/custom.scss @@ -209,6 +209,39 @@ footer { } +/* Styles for alert boxes */ +.alert { + &.note { + &:not(.omit-title):before { + content: "INFO: "; + font-weight: $font-weight-bold; + } + border: 2px solid $note; + border-left-width: 5px; + background: $note-background; + } + + &.rationale { + &:not(.omit-title):before { + content: "RATIONALE: "; + font-weight: $font-weight-bold; + } + border: 2px solid $note; + border-left-width: 5px; + background: $note-background; + } + + &.warning { + &:not(.omit-title):before { + content: "WARNING: "; + font-weight: $font-weight-bold; + } + border: 2px solid $warning; + border-left-width: 5px; + background: $warning-background; + } +} + /* Miscellaneous custom bits */ /* Update link colours for MAtrix style */ diff --git a/content/_index.md b/content/_index.md index 66c4709b..c6214c61 100644 --- a/content/_index.md +++ b/content/_index.md @@ -35,13 +35,13 @@ browsing the Client-Server API. ### Matrix versions -Note - +{{% boxes/note %}} As of June 10th 2019, the Matrix specification is considered out of beta -indicating that all currently released APIs are considered stable and secure to the best of our knowledge, and the spec should contain the complete information necessary to develop production-grade implementations of Matrix without the need for external reference. +{{% /boxes/note %}} Matrix 1.0 (released June 10th, 2019) consists of the following minimum API versions: @@ -335,13 +335,13 @@ participating servers in a room, currently using full mesh topology. Servers may also request backfill of events over federation from the other servers participating in a room. -Note - +{{% boxes/note %}} Events are not limited to the types defined in this specification. New or custom event types can be created on a whim using the Java package naming convention. For example, a `com.example.game.score` event can be sent by clients and other clients would receive it through Matrix, assuming the client has access to the `com.example` namespace. +{{% /boxes/note %}} #### Room Aliases diff --git a/content/appendices.md b/content/appendices.md index 17155583..7ab2618b 100644 --- a/content/appendices.md +++ b/content/appendices.md @@ -74,18 +74,18 @@ to be in the 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 - +{{% boxes/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. +{{% /boxes/warning %}} -Note - +{{% boxes/note %}} Float values are not permitted by this encoding. +{{% /boxes/note %}} ```py import json @@ -415,12 +415,12 @@ Examples of valid server names are: - `[1234:5678::abcd]` (IPv6 literal) - `[1234:5678::abcd]:5678` (IPv6 literal with explicit port) -Note - +{{% boxes/note %}} This grammar is based on the standard for internet host names, as specified by [RFC1123, section 2.1](https://tools.ietf.org/html/rfc1123#page-13), with an extension for IPv6 literals. +{{% /boxes/note %}} Server names must be treated case-sensitively: in other words, `@user:matrix.org` is a different person from `@user:MATRIX.ORG`. @@ -490,8 +490,7 @@ The complete grammar for a legal user ID is: / %x61-7A ; a-z / "-" / "." / "=" / "_" / "/" -Rationale - +{{% boxes/rationale %}} A number of factors were considered when defining the allowable characters for a user ID. @@ -525,6 +524,7 @@ The length restriction is derived from the limit on the length of the `sender` key on events; since the user ID appears in every event sent by the user, it is limited to ensure that the user ID does not dominate over the actual content of the events. +{{% /boxes/rationale %}} Matrix user IDs are sometimes informally referred to as MXIDs. @@ -564,12 +564,12 @@ consistently. However, we suggest the following algorithm: well as `=`, as their hexadecimal value, prefixed with `=`. For example, `#` becomes `=23`; `á` becomes `=c3=a1`. -Rationale - +{{% boxes/rationale %}} The suggested mapping is an attempt to preserve human-readability of simple ASCII identifiers (unlike, for example, base-32), whilst still allowing representation of *any* character (unlike punycode, which provides no way to encode ASCII punctuation). +{{% /boxes/rationale %}} #### Room IDs and Event IDs @@ -631,11 +631,11 @@ domain). #### matrix.to navigation -Note - +{{% boxes/note %}} This namespacing is in place pending a `matrix://` (or similar) URI scheme. This is **not** meant to be interpreted as an available web service - see below for more details. +{{% /boxes/note %}} Rooms, users, aliases, and groups may be represented as a "matrix.to" URI. This URI can be used to reference particular objects in a given @@ -676,19 +676,19 @@ Examples of matrix.to URIs are: - User: `https://matrix.to/#/%40alice%3Aexample.org` - Group: `https://matrix.to/#/%2Bexample%3Aexample.org` -Note - +{{% boxes/note %}} Historically, clients have not produced URIs which are fully encoded. Clients should try to interpret these cases to the best of their ability. For example, an unencoded room alias should still work within the client if possible. +{{% /boxes/note %}} -Note - +{{% boxes/note %}} Clients should be aware that decoding a matrix.to URI may result in extra slashes appearing due to some [room versions](index.html#room-versions). These slashes should normally be encoded when producing matrix.to URIs, however. +{{% /boxes/note %}} ##### Routing diff --git a/content/application-service-api.md b/content/application-service-api.md index 089d8884..582abf81 100644 --- a/content/application-service-api.md +++ b/content/application-service-api.md @@ -48,8 +48,7 @@ service. ### Registration -Note - +{{% boxes/note %}} Previously, application services could register with a homeserver via HTTP APIs. This was removed as it was seen as a security risk. A compromised application service could re-register for a global `*` regex @@ -58,6 +57,7 @@ application services now have to register via configuration files which are linked to the homeserver configuration file. The addition of configuration files allows homeserver admins to sanity check the registration for suspicious regex strings. +{{% /boxes/note %}} Application services register "namespaces" of user IDs, room aliases and room IDs. These namespaces are represented as regular expressions. An @@ -213,12 +213,12 @@ below: regex: "#_irc_bridge_.*" rooms: [] -Warning - +{{% boxes/warning %}} If the homeserver in question has multiple application services, each `as_token` and `id` MUST be unique per application service as these are used to identify the application service. The homeserver MUST enforce this. +{{% /boxes/warning %}} ### Homeserver -> Application Service API @@ -314,8 +314,7 @@ homeserver should retry several times before timing out. This should result in an HTTP status 408 "Request Timeout" on the client which initiated this request (e.g. to join a room alias). -Rationale - +{{% boxes/rationale %}} Blocking the homeserver and expecting the application service to create the entity using the client-server API is simpler and more flexible than alternative methods such as returning an initial sync style JSON blob @@ -323,6 +322,7 @@ and get the HS to provision the room/user. This also meant that there didn't need to be a "backchannel" to inform the application service about information about the entity such as room ID to room alias mappings. +{{% /boxes/rationale %}} {{query\_user\_as\_http\_api}} diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index be244c97..ee349c95 100644 --- a/content/client-server-api/_index.md +++ b/content/client-server-api/_index.md @@ -62,11 +62,11 @@ convention of using underscores to separate words (for example `/delete_devices`). The key names in JSON objects passed over the API also follow this convention. -Note - +{{% boxes/note %}} There are a few historical exceptions to this rule, such as `/createRoom`. A future version of this specification will address the inconsistency. +{{% /boxes/note %}} Any errors which occur at the Matrix API level MUST return a "standard error response". This is a JSON object which looks like: @@ -296,10 +296,10 @@ conscientious decision what to do next. ### Well-known URI -Note - +{{% boxes/note %}} Servers hosting the `.well-known` JSON file SHOULD offer CORS headers, as per the [CORS](#CORS) section in this specification. +{{% /boxes/note %}} The `.well-known` method uses a JSON file at a predetermined location to specify parameter values. The flow for this method is as follows: @@ -344,12 +344,12 @@ parameter or through an Authorization Header of `Bearer $access_token`. An access token is typically obtained via the [Login](#login) or [Registration](#Registration) processes. -Note - +{{% boxes/note %}} This specification does not mandate a particular format for the access token. Clients should treat it as an opaque byte sequence. Servers are free to choose an appropriate format. Server implementors may like to investigate [macaroons](http://research.google.com/pubs/pub41892.html). +{{% /boxes/note %}} ### Using access tokens @@ -1096,12 +1096,12 @@ the login endpoint during the login process. For example: ##### Notes on password management -Warning - +{{% boxes/warning %}} Clients SHOULD enforce that the password provided is suitably complex. The password SHOULD include a lower-case letter, an upper-case letter, a number and a symbol and be at a minimum 8 characters in length. Servers MAY reject weak passwords with an error code `M_WEAK_PASSWORD`. +{{% /boxes/warning %}} ### Adding Account Administrative Contact Information @@ -1109,13 +1109,13 @@ A homeserver may keep some contact information for administrative use. This is independent of any information kept by any identity servers, though can be proxied (bound) to the identity server in many cases. -Note - +{{% boxes/note %}} This section deals with two terms: "add" and "bind". Where "add" (or "remove") is used, it is speaking about an identifier that was not bound to an identity server. As a result, "bind" (or "unbind") references an identifier that is found in an identity server. Note that an identifier can be added and bound at the same time, depending on context. +{{% /boxes/note %}} {{administrative\_contact\_cs\_http\_api}} @@ -1261,10 +1261,10 @@ default and only stable `available` room version. ## Pagination -Note - +{{% boxes/note %}} The paths referred to in this section are not actual endpoints. They only serve as examples to explain how pagination functions. +{{% /boxes/note %}} Pagination is the process of dividing a dataset into multiple discrete pages. Matrix makes use of pagination to allow clients to view extremely @@ -1415,8 +1415,7 @@ any given point in time: [E0]->[E1]->[E2]->[E3]->[E4]->[E5] -Warning - +{{% boxes/warning %}} The format of events can change depending on room version. Check the [room version specification](../index.html#room-versions) for specific details on what to expect for event formats. Examples contained within @@ -1428,6 +1427,7 @@ the event ID format being different depending on room version. Clients should not be parsing the event ID, and instead be treating it as an opaque string. No changes should be required to support the currently available room versions. +{{% /boxes/warning %}} ### Types of room events @@ -1453,13 +1453,13 @@ follow the Java package naming convention, e.g. `com.example.myapp.event`. This ensures event types are suitably namespaced for each application and reduces the risk of clashes. -Note - +{{% boxes/note %}} Events are not limited to the types defined in this specification. New or custom event types can be created on a whim using the Java package naming convention. For example, a `com.example.game.score` event can be sent by clients and other clients would receive it through Matrix, assuming the client has access to the `com.example` namespace. +{{% /boxes/note %}} Note that the structure of these events may be different than those in the server-server API. @@ -1522,9 +1522,9 @@ than that implied by the total 65 KB limit on events. ### Room Events -Note - +{{% boxes/note %}} This section is a work in progress. +{{% /boxes/note %}} This specification outlines several standard event types, all of which are prefixed with `m.` @@ -1607,17 +1607,16 @@ of the message timeline. The client can fill these gaps using the prev_batch: 'd-e-f' next_batch: 'u-v-w' ``` -Warning - +{{% boxes/warning %}} Events are ordered in this API according to the arrival time of the event on the homeserver. This can conflict with other APIs which order events based on their partial ordering in the event graph. This can result in duplicate events being received (once per distinct API called). Clients SHOULD de-duplicate events based on the event ID when this happens. +{{% /boxes/warning %}} -Note - +{{% boxes/note %}} The `/sync` API returns a `state` list which is separate from the `timeline`. This `state` list allows clients to keep their model of the room state in sync with that on the server. In the case of an initial @@ -1635,9 +1634,9 @@ In both cases, it should be noted that the events returned in the `state` list did **not** necessarily take place just before the returned `timeline`, so clients should not display them to the user in the timeline. +{{% /boxes/note %}} -Rationale - +{{% boxes/rationale %}} An early design of this specification made the `state` list represent the room state at the end of the returned timeline, instead of the start. This was unsatisfactory because it led to duplication of events @@ -1650,6 +1649,7 @@ where that user changes their displayname. If the `state` list represents the room state at the end of the timeline, the client must take a copy of the state dictionary, and *rewind* S1, in order to correctly calculate the display name for M0. +{{% /boxes/rationale %}} {{sync\_cs\_http\_api}} @@ -1739,8 +1739,7 @@ property of the redacted event, under the `redacted_because` key. When a client receives a redaction event it should change the redacted event in the same way a server does. -Note - +{{% boxes/note %}} Redacted events can still affect the state of the room. When redacted, state events behave as though their properties were simply not specified, except those protected by the redaction algorithm. For @@ -1748,6 +1747,7 @@ example, a redacted `join` event will still result in the user being considered joined. Similarly, a redacted topic does not necessarily cause the topic to revert to what it was prior to the event - it causes the topic to be removed from the room. +{{% /boxes/note %}} ##### Events @@ -1804,9 +1804,9 @@ request. ### Permissions -Note - +{{% boxes/note %}} This section is a work in progress. +{{% /boxes/note %}} Permissions for rooms are done via the concept of power levels - to do any action in a room a user must have a suitable power level. Power diff --git a/content/client-server-api/modules/end_to_end_encryption.md b/content/client-server-api/modules/end_to_end_encryption.md index 089a6748..bb867a36 100644 --- a/content/client-server-api/modules/end_to_end_encryption.md +++ b/content/client-server-api/modules/end_to_end_encryption.md @@ -194,8 +194,7 @@ process: those already flagged as outdated, and initiates a `/keys/query`\_ request for all of them. -Warning - +{{% boxes/warning %}} Bob may update one of his devices while Alice has a request to `/keys/query` in flight. Alice's client may therefore see Bob's user ID in the `device_lists` field of the `/sync` response while the first @@ -218,9 +217,9 @@ each user, by queuing additional requests until the first completes. Alternatively, the client could make a new request immediately, but ensure that the first request's results are ignored (possibly by cancelling the request). +{{% /boxes/warning %}} -Note - +{{% boxes/note %}} When Bob and Alice share a room, with Bob tracking Alice's devices, she may leave the room and then add a new device. Bob will not be notified of this change, as he doesn't share a room anymore with Alice. When they @@ -231,6 +230,7 @@ thus Bob will update his list of Alice's devices as part of his normal processing. Note that Bob can also be notified when he stops sharing any room with Alice by inspecting the `left` property of the `device_lists` field, and as a result should remove her from its list of tracked users. +{{% /boxes/note %}} ##### Sending encrypted attachments @@ -243,12 +243,12 @@ AES key, and encrypt the file using AES-CTR. The counter should be Initialization Vector (IV), which together form a 128-bit unique counter block. -Warning - +{{% boxes/warning %}} An IV must never be used multiple times with the same key. This implies that if there are multiple files to encrypt in the same message, typically an image and its thumbnail, the files must not share both the same key and IV. +{{% /boxes/warning %}} Then, the encrypted file can be uploaded to the homeserver. The key and the IV must be included in the room event along with the resulting @@ -392,13 +392,13 @@ Device verification may reach one of several conclusions. For example: reason to suspect otherwise. The encryption protocol continues to protect against passive eavesdroppers. -Note - +{{% boxes/note %}} Once the signing key has been verified, it is then up to the encryption protocol to verify that a given message was sent from a device holding that Ed25519 private key, or to encrypt a message so that it may only be decrypted by such a device. For the Olm protocol, this is documented at . +{{% /boxes/note %}} ##### Key verification framework @@ -700,10 +700,10 @@ the info parameter is the concatenation of: New implementations are discouraged from implementing the `curve25519` method. -Rationale - +{{% boxes/rationale %}} HKDF is used over the plain shared secret as it results in a harder attack as well as more uniform data to work with. +{{% /boxes/rationale %}} 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 @@ -746,13 +746,12 @@ following table to get the corresponding emoji: {{sas\_emoji\_table}} -Note - +{{% boxes/note %}} This table is available as JSON at +{{% /boxes/note %}} -Rationale - +{{% boxes/rationale %}} The emoji above were chosen to: - Be recognisable without colour. @@ -762,17 +761,18 @@ The emoji above were chosen to: - Easily described by a few words. - Avoid symbols with negative connotations. - Be likely similar across multiple platforms. +{{% /boxes/rationale %}} Clients SHOULD show the emoji with the descriptions from the table, or appropriate translation of those descriptions. Client authors SHOULD collaborate to create a common set of translations for all languages. -Note - +{{% boxes/note %}} Known translations for the emoji are available from and can be translated online: +{{% /boxes/note %}} ##### Cross-signing @@ -950,11 +950,11 @@ indicate this by sending an [m.room\_key.withheld]() to-device message, as described in [Reporting that decryption keys are withheld](#reporting-that-decryption-keys-are-withheld). -Note - +{{% boxes/note %}} Key sharing can be a big attack vector, thus it must be done very carefully. A reasonable strategy is for a user's client to only send keys requested by the verified devices of the same user. +{{% /boxes/note %}} ##### Server-side key backups @@ -1388,13 +1388,13 @@ of reasons. When this happens to an Olm-encrypted message, the client should assume that the Olm session has become corrupted and create a new one to replace it. -Note - +{{% boxes/note %}} Megolm-encrypted messages generally do not have the same problem. Usually the key for an undecryptable Megolm-encrypted message will come later, allowing the client to decrypt it successfully. Olm does not have a way to recover from the failure, making this session replacement process required. +{{% /boxes/note %}} To establish a new session, the client sends an [m.dummy](#m-dummy) to-device event to the other party to notify them of the new session @@ -1555,14 +1555,14 @@ difference with the `one_time_key_counts` property in the -Note - +{{% boxes/note %}} For optimal performance, Alice should be added to `changed` in Bob's sync only when she updates her devices or cross-signing keys, or when Alice and Bob now share a room but didn't share any room previously. However, for the sake of simpler logic, a server may add Alice to `changed` when Alice and Bob share a new room, even if they previously already shared a room. +{{% /boxes/note %}} Example response: diff --git a/content/client-server-api/modules/history_visibility.md b/content/client-server-api/modules/history_visibility.md index 322114fc..8eba3643 100644 --- a/content/client-server-api/modules/history_visibility.md +++ b/content/client-server-api/modules/history_visibility.md @@ -33,13 +33,13 @@ The four options for the `m.room.history_visibility` event are: point they joined the room onwards. Events stop being accessible when the member's state changes to something other than `join`. -Warning - +{{% boxes/warning %}} These options are applied at the point an event is *sent*. Checks are performed with the state of the `m.room.history_visibility` event when the event in question is added to the DAG. This means clients cannot retrospectively choose to show or hide history to new users if the setting at that time was more restrictive. +{{% /boxes/warning %}} #### Events diff --git a/content/client-server-api/modules/instant_messaging.md b/content/client-server-api/modules/instant_messaging.md index 41b8e427..386ee34c 100644 --- a/content/client-server-api/modules/instant_messaging.md +++ b/content/client-server-api/modules/instant_messaging.md @@ -110,11 +110,11 @@ treated similar to a `div`. Clients that support rich replies will end up stripping the tag and its contents and therefore may wish to exclude the tag entirely. -Note - +{{% boxes/note %}} A future iteration of the specification will support more powerful and extensible message formatting options, such as the proposal [MSC1767](https://github.com/matrix-org/matrix-doc/pull/1767). +{{% /boxes/note %}} {{msgtype\_events}} diff --git a/content/client-server-api/modules/server_acls.md b/content/client-server-api/modules/server_acls.md index 00d9a085..5243756f 100644 --- a/content/client-server-api/modules/server_acls.md +++ b/content/client-server-api/modules/server_acls.md @@ -18,19 +18,19 @@ any other server, similar to setting the `m.federate` value on the {{m\_room\_server\_acl\_event}} -Note - +{{% boxes/note %}} 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. +{{% /boxes/note %}} -Note - +{{% boxes/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. +{{% /boxes/note %}} #### Client behaviour diff --git a/content/client-server-api/modules/sso_login.md b/content/client-server-api/modules/sso_login.md index 7137aaa7..ae5ac22d 100644 --- a/content/client-server-api/modules/sso_login.md +++ b/content/client-server-api/modules/sso_login.md @@ -85,8 +85,7 @@ These steps are illustrated as follows: |<-------------access token-------------| | ``` -Note - +{{% boxes/note %}} In the older [r0.4.0 version](https://matrix.org/docs/spec/client_server/r0.4.0.html#cas-based-client-login) of this specification it was possible to authenticate via CAS when the @@ -96,6 +95,7 @@ which is the same process with the only change being which redirect endpoint to use: for `m.login.cas`, use `/cas/redirect` and for `m.login.sso` use `/sso/redirect` (described below). The endpoints are otherwise the same. +{{% /boxes/note %}} ##### Client behaviour diff --git a/content/identity-service-api.md b/content/identity-service-api.md index 4439a65e..18f8bbc2 100644 --- a/content/identity-service-api.md +++ b/content/identity-service-api.md @@ -254,10 +254,10 @@ characteristics than the service's long-term keys. ### Client behaviour -Note - +{{% boxes/note %}} This section only covers the v2 lookup endpoint. The v1 endpoint is described in isolation above. +{{% /boxes/note %}} Prior to performing a lookup clients SHOULD make a request to the `/hash_details` endpoint to determine what algorithms the server @@ -269,10 +269,10 @@ Clients MUST support at least the `sha256` algorithm. ### Server behaviour -Note - +{{% boxes/note %}} This section only covers the v2 lookup endpoint. The v1 endpoint is described in isolation above. +{{% /boxes/note %}} Servers, upon receipt of a `/lookup` request, will compare the query against known bindings it has, hashing the identifiers it knows about as @@ -299,11 +299,11 @@ the 3PID to search for. For example, if the client wanted to know about `alice@example.org`'s bindings, it would first format the query as `alice@example.org email ThePepperGoesHere`. -Rationale - +{{% boxes/rationale %}} Mediums and peppers are appended to the address to prevent a common prefix for each 3PID, helping prevent attackers from pre-computing the internal state of the hash function. +{{% /boxes/rationale %}} After formatting each query, the string is run through SHA-256 as defined by [RFC 4634](https://tools.ietf.org/html/rfc4634). The @@ -342,12 +342,12 @@ the client has made an appropriate request to `/hash_details` first. ### Security considerations -Note - +{{% boxes/note %}} [MSC2134](https://github.com/matrix-org/matrix-doc/pull/2134) has much more information about the security considerations made for this section of the specification. This section covers the high-level details for why the specification is the way it is. +{{% /boxes/note %}} Typically the lookup endpoint is used when a client has an unknown 3PID it wants to find a Matrix User ID for. Clients normally do this kind of @@ -359,8 +359,7 @@ protect the privacy of users who might not have a Matrix identifier bound to their 3PID addresses, the specification attempts to make it difficult to harvest 3PIDs. -Rationale - +{{% boxes/rationale %}} Hashing identifiers, while not perfect, helps make the effort required to harvest identifiers significantly higher. Phone numbers in particular are still difficult to protect with hashing, however hashing is @@ -369,6 +368,7 @@ objectively better than not. An alternative to hashing would be using bcrypt or similar with many rounds, however by nature of needing to serve mobile clients and clients on limited hardware the solution needs be kept relatively lightweight. +{{% /boxes/rationale %}} Clients should be cautious of servers not rotating their pepper very often, and potentially of servers which use a weak pepper - these diff --git a/content/rooms/v1.md b/content/rooms/v1.md index 1649b633..75db1574 100644 --- a/content/rooms/v1.md +++ b/content/rooms/v1.md @@ -46,30 +46,29 @@ of one of the following event types: ## Server implementation components -Warning - +{{% boxes/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. +{{% /boxes/warning %}} 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 - +{{% boxes/warning %}} Although there are many rooms using room version 1, 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. +{{% /boxes/warning %}} ### State resolution -Warning - +{{% boxes/warning %}} Room version 1 is known to have bugs that can cause the state of rooms to reset to older versions of the room's state. For example this could mean that users who had joined the room may be removed from the room, @@ -79,6 +78,7 @@ as the the room's name or topic could also reset to a previous version. This is fixed in the state resolution algorithm introduced in room version 2. +{{% /boxes/warning %}} The room state *S*′(*E*) after an event *E* is defined in terms of the room state *S*(*E*) before *E*, and depends on whether *E* is a state @@ -135,11 +135,11 @@ The types of state events that affect authorization are: - `m.room.power_levels` - `m.room.third_party_invite` -Note - +{{% boxes/note %}} Power levels are inferred from defaults when not explicitly supplied. For example, mentions of the `sender`'s power level can also refer to the default power level for users in the room. +{{% /boxes/note %}} The rules are as follows: @@ -261,8 +261,7 @@ The rules are as follows: 3. Otherwise, reject. 12. Otherwise, allow. -Note - +{{% boxes/note %}} Some consequences of these rules: - Unless you are a member of the room, the only permitted operations @@ -271,6 +270,7 @@ Some consequences of these rules: - To unban somebody, you must have power level greater than or equal to both the kick *and* ban levels, *and* greater than the target user's power level. +{{% /boxes/note %}} ### Event format diff --git a/content/rooms/v2.md b/content/rooms/v2.md index b81235ae..cf668fa6 100644 --- a/content/rooms/v2.md +++ b/content/rooms/v2.md @@ -9,12 +9,12 @@ state resolution algorithm. ## Server implementation components -Warning - +{{% boxes/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. +{{% /boxes/warning %}} Room version 2 uses the base components of [room version 1](v1.html), changing only the state resolution algorithm. @@ -157,8 +157,7 @@ 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). -Rationale - +{{% boxes/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 @@ -182,6 +181,7 @@ Intuitively, using rejected events feels dangerous, however: the event. The duplicated event would then pass the auth checks. Ignoring rejected events would therefore not eliminate any potential attack vectors. +{{% /boxes/rationale %}} Rejected auth events are deliberately excluded from use in the iterative auth checks, as auth events aren't re-authed (although non-auth events diff --git a/content/rooms/v3.md b/content/rooms/v3.md index 0fbfb751..4fecfa39 100644 --- a/content/rooms/v3.md +++ b/content/rooms/v3.md @@ -22,21 +22,20 @@ and the potentially problematic slash). ## Server implementation components -Warning - +{{% boxes/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. +{{% /boxes/warning %}} Room version 3 uses the state resolution algorithm defined in [room version 2](v2.html), and the event format defined here. ### Event IDs -Rationale - +{{% boxes/rationale %}} 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 @@ -44,6 +43,7 @@ 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. +{{% /boxes/rationale %}} The event ID is the [reference hash](../server_server/%SERVER_RELEASE_LABEL%.html#reference-hashes) of diff --git a/content/rooms/v4.md b/content/rooms/v4.md index b5d3deba..8d383069 100644 --- a/content/rooms/v4.md +++ b/content/rooms/v4.md @@ -21,26 +21,26 @@ domain). ## Server implementation components -Warning - +{{% boxes/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. +{{% /boxes/warning %}} Room version 4 uses the same algorithms defined in [room version 3](v3.html), however using URL-safe base64 to generate the event ID. ### Event IDs -Rationale - +{{% boxes/rationale %}} Room version 3 generated event IDs that were difficult for client implementations which were not encoding the event ID to function in those rooms. It additionally raised concern due to the `/` character being interpretted differently by some reverse proxy software, and generally made administration harder. +{{% /boxes/rationale %}} The event ID is the [reference hash](../server_server/%SERVER_RELEASE_LABEL%.html#reference-hashes) of diff --git a/content/rooms/v5.md b/content/rooms/v5.md index 5d8b5767..b5764732 100644 --- a/content/rooms/v5.md +++ b/content/rooms/v5.md @@ -15,13 +15,13 @@ Clients should be aware of event ID changes in [room version ## Server implementation components -Warning - +{{% boxes/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. +{{% /boxes/warning %}} Room version 5 uses the same algorithms defined in [room version 4](v4.html), ensuring that signing key validity is respected. diff --git a/content/rooms/v6.md b/content/rooms/v6.md index 97c99787..f4933756 100644 --- a/content/rooms/v6.md +++ b/content/rooms/v6.md @@ -16,13 +16,13 @@ otherwise unchanged. ## Server implementation components -Warning - +{{% boxes/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. +{{% /boxes/warning %}} Room version 6 makes the following alterations to algorithms described in [room version 5](v5.html). diff --git a/content/server-server-api.md b/content/server-server-api.md index 7c034aa9..33882bd7 100644 --- a/content/server-server-api.md +++ b/content/server-server-api.md @@ -184,12 +184,12 @@ Transparency](https://www.certificate-transparency.org/) project. ### Retrieving server keys -Note - +{{% boxes/note %}} There was once a "version 1" of the key exchange. It has been removed from the specification due to lack of significance. It may be reviewed [from the historical draft](https://github.com/matrix-org/matrix-doc/blob/51faf8ed2e4a63d4cfd6d23183698ed169956cc0/specification/server_server_api.rst#232version-1). +{{% /boxes/note %}} Each homeserver publishes its public keys under `/_matrix/key/v2/server/{keyId}`. Homeservers query for keys by either @@ -451,21 +451,20 @@ rejected event where it is a state event. If an event in an incoming transaction is rejected, this should not cause the transaction request to be responded to with an error response. -Note - +{{% boxes/note %}} This means that events may be included in the room DAG even though they should be rejected. +{{% /boxes/note %}} -Note - +{{% boxes/note %}} This is in contrast to redacted events which can still affect the state of the room. For example, a redacted `join` event will still result in the user being considered joined. +{{% /boxes/note %}} #### Soft failure -Rationale - +{{% boxes/rationale %}} It is important that we prevent users from evading bans (or other power restrictions) by creating events which reference old parts of the DAG. For example, a banned user could continue to send messages to a room by @@ -486,6 +485,7 @@ clients about the new event. This discourages servers from sending events that evade bans etc. in this way, as end users won't actually see the events. +{{% /boxes/rationale %}} When the homeserver receives a new event over federation it should also check whether the event passes auth checks based on the current state of @@ -499,28 +499,28 @@ nor be referenced by new events created by the homeserver (i.e. they should not be added to the server's list of forward extremities of the room). Soft failed events are otherwise handled as usual. -Note - +{{% boxes/note %}} Soft failed events participate in state resolution as normal if further events are received which reference it. It is the job of the state resolution algorithm to ensure that malicious events cannot be injected into the room state via this mechanism. +{{% /boxes/note %}} -Note - +{{% boxes/note %}} Because soft failed state events participate in state resolution as normal, it is possible for such events to appear in the current state of the room. In that case the client should be told about the soft failed event in the usual way (e.g. by sending it down in the `state` section of a sync response). +{{% /boxes/note %}} -Note - +{{% boxes/note %}} A soft failed event should be returned in response to federation requests where appropriate (e.g. in `/event/`). Note that soft failed events are returned in `/backfill` and `/get_missing_events` responses only if the requests include events referencing the soft failed events. +{{% /boxes/note %}} Example @@ -783,11 +783,11 @@ the event to other servers in the room. ## Third-party invites -Note - +{{% boxes/note %}} More information about third party invites is available in the [Client-Server API](../client_server/%CLIENT_RELEASE_LABEL%.html) under the Third Party Invites module. +{{% /boxes/note %}} When a user wants to invite another user in a room but doesn't know the Matrix ID to invite, they can do so using a third-party identifier (e.g. diff --git a/layouts/partials/alert.html b/layouts/partials/alert.html new file mode 100644 index 00000000..9096769f --- /dev/null +++ b/layouts/partials/alert.html @@ -0,0 +1,20 @@ +{{/* + + Display an alert box of the given type, containing the given content. + + Supported types are "warning", "info", and "rationale". + The type determines the colors used in the box and, by default, + the title for the box: WARNING, INFO, RATIONALE. + + By passing "omit_title", a caller can suppress the title, and just get + a box using the colors and styles for the given type. + +*/}} + +{{ $type := .type}} +{{ $content := .content}} +{{ $omit_title := .omit_title }} + + diff --git a/layouts/shortcodes/boxes/note.html b/layouts/shortcodes/boxes/note.html new file mode 100644 index 00000000..48c9d3c9 --- /dev/null +++ b/layouts/shortcodes/boxes/note.html @@ -0,0 +1 @@ +{{ partial "alert" (dict "type" "note" "content" .Inner) }} diff --git a/layouts/shortcodes/boxes/rationale.html b/layouts/shortcodes/boxes/rationale.html new file mode 100644 index 00000000..385bd4b6 --- /dev/null +++ b/layouts/shortcodes/boxes/rationale.html @@ -0,0 +1 @@ +{{ partial "alert" (dict "type" "rationale" "content" .Inner) }} diff --git a/layouts/shortcodes/boxes/warning.html b/layouts/shortcodes/boxes/warning.html new file mode 100644 index 00000000..6e884026 --- /dev/null +++ b/layouts/shortcodes/boxes/warning.html @@ -0,0 +1 @@ +{{ partial "alert" (dict "type" "warning" "content" .Inner) }}