diff --git a/proposals/327-matrix-1.15.md b/proposals/327-matrix-1.15.md new file mode 100644 index 00000000..3d0a480b --- /dev/null +++ b/proposals/327-matrix-1.15.md @@ -0,0 +1,198 @@ +# GSC327: TI-M on Matrix 1.15 + +TI-M basiert im aktuellen Release auf [Matrix 1.11], welches im Juni 2024 veröffentlicht wurde. +Seitdem gab es vier weitere Matrix-Release. Um neue Features und Verbesserungen in TI-M nutzbar zu +machen ist ein Update der Matrix Version in TI-M erforderlich. Dieses Proposal listet die für TI-M +relevanten Matrix-Neuerungen auf und leitet, sofern notwendig, entsprechende Änderungen an der +Spezifikation ab. + +## Änderungsvorschlag + +### `server_name` → `via` Migration + +Der `server_name` Query-Parameter auf [`/_matrix/client/v3/join/{roomIdOrAlias}`] and +[`/_matrix/client/v3/knock/{roomIdOrAlias}`] wurde in [Matrix 1.12] als deprecated markiert und +durch einen neuen Parameter `via` ersetzt. Server müssen dabei weiterhin beide Parameter akzeptieren +aber `via` bevorzugen. + +> - Deprecate the `server_name` query parameter on `POST /_matrix/client/v3/join/{roomIdOrAlias}` +> and `POST /_matrix/client/v3/knock/{roomIdOrAlias}`, as per [MSC4156]. ([\#1933]) +> - Add `via` query parameter on `POST /_matrix/client/v3/join/{roomIdOrAlias}` and +> `POST /_matrix/client/v3/knock/{roomIdOrAlias}`, as per [MSC4156]. ([\#1933]) + +In [Matrix 1.14][Matrix 1.12] wurde der `server_name` Parameter dann gänzlich aus der Spec entfernt. + +> Remove `server_name` parameter from `/_matrix/client/v3/join/{roomIdOrAlias}` and +> `/_matrix/client/v3/knock/{roomIdOrAlias}`, as per [MSC4213]. ([\#2059]) + +Da es bereits TI-M Clients im Feld gibt und diese `via` nicht kennen, müssen TI-M Fachdienste +`server_name` weiterhin als Fallback unterstützen. + +> **A_1 – Weitere Unterstützung von `server_name`** +> +> TI-M Fachdienste MÜSSEN bei den Requests `POST /_matrix/client/v3/join/{roomIdOrAlias}` und +> `POST /_matrix/client/v3/knock/{roomIdOrAlias}` den Parameter `server_name` so wie in Matrix v1.12 +> weiterhin unterstützen. **\[\<=\]** +> +> Hinweis: `server_name` wurde in Matrix v1.14 entfernt und durch den in Matrix v1.12 eingeführten +> `via` Parameter ersetzt. Die Unterstützung von `server_name` nach Matrix v1.12 beinhaltet, dass +> `via` serverseitig bevorzugt wird falls beide Parameter gesetzt sind. + +Clients können über [`/_matrix/client/versions`] erkennen ob ihr Server `via` unterstützt und +wahlweise `via` oder `server_name` verwenden. Alternativ können Clients auch einfach beide Parameter +gleichzeitig und mit identischem Inhalt setzen. TI-M-seitig bedarf es hier keiner weiteren Regelung. + +### Einschränkung von Profilabfragen + +In [Matrix 1.12] wurde für Server die Möglichkeit eingeführt Profilabfragen einzuschränken. Abfragen +müssen nur noch beantwortet werden wenn der anfragende und der angefragte Nutzer gemeinsame Räume +haben oder wenn der angefragte Nutzer Mitglied eines öffentlichen Raumes ist. In allen anderen +Fällen dürfen Server Anfragen mit 403 `M_FORBIDDEN` ablehen. + +> - Add 403 responses on `GET /_matrix/client/v3/profile/{userId}/avatar_url` and +> `GET /_matrix/client/v3/profile/{userId}/displayname`, as per [MSC4170]. ([\#1867]) +> - Add 403 response on `GET /_matrix/federation/v1/query/profile`, as per [MSC4170]. ([\#1867]) + +Die Neuregelung der Fälle in denen Profilabfragen möglich sein müssen entspricht [A_26374] in TI-M +Basis. Diese Anforderung kann daher entfallen. + +Weiterhin verbietet [A_26290] auf ePA-Fachdiensten Profilabfragen in allen anderen Fällen. Diese +Anforderung ist bis auf den fehlenden Fehlercode konform mit der neuen Matrix-Spezifikation. Der +Fehlercode wird daher in die Anforderung eingefügt. + +> **A_26290-1 - Verbot von Profilabfragen ohne gemeinsame Räume** +> +> Der TI-M Fachdienst ePA MUSS Requests zu den folgenden Endpunkten mit einer HTTP 403 Response *und +> dem Fehlercode `M_FORBIDDEN`* ablehnen, sofern der anfragende Nutzer keine gemeinsamen Räume mit +> dem angefragten Nutzer hat: +> +> - `GET /_matrix/client/v3/profile/{userId}` +> - `GET /_matrix/client/v3/profile/{userId}/avatar_url` +> - `GET /_matrix/client/v3/profile/{userId}/displayname` +> +> **\[\<=\]** + +### `dont_notify` und `coalesce` Push Rule Actions + +In [Matrix 1.12] wurde klargestellt, dass die Push Rule Actions `dont_notify` und `coalesce` nicht +abzulehnen sondern zu ignorieren sind. + +> - Clarify that the deprecated `dont_notify` and `coalesce` push rule actions MUST be ignored, not +> rejected. ([\#1890]) + +Da gegenteilige Implementierungen nicht bekannt sind gibt es für TI-M an dieser Stelle eigentlich +nichts zu tun. Gleichzeitig fällt aber auf, dass mit [A_26193] die Verwendung dieser Actions für +TI-M Clients explizit verboten wurde. Dies erscheint überflüssig, da diese Actions von jedem Server +ignoriert werden und ohnehin nicht mehr Teil der Matrix-Spezifikation sind. [A_26193] wird daher +entfernt. + +### OAuth 2.0 APIs + +In [Matrix 1.15] wurden neue OAuth APIs eingeführt. + +> Add the OAuth 2.0 based authentication API, as per [MSC3861] and its sub-proposals. ([\#2141], +> [\#2148], [\#2149], [\#2150], [\#2151], [\#2159], [\#2164]) + +Im Vergleich zu den von TI-M verwendeten Authentication APIs bieten die OAuth APIs den Vorteil, dass +PKCE und State verpflichtend integriert sind. Des Weiteren erleichtert die Verwendung von OAuth die +Nachnutzung bestehender Libraries. Nachteilig ist hingegen, dass die neuen APIs nicht mit der +[User-Interactive Authentication] kompatibel sind. Konkret davon betroffen ist allerdings nur das +Reset der Cross-Signing Keys, wofür es mit [MSC4312] einen Workaround gibt. + +In Summe überwiegen die Vorteile der neuen APIs. Neue TI-M Clients werden daher verpflichtet die +OAuth APIs zu verwenden. + +> **A_2 – Verwendung der OAuth-APIs** +> +> TI-M Clients MÜSSEN sofern ihr Fachdienste Matrix 1.15 unterstützt die [OAuth APIs] zur +> Authentifizierung nutzen. **\[\<=\]** + +Da wir bereits Clients im Feld haben, die Matrix 1.15 nicht unterstützen müssen Fachdienste die +Authentifizierung allerdings weiterhin auch über die alten APIs erlauben. + +> **A_3 – Authentication APIs** +> +> TI-M Fachdienste MÜSSEN die Authentifizierung sowohl über die [OAuth APIs] als auch über die +> [Legacy APIs] erlauben. **\[\<=\]** + +Weiterhin werden Clients und Fachdienste verpflichtet zum Reset der Cross-Signing Keys den +Workaround aus [MSC4312] umzusetzen. + +> **A_4 – Cross-Signing-Reset & OAuth APIs** +> +> TI-M Clients und Fachdienste MÜSSEN zum Reset der Cross-Signing-Keys das Verfahren aus [MSC4312] +> implementieren sofern die Authentifizierung über die [OAuth APIs] erfolgt ist. **\[\<=\]** + +## Nennenswerte Änderungen ohne Anpassungen in TI-M + +### Raumversion 11 + +In [Matrix 1.14] wurde Raum Version 11 als neuer Standard festgelegt + +> Update the default room version to 11, as per [MSC4239]. ([\#2105]) + +Für TI-M gelten wegen [Kapitel 5.4 in TI-M Basis] folgende Regeln: + +- Version 9, 10 und 11 müssen unterstützt werden +- Version 10 muss als Default verwendet werden +- Räume mit Version 11 dürfen nicht erzeugt werden + +Leider haben wir weiterhin Implementierungen aus der alten TI-M 1.x Linie im Feld. Diese basieren +auf Matrix 1.3 und kennen Raumversion 11 nicht. Hier gibt es also vorerst keine Änderung. + +### Mark as unread + +Räume können seit [Matrix 1.12] explizit als ungelesen markiert werden. + +> - Add support for marking rooms as unread, as per [MSC2867]. ([\#1895], [\#1941]) + +Dieses Feature ist Teil des Moduls [Receipts] und kann in TI-M ohne Einschränkung verwendet werden. + +## Sicherheit und Datenschutz + +Die Verwendung der neuen [OAuth APIs] erhöht durch PKCE die Sicherheit des Login-Verfahrens. + +## Kompatibilität & Migration + +Alle obigen Änderungen garantieren Kompatibilität zu bestehenden Implementierungen. + +## Alternativen + +Keine. + + [Matrix 1.11]: https://spec.matrix.org/v1.15/changelog/v1.11/ + [`/_matrix/client/v3/join/{roomIdOrAlias}`]: https://spec.matrix.org/v1.15/client-server-api/#post_matrixclientv3joinroomidoralias + [`/_matrix/client/v3/knock/{roomIdOrAlias}`]: https://spec.matrix.org/v1.15/client-server-api/#post_matrixclientv3knockroomidoralias + [Matrix 1.12]: https://spec.matrix.org/v1.15/changelog/v1.12/ + [MSC4156]: https://github.com/matrix-org/matrix-spec-proposals/pull/4156 + [\#1933]: https://github.com/matrix-org/matrix-spec/issues/1933 + [MSC4213]: https://github.com/matrix-org/matrix-spec-proposals/pull/4213 + [\#2059]: https://github.com/matrix-org/matrix-spec/issues/2059 + [`/_matrix/client/versions`]: https://spec.matrix.org/v1.15/client-server-api/#get_matrixclientversions + [MSC4170]: https://github.com/matrix-org/matrix-spec-proposals/pull/4170 + [\#1867]: https://github.com/matrix-org/matrix-spec/issues/1867 + [A_26374]: https://gemspec.gematik.de/prereleases/Draft_TI-Messenger_24_3/gemSpec_TI-M_Basis_V1.1.0_CC/#A_26374 + [A_26290]: https://gemspec.gematik.de/prereleases/Draft_TI-Messenger_24_3/gemSpec_TI-M_ePA_V1.1.0_CC/#A_26290 + [\#1890]: https://github.com/matrix-org/matrix-spec/issues/1890 + [A_26193]: https://gemspec.gematik.de/prereleases/Draft_TI-Messenger_24_3/gemSpec_TI-M_Basis_V1.1.0_CC/#A_26193 + [Matrix 1.15]: https://spec.matrix.org/v1.15/changelog/v1.15/ + [MSC3861]: https://github.com/matrix-org/matrix-spec-proposals/pull/3861 + [\#2141]: https://github.com/matrix-org/matrix-spec/issues/2141 + [\#2148]: https://github.com/matrix-org/matrix-spec/issues/2148 + [\#2149]: https://github.com/matrix-org/matrix-spec/issues/2149 + [\#2150]: https://github.com/matrix-org/matrix-spec/issues/2150 + [\#2151]: https://github.com/matrix-org/matrix-spec/issues/2151 + [\#2159]: https://github.com/matrix-org/matrix-spec/issues/2159 + [\#2164]: https://github.com/matrix-org/matrix-spec/issues/2164 + [User-Interactive Authentication]: https://spec.matrix.org/v1.15/client-server-api/#user-interactive-authentication-api + [MSC4312]: https://github.com/matrix-org/matrix-spec-proposals/pull/4312 + [OAuth APIs]: https://spec.matrix.org/v1.15/client-server-api/#oauth-20-api + [Legacy APIs]: https://spec.matrix.org/v1.15/client-server-api/#legacy-api + [Matrix 1.14]: https://spec.matrix.org/v1.15/changelog/v1.14/ + [MSC4239]: https://github.com/matrix-org/matrix-spec-proposals/pull/4239 + [\#2105]: https://github.com/matrix-org/matrix-spec/issues/2105 + [Kapitel 5.4 in TI-M Basis]: https://gemspec.gematik.de/docs/gemSpec/gemSpec_TI-M_Basis/latest/#5.4 + [MSC2867]: https://github.com/matrix-org/matrix-spec-proposals/pull/2867 + [\#1895]: https://github.com/matrix-org/matrix-spec/issues/1895 + [\#1941]: https://github.com/matrix-org/matrix-spec/issues/1941 + [Receipts]: https://spec.matrix.org/v1.15/client-server-api/#receipts