From 017b448660edbc27f012e6d0501e0d3edf2d702b Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Fri, 26 Oct 2018 14:20:21 -0600 Subject: [PATCH 01/40] Proposal to add ?via to matrix.to permalinks --- proposals/1704-matrix.to-permalinks.md | 36 ++++++++++++++++++++++++++ 1 file changed, 36 insertions(+) create mode 100644 proposals/1704-matrix.to-permalinks.md diff --git a/proposals/1704-matrix.to-permalinks.md b/proposals/1704-matrix.to-permalinks.md new file mode 100644 index 00000000..1430565c --- /dev/null +++ b/proposals/1704-matrix.to-permalinks.md @@ -0,0 +1,36 @@ +# matrix.to permalink navigation + +Currently Matrix uses matrix.to URIs to reference rooms and other entities in a +permanent manner. With just a room ID, users can't get into rooms if their server +is not already aware of the room. This makes permalinks to rooms or events difficult +as the user won't actually be able to join. A matrix.to link generated using a +room's alias is not a permanent link due to aliases being transferable. + +In lieu of an improved way to reference entities permanently in Matrix, a new parameter +is to be added to matrix.to URIs to assist clients and servers receiving permanent links +in joining the room. + +For reference, existing permalinks look like this: + +``` +https://matrix.to/#/!somewhere:example.org +https://matrix.to/#/!somewhere:example.org/$something:example.org +``` + +By adding a new parameter to the end, receivers can more easily join the room: + +``` +https://matrix.to/#/!somewhere:example.org?via=example-1.org&via=example-2.org +https://matrix.to/#/!somewhere:example.org/$something:example.org?via=example-1.org&via=example-2.org +``` + +Clients can pass the servers directly to `/join` in the form of `server_name` +parameters. + +When generating the permalinks, clients should pick servers that have a reasonably +high chance of being in the room in the distant future. The current recommendation +is to pick up to 3 unique servers where the first one is that of the user with the +highest power level in the room, provided that power level is 50 or higher. The other +2 servers should be the most popular servers in the room based on the number of joined +users. This same heuristic should apply to the first server if no user meets the power +level requirements. From 87330b9b9b01dc089a8781d9775e9252c207b4cb Mon Sep 17 00:00:00 2001 From: Richard van der Hoff Date: Mon, 5 Nov 2018 18:23:23 +0000 Subject: [PATCH 02/40] Proposal for .well-known for server discovery --- proposals/1708-well-known-for-federation.md | 126 ++++++++++++++++++++ 1 file changed, 126 insertions(+) create mode 100644 proposals/1708-well-known-for-federation.md diff --git a/proposals/1708-well-known-for-federation.md b/proposals/1708-well-known-for-federation.md new file mode 100644 index 00000000..2b8a3711 --- /dev/null +++ b/proposals/1708-well-known-for-federation.md @@ -0,0 +1,126 @@ +# .well-known support for server name resolution + +Currently, mapping from a server name to a hostname for federation is done via +`SRV` records. This presents two principal difficulties: + + * SRV records are not widely used, and administrators may be unfamiliar with + them, and there may be other practical difficulties in their deployment such + as poor support from hosting providers. [^1] + + * It is likely that we will soon require valid X.509 certificates on the + federation endpoint. It will then be necessary for the homeserver to present + a certificate which is valid for the server name. This presents difficulties + for hosted server offerings: BigCorp may be reluctant to hand over the + keys for `bigcorp.com` to the administrators of the `bigcorp.com` matrix + homeserver. + +Here we propose to solve these problems by augmenting the current `SRV` record +with a `.well-known` lookup. + +## Proposal + +For reference, the current [specification for resolving server +names](https://matrix.org/docs/spec/server_server/unstable.html#resolving-server-names) +is as follows: + +* If the hostname is an IP literal, then that IP address should be used, + together with the given port number, or 8448 if no port is given. + +* Otherwise, if the port is present, then an IP address is discovered by + looking up an AAAA or A record for the hostname, and the specified port is + used. + +* If the hostname is not an IP literal and no port is given, the server is + discovered by first looking up a `_matrix._tcp` SRV record for the + hostname, which may give a hostname (to be looked up using AAAA or A queries) + and port. If the SRV record does not exist, then the server is discovered by + looking up an AAAA or A record on the hostname and taking the default + fallback port number of 8448. + + Homeservers may use SRV records to load balance requests between multiple TLS + endpoints or to failover to another endpoint if an endpoint fails. + +The first two points remain unchanged: if the server name is an IP literal, or +contains a port, then requests will be made directly as before. + +If the hostname is neither an IP literal, nor does it have an explicit port, +then the requesting server should continue to make an SRV lookup as before, and +use the result if one is found. + +If *no* result is found, the requesting server should make a `GET` request to +`https://\/.well-known/matrix/server`, with normal X.509 +certificate validation. If the request fails in any way, then we fall back as +before to using using port 8448 on the hostname. + +Rationale: Falling back to port 8448 (rather than aborting the request) is +necessary to maintain compatibility with existing deployments, which may not +present valid certificates on port 443, or may return 4xx or 5xx errors. + +If the GET request succeeds, it should result in a JSON response, with contents +structured as shown: + +```json +{ + "server": "[:]" +} +``` + +The `server` property has the same format as a [server +name](https://matrix.org/docs/spec/appendices.html#server-name): a hostname +followed by an optional port. + +If the response cannot be parsed as JSON, or lacks a valid `server` property, +the request is considered to have failed, and no fallback to port 8448 takes +place. + +Otherwise, the requesting server performs an `AAAA/A` lookup on the hostname, +and connects to the resultant address and the specifed port. The port defaults +to 8448, if unspecified. + +### Caching + +Servers should not look up the `.well-known` file for every request, as this +would impose an unacceptable overhead on both sides. Instead, the results of +the `.well-known` request should be cached according to the HTTP response +headers, as per [RFC7234](https://tools.ietf.org/html/rfc7234). If the response +does not include an explicit expiry time, the requesting server should use a +sensible default: 24 hours is suggested. + +Because there is no way to request a revalidation, it is also recommended that +requesting servers cap the expiry time. 48 hours is suggested. + +Similarly, a failure to retrieve the `.well-known` file should be cached for +a reasonable period. 24 hours is suggested again. + +### The future of SRV records + +It's worth noting that this proposal is very clear in that we will maintain +support for SRV records for the immediate future; there are no current plans to +deprecate them. + +However, clearly a `.well-known` file can provide much of the functionality of +an SRV record, and having to support both may be undesirable. Accordingly, we +may consider sunsetting SRV record support at some point in the future. + +### Outstanding questions + +Should we follow 30x redirects for the .well-known file? On the one hand, there +is no obvious usecase and they add complexity (for example: how do they +interact with caches?). On the other hand, we'll presumably be using an HTTP +client library to handle some of the caching stuff, and they might be useful +for something? + +## Security considerations + +The `.well-known` file potentially broadens the attack surface for an attacker +wishing to intercept federation traffic to a particular server. + +## Conclusion + +This proposal adds a new mechanism, alongside the existing `SRV` record lookup +for finding the server responsible for a particular matrix server_name, which +will allow greater flexibility in deploying homeservers. + + +[^1] For example, Cloudflare automatically "flattens" SRV record responses. + From e3f10a4fd2049bcd71f4e77fe4192946498059f2 Mon Sep 17 00:00:00 2001 From: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> Date: Mon, 5 Nov 2018 18:37:25 +0000 Subject: [PATCH 03/40] Update 1708-well-known-for-federation.md fix title --- proposals/1708-well-known-for-federation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/1708-well-known-for-federation.md b/proposals/1708-well-known-for-federation.md index 2b8a3711..beec384f 100644 --- a/proposals/1708-well-known-for-federation.md +++ b/proposals/1708-well-known-for-federation.md @@ -1,4 +1,4 @@ -# .well-known support for server name resolution +# MSC1708: .well-known support for server name resolution Currently, mapping from a server name to a hostname for federation is done via `SRV` records. This presents two principal difficulties: From c4e1949cf8f81b137d9fedebb4d5bf2c5116b112 Mon Sep 17 00:00:00 2001 From: Richard van der Hoff Date: Tue, 6 Nov 2018 11:38:23 +0000 Subject: [PATCH 04/40] Clarifications about what `server` means --- proposals/1708-well-known-for-federation.md | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) diff --git a/proposals/1708-well-known-for-federation.md b/proposals/1708-well-known-for-federation.md index beec384f..8854eb9f 100644 --- a/proposals/1708-well-known-for-federation.md +++ b/proposals/1708-well-known-for-federation.md @@ -47,8 +47,8 @@ If the hostname is neither an IP literal, nor does it have an explicit port, then the requesting server should continue to make an SRV lookup as before, and use the result if one is found. -If *no* result is found, the requesting server should make a `GET` request to -`https://\/.well-known/matrix/server`, with normal X.509 +If *no* SRV result is found, the requesting server should make a `GET` request +to `https://\/.well-known/matrix/server`, with normal X.509 certificate validation. If the request fails in any way, then we fall back as before to using using port 8448 on the hostname. @@ -65,17 +65,19 @@ structured as shown: } ``` -The `server` property has the same format as a [server -name](https://matrix.org/docs/spec/appendices.html#server-name): a hostname -followed by an optional port. +The `server` property should be a hostname or IP address, followed by an +optional port. If the response cannot be parsed as JSON, or lacks a valid `server` property, the request is considered to have failed, and no fallback to port 8448 takes place. -Otherwise, the requesting server performs an `AAAA/A` lookup on the hostname, -and connects to the resultant address and the specifed port. The port defaults -to 8448, if unspecified. +Otherwise, the requesting server performs an `AAAA/A` lookup on the hostname +(if necessary), and connects to the resultant address and the specifed +port. The port defaults to 8448, if unspecified. + +(The formal grammar for the `server` property is identical to that of a [server +name](https://matrix.org/docs/spec/appendices.html#server-name).) ### Caching From 09d41464e7b3d03eb07fe066b4fae4153f79b3c2 Mon Sep 17 00:00:00 2001 From: Richard van der Hoff Date: Tue, 6 Nov 2018 11:38:46 +0000 Subject: [PATCH 05/40] Add problems section xs --- proposals/1708-well-known-for-federation.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/proposals/1708-well-known-for-federation.md b/proposals/1708-well-known-for-federation.md index 8854eb9f..21365be1 100644 --- a/proposals/1708-well-known-for-federation.md +++ b/proposals/1708-well-known-for-federation.md @@ -112,6 +112,21 @@ interact with caches?). On the other hand, we'll presumably be using an HTTP client library to handle some of the caching stuff, and they might be useful for something? +## Problems + +It will take a while for `.well-known` to be supported across the ecosystem; +until it is, it will be difficult to deploy homeservers which rely on it for +their routing: if Alice is using a current homeserver implementation, and Bob +deploys a new implementation which relies on `.well-known` for routing, then +Alice will be unable to send messages to Bob. (This is the same problem we have with +[SNI](https://github.com/matrix-org/synapse/issues/1491#issuecomment-415153428).) + +The main defence against this seems to be to release support for `.well-known` +as soom as possible, to maximise uptake in the ecosystem. It is likely that, as +we approach Matrix 1.0, there will be sufficient other new features (such as +new Room versions) that upgading will be necessary anyway. + + ## Security considerations The `.well-known` file potentially broadens the attack surface for an attacker From f30e6851127874739659ffe2b2c211c4db6e50f0 Mon Sep 17 00:00:00 2001 From: Richard van der Hoff Date: Wed, 7 Nov 2018 13:41:53 +0000 Subject: [PATCH 06/40] proposal for requiring signed certs for federation --- proposals/1711-x509-for-federation.md | 238 ++++++++++++++++++++++++++ 1 file changed, 238 insertions(+) create mode 100644 proposals/1711-x509-for-federation.md diff --git a/proposals/1711-x509-for-federation.md b/proposals/1711-x509-for-federation.md new file mode 100644 index 00000000..9c20eab9 --- /dev/null +++ b/proposals/1711-x509-for-federation.md @@ -0,0 +1,238 @@ +# MSC1711: X.509 certificate verification for federation connections + +TLS connections for server-to-server communication currently rely on an +approach borrowed from the [Perspectives +project](https://web.archive.org/web/20170702024706/https://perspectives-project.org/) +to provide certificate verification, rather than the more normal model using +certificates signed by trusted Certificate Authorities. This document sets out +the reasons that this has not been a success, and suggests that we should +instead revert to the CA model. + +## Background: the failure of the Perspectives approach + +The Perspectives approach replaces the conventional heirarchy of trust provided +by the Certificate Authority model with a large number of "notary" servers +distributed around the world. The intention is that the notary servers +regularly monitor remote servers and observe the certificates they present; +when making a connection to a new site, a client can correlate the certificate +it presents with that seen by the notary servers. In theory this makes it very +hard to mount a Man-in-the-Middle (MitM) attack, because it would require +intercepting traffic between the target server and a large number of the notary +servers. + +It is notable that the Perspectives project itself appears to have largely been +abandoned: its website has largely been repurposed, the [Firefox +extension](https://addons.mozilla.org/en-GB/firefox/addon/perspectives/) does +not work with modern versions of Firefox, the [mailing +list](https://groups.google.com/forum/#!forum/perspectives-dev) is inactive, +and several of the (ten) published notary servers are no longer functional. The +reasons for this are not entirely clear, though clearly it never gained +widespread adoption. + +When Matrix was originally designed in 2014, the Perspectives project was +heavily active, and avoiding dependencies on the relatively centralised +Certificate Authorities was attractive, in accordance with Matrix's design as a +decentralised protocol. However, this has not been a success in practice. + +Matrix was unable to make use of the existing notary servers (largely because +we wanted to extend the protocol to include signing keys): the intention was +that, as the Matrix ecosystem grew, public Matrix servers would act as notary +servers. However, in practice we have ended up in a situation where almost [1](#f1) every Matrix homeserver either uses `matrix.org` as the +sole notary, or does no certificate verification at all. Far from avoiding the +centralisation of the Certificate Authorities, the entire protocol is therefore +dependent on a single point of control at `matrix.org` - and because +`matrix.org` only monitors from a single location, the protection against MitM +attacks is weak. + +It is also clear that the Perspectives approach is poorly-understood. It is a +common error for homeservers to be deployed behind reverse-proxies which make +the Perspectives-based approach unreliable. The CA model, for all its flaws, is +at least commonly used, which makes it easier for administrators to deploy +(secure) homeservers, and allows server implementations to leverage existing +libraries. + +## Proposal + +We propose that Matrix homeservers should be required to present valid TLS +certificates, signed by a known Certificate Authority, on their federation +port. + +In order to ease transition, we could continue to follow the current, +perspectives-based approach for servers whose TLS certificates fail +validation. However, this should be strictly time-limited (for three months, +say), to give administrators time to switch to a signed certificate. The +`matrix.org` team would proactively attempt to reach out to homeserver +administrators who do not update their certificate. + +Once the transition to CA-signed certificates is complete, the +`tls_fingerprints` property of the +[`/_matrix/key/v2`](https://matrix.org/docs/spec/server_server/unstable.html#retrieving-server-keys) +endpoints would be redundant and we should consider removing it. + +The process of determining which CAs are trusted to sign certificates would be +implementation-specific, though it should almost certainly make use of existing +operating-system support for maintaining such lists. It might also be useful if +administrators could override this list, for the purpose of setting up a +private federation using their own CA. + +### Interaction with SRV records + +With the use of `SRV` records, it is possible for the hostname of a homeserver +to be quite different from the matrix domain it is hosting. For example, if +there were an SRV record at `_matrix._tcp.matrix.org` which pointed to +`server.example.com`, then any federation requests for `matrix.org` would be +routed to `server.example.com`. The question arises as to which certificate +`server.example.com` should present. + +In short: the server should present a certificate for the matrix domain +(`matrix.org` in the above example). This ensures that traffic cannot be +intercepted by a MitM who can control the DNS response for the `SRV` record +(perhaps via cache-poisoning or falsifying DNS responses). + +This will be in line with the current +[requirements](https://matrix.org/docs/spec/server_server/unstable.html#resolving-server-names) +in the Federation API specification for the `Host`, and by implication, the TLS +Server Name Indication [2](#f2). + +### Interaction with `.well-known` files + +[MSC1708](https://github.com/matrix-org/matrix-doc/blob/rav/proposal/well-known-for-federation/proposals/1708-well-known-for-federation.md) +proposes an alternative to SRV records, in the form of `.well-known` files. In +this instance, a file at `https://matrix.org/.well-known/matrix/server` might +direct requests to `server.example.com`. + +In this case, `server.example.com` would be required to present a valid +certificate for `server.example.com`. + +Because the request for the `.well-known` file takes place over a validated TLS +connection, this is not subject to the same DNS-based attacks as the SRV +record, and this mechanism allows the owners of a domain to delegate +responsibility for running their Matrix homeserver without having to hand over +TLS keys for the whole domain. + +### Extensions + +HTTP-Based Public Key Pinning (HPKP) and +[https://www.certificate-transparency.org](Certificate transparency) are +both HTTP extensions which attempt to work around some of the deficiencies in +the CA model, by making it more obvious if a CA has issued a certificate +incorrectly. + +HPKP has not been particularly successful, and is +[deprecated]((https://developers.google.com/web/updates/2018/04/chrome-67-deps-rems#deprecate_http-based_public_key_pinning) +in Google Chrome as of April 2018. Certificate transparency, however, is seeing +widespread adoption from Certificate Authories and HTTP clients. + +This proposal sees both technologies as optional techniques which could be +provided by homeserver implementations. We encourage but do not mandate the use +of Certificate Transparency. + +### Related work + +The Perspectives approach is also currently used for exchanging the keys that +are used by homeservers to sign Matrix events and federation requests (the +"signing keys"). Problems similar to those covered here also apply to that +mechanism. A future MSC will propose improvements in that area. + +## Tradeoffs + +There are well-known problems with the CA model, including a number of +widely-published incidents in which CAs have issued certificates +incorrectly. It is therefore important to consider alternatives to the CA +model. + +### Improving support for the Perspectives model + +In principle, we could double-down on the Perspectives approach, and make an effort +to get servers other than `matrix.org` used as notary servers. However, there +remain significant problems with such an approach: + +* Perspectives remain complex to configure correctly. Ideally, administrators + need to make conscious choices about which notaries to trust, which is hard + to do, especially for newcomers to the ecosystem. (In practice, people use + the out-of-the-box configuration, which is why everyone just uses + `matrix.org` today). + +* A *correct* implementation of Perspectives really needs to take into account + more than the latest state seen by the notary servers: some level of history + should be taken into account too. + +Essentially, whilst we still believe the Perspectives approach has some merit, +we believe it needs further research before it can be relied upon. We believe +that the resources of the Matrix ecosystem are better spent elsewhere. + +### DANE + +DNS-Based Authentication of Named Entities (DANE) can be used as an alternative +to the CA model. (It is arguably more appropriately used *together* with the CA +model.) + +It is not obvious to the author of this proposal that DANE provides any +material advantages over the CA model. In particular it replaces the +centralised trust of the CAs with the centralised trust of the DNS registries. + +## Potential issues + +Beyond the problems already discussed with the CA model, requiring signed +certificates comes with a number of downsides. + +### More difficult setup + +Configuring a working, federating homeserver is a process fraught with +pitfalls. This proposal adds the requirement to obtain a signed certificate to +that process. Even with modern intiatives such as Let's Encrypt, this is +another procedure requiring manual intervention across several moving parts[3](#f3). + +On the other hand: obtaining an SSL certificate should be a familiar process to +anybody capable of hosting a production homeserver (indeed, they should +probably already have one for the client port). This change also opens the +possibility of putting the federation port behind a reverse-proxy without the +need for additional configuration. Hopefully making the certificate usage more +conventional will offset the overhead of setting up a certificate. + +### Inferior support for IP literals + +Whilst it is possible to obtain an SSL cert which is valid for a literal IP +address, this typically requires purchase of a premium certificate; in +particular, Let's Encrypt will not issue certificates for IP literals. This may +make it impractical to run a homeserver which uses an IP literal, rather than a +DNS name, as its `server_name`. + +It has long been the view of the `matrix.org` administrators that IP literals +are only really suitable for internal testing. Those who wish to use them for +that purpose could either disable certificate checks inside their network, or +use their own CA to issue certificates. + +### Inferior support for hidden services (`.onion` addresses) + +It is currently possible to correctly route traffic to a homeserver on a +`.onion` domain, provided any remote servers which may need to reach that +server are configured to route to such addresses via the Tor network. However, +it can be difficult to get a certificate for a `.onion` domain (again, Let's +Encrypt do not support them). + +The reasons for requiring a signed certificate (or indeed, for using TLS at +all) are weakened when traffic is routed via the Tor network. It may be +reasonable to relax the requirement for a signed certificate for such traffic. + +## Conclusion + +We believe that requiring homservers to present an X.509 certificate signed by +a recognised Certificate Authority will improve security, reduce +centralisation, and eliminate some common deployment pitfalls. + +[1] It's *possible* to set up homeservers to use servers other than +`matrix.org` as notaries, but we are not aware of any that are set up this +way. [↩](#a1) + +[2] I've not been able to find an authoritative source on this, but +most reverse-proxies will reject requests where the SNI and Host headers do not +match. [↩](#a2) + +[3] Let's Encrypt will issue ACME challenges via port 80 or DNS +(for the `http-01` or `dns-01` challenge types respectively). It is unlikely +that a homeserver implementation would be able to control either port 80 or DNS +responses, so we will be unable to automate a Let's Encrypt certificate +request. [↩](#a3) From efc8056fb62ccb7501efae146abb646914f69b1d Mon Sep 17 00:00:00 2001 From: Richard van der Hoff Date: Wed, 7 Nov 2018 13:48:27 +0000 Subject: [PATCH 07/40] fix a couple of broken links --- proposals/1711-x509-for-federation.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/proposals/1711-x509-for-federation.md b/proposals/1711-x509-for-federation.md index 9c20eab9..a31ae482 100644 --- a/proposals/1711-x509-for-federation.md +++ b/proposals/1711-x509-for-federation.md @@ -114,13 +114,13 @@ TLS keys for the whole domain. ### Extensions HTTP-Based Public Key Pinning (HPKP) and -[https://www.certificate-transparency.org](Certificate transparency) are +[Certificate transparency](https://www.certificate-transparency.org) are both HTTP extensions which attempt to work around some of the deficiencies in the CA model, by making it more obvious if a CA has issued a certificate incorrectly. HPKP has not been particularly successful, and is -[deprecated]((https://developers.google.com/web/updates/2018/04/chrome-67-deps-rems#deprecate_http-based_public_key_pinning) +[deprecated](https://developers.google.com/web/updates/2018/04/chrome-67-deps-rems#deprecate_http-based_public_key_pinning) in Google Chrome as of April 2018. Certificate transparency, however, is seeing widespread adoption from Certificate Authories and HTTP clients. From f9cf99f1fd6c1b0cbdf77e86b6a4e532c13adb2a Mon Sep 17 00:00:00 2001 From: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> Date: Thu, 8 Nov 2018 15:31:58 +0000 Subject: [PATCH 08/40] typo --- proposals/1711-x509-for-federation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/1711-x509-for-federation.md b/proposals/1711-x509-for-federation.md index a31ae482..d30fe566 100644 --- a/proposals/1711-x509-for-federation.md +++ b/proposals/1711-x509-for-federation.md @@ -219,7 +219,7 @@ reasonable to relax the requirement for a signed certificate for such traffic. ## Conclusion -We believe that requiring homservers to present an X.509 certificate signed by +We believe that requiring homeservers to present an X.509 certificate signed by a recognised Certificate Authority will improve security, reduce centralisation, and eliminate some common deployment pitfalls. From bc290155145d9e8d4721dbae111d0d13f83cd01a Mon Sep 17 00:00:00 2001 From: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> Date: Thu, 8 Nov 2018 16:28:13 +0000 Subject: [PATCH 09/40] fix typo --- proposals/1711-x509-for-federation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/1711-x509-for-federation.md b/proposals/1711-x509-for-federation.md index d30fe566..52662123 100644 --- a/proposals/1711-x509-for-federation.md +++ b/proposals/1711-x509-for-federation.md @@ -10,7 +10,7 @@ instead revert to the CA model. ## Background: the failure of the Perspectives approach -The Perspectives approach replaces the conventional heirarchy of trust provided +The Perspectives approach replaces the conventional hierarchy of trust provided by the Certificate Authority model with a large number of "notary" servers distributed around the world. The intention is that the notary servers regularly monitor remote servers and observe the certificates they present; From b1e79ac7ab37302c2c90f2f031a8c6f8d4d2d34b Mon Sep 17 00:00:00 2001 From: Matthew Hodgson Date: Fri, 9 Nov 2018 11:22:22 +0000 Subject: [PATCH 10/40] Update 1708-well-known-for-federation.md --- proposals/1708-well-known-for-federation.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/proposals/1708-well-known-for-federation.md b/proposals/1708-well-known-for-federation.md index 21365be1..bd2f32b8 100644 --- a/proposals/1708-well-known-for-federation.md +++ b/proposals/1708-well-known-for-federation.md @@ -122,9 +122,9 @@ Alice will be unable to send messages to Bob. (This is the same problem we have [SNI](https://github.com/matrix-org/synapse/issues/1491#issuecomment-415153428).) The main defence against this seems to be to release support for `.well-known` -as soom as possible, to maximise uptake in the ecosystem. It is likely that, as +as soon as possible, to maximise uptake in the ecosystem. It is likely that, as we approach Matrix 1.0, there will be sufficient other new features (such as -new Room versions) that upgading will be necessary anyway. +new Room versions) that upgrading will be necessary anyway. ## Security considerations From e789eb186a8f12fe2517d1b30c8e38989d3c3b5f Mon Sep 17 00:00:00 2001 From: Richard van der Hoff Date: Mon, 12 Nov 2018 14:02:44 +0000 Subject: [PATCH 11/40] link to MSC1711 --- proposals/1708-well-known-for-federation.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/proposals/1708-well-known-for-federation.md b/proposals/1708-well-known-for-federation.md index bd2f32b8..8fa66c7a 100644 --- a/proposals/1708-well-known-for-federation.md +++ b/proposals/1708-well-known-for-federation.md @@ -7,7 +7,8 @@ Currently, mapping from a server name to a hostname for federation is done via them, and there may be other practical difficulties in their deployment such as poor support from hosting providers. [^1] - * It is likely that we will soon require valid X.509 certificates on the + * [MSC1711](https://github.com/matrix-org/matrix-doc/pull/1711) proposes + requiring valid X.509 certificates on the federation endpoint. It will then be necessary for the homeserver to present a certificate which is valid for the server name. This presents difficulties for hosted server offerings: BigCorp may be reluctant to hand over the @@ -140,4 +141,3 @@ will allow greater flexibility in deploying homeservers. [^1] For example, Cloudflare automatically "flattens" SRV record responses. - From 0e156faaf1c67d1f45345f45ac837f87ca8d74ba Mon Sep 17 00:00:00 2001 From: Richard van der Hoff Date: Wed, 12 Dec 2018 21:43:40 +0000 Subject: [PATCH 12/40] MSC1753: client-server capabilities API --- proposals/1753-capabilities.md | 99 ++++++++++++++++++++++++++++++++++ 1 file changed, 99 insertions(+) create mode 100644 proposals/1753-capabilities.md diff --git a/proposals/1753-capabilities.md b/proposals/1753-capabilities.md new file mode 100644 index 00000000..23d22c4f --- /dev/null +++ b/proposals/1753-capabilities.md @@ -0,0 +1,99 @@ +# MSC1753: client-server capabilities API + +A mechanism is needed for clients to interrogate servers to establish whether +particular operations can be performed. + +For example, users may not be able to change their password if a server is +configured to authenticate against a separate system, in which case it is +nonsensical to offer the user such an option. + +## Proposal + +### `POST /_matrix/client/r0/capabilities` + +We will add a new endpoint to the client-server API: `POST +/_matrix/client/r0/capabilities`. The endpoint will be authenticated as normal +via an access token. + +The body of the request will list the capabilities the client is interested +in, as shown: + +```json +{ + "capabilities": { + "m.capability_one": {}, + "com.example.custom_capability": {} + } +} +``` + +The keys of the `capabilities` object are capability identifiers. As with +other identifiers in the Matrix protocol, the `m.` prefix is reserved for +definition in the Matrix specification; other values can be used within an +organisation following the Java package naming conventions. + +The values of the `capabilities` object will depend on the capability +identifier, though in general the empty object will suffice. + +The server should reply with a list of the operations the client may perform, +as shown: + +```json +{ + "capabilities": { + "m.capability_one": {} + } +} +``` + +The server should exclude from the list any operations which the client cannot +currently perform. It should also exclude any capabilities it does not +recognise or support, or whose value in the query did not have the expected +form. + +Again the values of the `capabilities` object will depend on the capability +identifier. + +### Initial capability identifiers + +As a starting point, a single capability identifier is proposed: +`m.change_password`, which should be considered supported if it is possible to +change the user's password via the `POST /_matrix/client/r0/account/password` +API. + +The values of the `capabilities` object should be the empty object in both the +query and the response. + +### Fallback behaviour + +Clients will need to be aware of servers which do not support the new endpoint, +and fall back to their current behaviour if they receive a 404 response. + +## Tradeoffs + +One alternative would be to provide specific ways of establishing support for +each operation: for example, a client might send an `GET +/_matrix/client/r0/account/password` request to see if the user can change +their password. The concern with this approach is that this could require a +large number of requests to establish which entries should appear on a menu or +dialog box. + +Another alternative would be a simple `GET /_matrix/client/r0/capabilities` +query, where a server would return all possible supported operations. The +problem with this is that it may add load to the server, and increase network +traffic, by returning a large number of features which the client may have no +interest in. + +## Potential issues + +None yet identified. + +## Security considerations + +None yet identified. + +## Conclusion + +We propose adding a new endpoint to the Client-Server API, which will allow +clients to query for supported operations so that they can decide whether to +expose them in their user-interface. From 68ac2172bab4669cf5243c241b606c0ff254acdb Mon Sep 17 00:00:00 2001 From: Richard van der Hoff Date: Fri, 21 Dec 2018 17:39:52 +0000 Subject: [PATCH 13/40] Give examples of applications --- proposals/1753-capabilities.md | 43 ++++++++++++++++++++++++++++++++++ 1 file changed, 43 insertions(+) diff --git a/proposals/1753-capabilities.md b/proposals/1753-capabilities.md index 23d22c4f..bcc5b2a3 100644 --- a/proposals/1753-capabilities.md +++ b/proposals/1753-capabilities.md @@ -69,6 +69,49 @@ query and the response. Clients will need to be aware of servers which do not support the new endpoint, and fall back to their current behaviour if they receive a 404 response. +### Suitable applications + +In general, capabilities advertised via this endpoiunt should depend in some +way on the state of the user or server - in other words, they will inherently +"optional" features in the API. + +This endpoint should *not* be used to advertise support for experimental or +unstable features, which is better done via `/client/r0/versions` (see +[MSC1497](https://github.com/matrix-org/matrix-doc/issues/1497)). + +Examples of features which might reasonably be advertised here include: + + * Whether the server supports user presence. + + * Whether the server supports other optional features. The following could be + made optional via this mechanism: + * Room directory + * URL previews + + * Policy restricitions, such as: + * Whether certain types of content are permitted on this server. + * The number of rooms you are allowed in. + * Configured ratelimits. + + +Features which might be better advertised elsewhere include: + + * Support for e2e key backups + ([MSC1219](https://github.com/matrix-org/matrix-doc/issues/1219)) - list in + `/client/r0/versions`. + + * Support for lazy-loading of room members - list in `/client/r0/versions`. + + * Media size limits - list in `/media/r0/config`, because the media server may + be a separate process. + + * Optional transports/encodings for the CS API - probably better handled via + HTTP headers etc. + + * Variations in room state resolution - this is implied via the room version + (which is in the `m.room.create` event). + + ## Tradeoffs One alternative would be to provide specific ways of establishing support for From 82f3b8a95a4be1b485a23be775458aea53ba324e Mon Sep 17 00:00:00 2001 From: Richard van der Hoff Date: Fri, 21 Dec 2018 17:47:52 +0000 Subject: [PATCH 14/40] switch to GET --- proposals/1753-capabilities.md | 43 +++++++--------------------------- 1 file changed, 9 insertions(+), 34 deletions(-) diff --git a/proposals/1753-capabilities.md b/proposals/1753-capabilities.md index bcc5b2a3..386e66dc 100644 --- a/proposals/1753-capabilities.md +++ b/proposals/1753-capabilities.md @@ -9,20 +9,18 @@ nonsensical to offer the user such an option. ## Proposal -### `POST /_matrix/client/r0/capabilities` +### `GET /_matrix/client/r0/capabilities` -We will add a new endpoint to the client-server API: `POST +We will add a new endpoint to the client-server API: `GET /_matrix/client/r0/capabilities`. The endpoint will be authenticated as normal via an access token. -The body of the request will list the capabilities the client is interested -in, as shown: +The server should reply with a list of supported features, as shown: ```json { "capabilities": { - "m.capability_one": {}, - "com.example.custom_capability": {} + "m.capability_one": {} } } ``` @@ -35,25 +33,6 @@ organisation following the Java package naming conventions. The values of the `capabilities` object will depend on the capability identifier, though in general the empty object will suffice. -The server should reply with a list of the operations the client may perform, -as shown: - -```json -{ - "capabilities": { - "m.capability_one": {} - } -} -``` - -The server should exclude from the list any operations which the client cannot -currently perform. It should also exclude any capabilities it does not -recognise or support, or whose value in the query did not have the expected -form. - -Again the values of the `capabilities` object will depend on the capability -identifier. - ### Initial capability identifiers As a starting point, a single capability identifier is proposed: @@ -61,8 +40,8 @@ As a starting point, a single capability identifier is proposed: change the user's password via the `POST /_matrix/client/r0/account/password` API. -The values of the `capabilities` object should be the empty object in both the -query and the response. +The value of the `capabilities` object in the response should be the empty +object. ### Fallback behaviour @@ -93,7 +72,6 @@ Examples of features which might reasonably be advertised here include: * The number of rooms you are allowed in. * Configured ratelimits. - Features which might be better advertised elsewhere include: * Support for e2e key backups @@ -111,7 +89,6 @@ Features which might be better advertised elsewhere include: * Variations in room state resolution - this is implied via the room version (which is in the `m.room.create` event). - ## Tradeoffs One alternative would be to provide specific ways of establishing support for @@ -121,11 +98,9 @@ their password. The concern with this approach is that this could require a large number of requests to establish which entries should appear on a menu or dialog box. -Another alternative would be a simple `GET /_matrix/client/r0/capabilities` -query, where a server would return all possible supported operations. The -problem with this is that it may add load to the server, and increase network -traffic, by returning a large number of features which the client may have no -interest in. +Another alternative is to provide a generic query mechanism where the client +can query for specific capabilities it is interested in. However, this adds +complication and makes it harder to discover capability identifiers. ## Potential issues From 7f5832044c6b16d1099dc117bea481ed7613f338 Mon Sep 17 00:00:00 2001 From: Richard van der Hoff Date: Wed, 2 Jan 2019 09:55:14 +0000 Subject: [PATCH 15/40] Fix typos per review --- proposals/1753-capabilities.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/proposals/1753-capabilities.md b/proposals/1753-capabilities.md index 386e66dc..4ac0ac05 100644 --- a/proposals/1753-capabilities.md +++ b/proposals/1753-capabilities.md @@ -50,8 +50,8 @@ and fall back to their current behaviour if they receive a 404 response. ### Suitable applications -In general, capabilities advertised via this endpoiunt should depend in some -way on the state of the user or server - in other words, they will inherently +In general, capabilities advertised via this endpoint should depend in some way +on the state of the user or server - in other words, they will be inherently "optional" features in the API. This endpoint should *not* be used to advertise support for experimental or From 962565b15959b032eb38943ad57ff577d5e03cd2 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Thu, 3 Jan 2019 17:40:49 +0000 Subject: [PATCH 16/40] Update proposals/1753-capabilities.md r0/versions isn't a thing Co-Authored-By: richvdh <1389908+richvdh@users.noreply.github.com> --- proposals/1753-capabilities.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/1753-capabilities.md b/proposals/1753-capabilities.md index 4ac0ac05..5c3ada41 100644 --- a/proposals/1753-capabilities.md +++ b/proposals/1753-capabilities.md @@ -55,7 +55,7 @@ on the state of the user or server - in other words, they will be inherently "optional" features in the API. This endpoint should *not* be used to advertise support for experimental or -unstable features, which is better done via `/client/r0/versions` (see +unstable features, which is better done via `/client/versions` (see [MSC1497](https://github.com/matrix-org/matrix-doc/issues/1497)). Examples of features which might reasonably be advertised here include: From 40196786619f75f3424258735f3958ac69b6a455 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Thu, 3 Jan 2019 17:40:57 +0000 Subject: [PATCH 17/40] Update proposals/1753-capabilities.md r0/versions isn't a thing Co-Authored-By: richvdh <1389908+richvdh@users.noreply.github.com> --- proposals/1753-capabilities.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/1753-capabilities.md b/proposals/1753-capabilities.md index 5c3ada41..cbda92d8 100644 --- a/proposals/1753-capabilities.md +++ b/proposals/1753-capabilities.md @@ -76,7 +76,7 @@ Features which might be better advertised elsewhere include: * Support for e2e key backups ([MSC1219](https://github.com/matrix-org/matrix-doc/issues/1219)) - list in - `/client/r0/versions`. + `/client/versions`. * Support for lazy-loading of room members - list in `/client/r0/versions`. From ca2e9260d427b9ec620e7fa94c9d13345cda463e Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Thu, 3 Jan 2019 17:41:06 +0000 Subject: [PATCH 18/40] Update proposals/1753-capabilities.md r0/versions isn't a thing Co-Authored-By: richvdh <1389908+richvdh@users.noreply.github.com> --- proposals/1753-capabilities.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/1753-capabilities.md b/proposals/1753-capabilities.md index cbda92d8..ec5169ab 100644 --- a/proposals/1753-capabilities.md +++ b/proposals/1753-capabilities.md @@ -78,7 +78,7 @@ Features which might be better advertised elsewhere include: ([MSC1219](https://github.com/matrix-org/matrix-doc/issues/1219)) - list in `/client/versions`. - * Support for lazy-loading of room members - list in `/client/r0/versions`. + * Support for lazy-loading of room members - list in `/client/versions`. * Media size limits - list in `/media/r0/config`, because the media server may be a separate process. From e0fa00fc34c3b67ee8166e19372e569eabce42c9 Mon Sep 17 00:00:00 2001 From: Richard van der Hoff Date: Thu, 3 Jan 2019 18:21:05 +0000 Subject: [PATCH 19/40] Some HSes use more than one notary --- proposals/1711-x509-for-federation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/1711-x509-for-federation.md b/proposals/1711-x509-for-federation.md index 52662123..82881d93 100644 --- a/proposals/1711-x509-for-federation.md +++ b/proposals/1711-x509-for-federation.md @@ -224,7 +224,7 @@ a recognised Certificate Authority will improve security, reduce centralisation, and eliminate some common deployment pitfalls. [1] It's *possible* to set up homeservers to use servers other than -`matrix.org` as notaries, but we are not aware of any that are set up this +`matrix.org` as notaries, but only a minority are actually set up this way. [↩](#a1) [2] I've not been able to find an authoritative source on this, but From 671527360cb68ad8cf789a743fd7bd42f8751e64 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 7 Jan 2019 13:16:45 -0700 Subject: [PATCH 20/40] Recommend some kind of WIP tag for MSCs --- specification/proposals_intro.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/proposals_intro.rst b/specification/proposals_intro.rst index 73ace98e..0b69e846 100644 --- a/specification/proposals_intro.rst +++ b/specification/proposals_intro.rst @@ -231,7 +231,7 @@ Lifetime States =============================== ============================= ==================================== Name GitHub Label Description =============================== ============================= ==================================== -Proposal Drafting and Feedback N/A A proposal document which is still work-in-progress but is being shared to incorporate feedback +Proposal Drafting and Feedback N/A A proposal document which is still work-in-progress but is being shared to incorporate feedback. Please prefix your proposal's title with ``[WIP]`` to highlight this state. Proposal In Review proposal-in-review A proposal document which is now ready and waiting for review by the Core Team and community Proposed Final Comment Period proposed-final-comment-period Currently awaiting signoff of a majority of team members in order to enter the final comment period Final Comment Period final-comment-period A proposal document which has reached final comment period either for merge, closure or postponement From bc1303a1a06e6884e42b96518119e98d447daa41 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 7 Jan 2019 13:39:50 -0700 Subject: [PATCH 21/40] Add a bit of rationale for WIP tags --- specification/proposals_intro.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/proposals_intro.rst b/specification/proposals_intro.rst index 0b69e846..96ffaafc 100644 --- a/specification/proposals_intro.rst +++ b/specification/proposals_intro.rst @@ -231,7 +231,7 @@ Lifetime States =============================== ============================= ==================================== Name GitHub Label Description =============================== ============================= ==================================== -Proposal Drafting and Feedback N/A A proposal document which is still work-in-progress but is being shared to incorporate feedback. Please prefix your proposal's title with ``[WIP]`` to highlight this state. +Proposal Drafting and Feedback N/A A proposal document which is still work-in-progress but is being shared to incorporate feedback. Please prefix your proposal's title with ``[WIP]`` to make it easier for reviewers to skim their notifications list. Proposal In Review proposal-in-review A proposal document which is now ready and waiting for review by the Core Team and community Proposed Final Comment Period proposed-final-comment-period Currently awaiting signoff of a majority of team members in order to enter the final comment period Final Comment Period final-comment-period A proposal document which has reached final comment period either for merge, closure or postponement From 367f61f14a0f475f0f95c77cd2cd27254e0e7124 Mon Sep 17 00:00:00 2001 From: Richard van der Hoff Date: Mon, 7 Jan 2019 21:38:41 +0000 Subject: [PATCH 22/40] cleanups and clarifications --- proposals/1711-x509-for-federation.md | 44 ++++++++++++++++++--------- 1 file changed, 30 insertions(+), 14 deletions(-) diff --git a/proposals/1711-x509-for-federation.md b/proposals/1711-x509-for-federation.md index 82881d93..dc737ff6 100644 --- a/proposals/1711-x509-for-federation.md +++ b/proposals/1711-x509-for-federation.md @@ -58,17 +58,18 @@ We propose that Matrix homeservers should be required to present valid TLS certificates, signed by a known Certificate Authority, on their federation port. -In order to ease transition, we could continue to follow the current, -perspectives-based approach for servers whose TLS certificates fail -validation. However, this should be strictly time-limited (for three months, -say), to give administrators time to switch to a signed certificate. The -`matrix.org` team would proactively attempt to reach out to homeserver -administrators who do not update their certificate. - -Once the transition to CA-signed certificates is complete, the +In order to ease transition and give administrators time to switch to a signed +certificate, we will continue to follow the current, perspectives-based +approach for servers whose TLS certificates fail validation. + +However, this fallback will be strictly time-limited, and Matrix S2S spec r0 +will not accept self-signed certificates, nor will it include the `tls_fingerprints` property of the [`/_matrix/key/v2`](https://matrix.org/docs/spec/server_server/unstable.html#retrieving-server-keys) -endpoints would be redundant and we should consider removing it. +endpoints. Synapse 1.0 will not accept self-signed certificates by default. + +The `matrix.org` team will proactively attempt to reach out to homeserver +administrators who do not update their certificates in the coming weeks. The process of determining which CAs are trusted to sign certificates would be implementation-specific, though it should almost certainly make use of existing @@ -76,6 +77,12 @@ operating-system support for maintaining such lists. It might also be useful if administrators could override this list, for the purpose of setting up a private federation using their own CA. +It would also be useful for administrators to be able to disable the +certificate checks for a whitelist of domains/netmasks. This would be useful +for `.onion` domains (where a certificate is hard to obtain, and where server +verification is provided at the network level), as well as for testing with IP +literals. + ### Interaction with SRV records With the use of `SRV` records, it is possible for the hostname of a homeserver @@ -93,7 +100,10 @@ intercepted by a MitM who can control the DNS response for the `SRV` record This will be in line with the current [requirements](https://matrix.org/docs/spec/server_server/unstable.html#resolving-server-names) in the Federation API specification for the `Host`, and by implication, the TLS -Server Name Indication [2](#f2). +Server Name Indication [2](#f2). It is also consistent with +the recommendations of +[RFC6125](https://tools.ietf.org/html/rfc6125#section-6.2.1) and the +conventions established by the XMPP protocol (per [RFC6120](https://tools.ietf.org/html/rfc6120#section-13.7.2.1). ### Interaction with `.well-known` files @@ -133,9 +143,9 @@ of Certificate Transparency. The Perspectives approach is also currently used for exchanging the keys that are used by homeservers to sign Matrix events and federation requests (the "signing keys"). Problems similar to those covered here also apply to that -mechanism. A future MSC will propose improvements in that area. +mechanism. This is discussed at [#1685](thttps://github.com/matrix-org/matrix-doc/issues/1685). -## Tradeoffs +## Alternatives There are well-known problems with the CA model, including a number of widely-published incidents in which CAs have issued certificates @@ -192,6 +202,12 @@ possibility of putting the federation port behind a reverse-proxy without the need for additional configuration. Hopefully making the certificate usage more conventional will offset the overhead of setting up a certificate. +Furthermore, homeserver implementations could provide an implementation of the +ACME protocol and integration with Let's Encrypt, to make it easier for +administrators to get started. (This would of course be +implementation-specific, and administrators who wanted to keep control of the +certificate creation process would be free to do so). + ### Inferior support for IP literals Whilst it is possible to obtain an SSL cert which is valid for a literal IP @@ -214,8 +230,8 @@ it can be difficult to get a certificate for a `.onion` domain (again, Let's Encrypt do not support them). The reasons for requiring a signed certificate (or indeed, for using TLS at -all) are weakened when traffic is routed via the Tor network. It may be -reasonable to relax the requirement for a signed certificate for such traffic. +all) are weakened when traffic is routed via the Tor network. Administrators +using the Tor network could disable certificate checks for `.onion` addresses. ## Conclusion From 74b2db7937bc23226770d8f0fb457ba667bf0e58 Mon Sep 17 00:00:00 2001 From: Richard van der Hoff Date: Mon, 7 Jan 2019 21:39:02 +0000 Subject: [PATCH 23/40] Remove .well-known section This really belongs in MSC1708. --- proposals/1711-x509-for-federation.md | 16 ---------------- 1 file changed, 16 deletions(-) diff --git a/proposals/1711-x509-for-federation.md b/proposals/1711-x509-for-federation.md index dc737ff6..43fd9657 100644 --- a/proposals/1711-x509-for-federation.md +++ b/proposals/1711-x509-for-federation.md @@ -105,22 +105,6 @@ the recommendations of [RFC6125](https://tools.ietf.org/html/rfc6125#section-6.2.1) and the conventions established by the XMPP protocol (per [RFC6120](https://tools.ietf.org/html/rfc6120#section-13.7.2.1). -### Interaction with `.well-known` files - -[MSC1708](https://github.com/matrix-org/matrix-doc/blob/rav/proposal/well-known-for-federation/proposals/1708-well-known-for-federation.md) -proposes an alternative to SRV records, in the form of `.well-known` files. In -this instance, a file at `https://matrix.org/.well-known/matrix/server` might -direct requests to `server.example.com`. - -In this case, `server.example.com` would be required to present a valid -certificate for `server.example.com`. - -Because the request for the `.well-known` file takes place over a validated TLS -connection, this is not subject to the same DNS-based attacks as the SRV -record, and this mechanism allows the owners of a domain to delegate -responsibility for running their Matrix homeserver without having to hand over -TLS keys for the whole domain. - ### Extensions HTTP-Based Public Key Pinning (HPKP) and From f33a540e6dbc6287b03c3633f09144a3266c26b4 Mon Sep 17 00:00:00 2001 From: Richard van der Hoff Date: Tue, 8 Jan 2019 00:25:06 +0000 Subject: [PATCH 24/40] Do a SRV lookup before .well-known lookup also other clarifications and corrections. --- proposals/1708-well-known-for-federation.md | 133 ++++++++++---------- 1 file changed, 69 insertions(+), 64 deletions(-) diff --git a/proposals/1708-well-known-for-federation.md b/proposals/1708-well-known-for-federation.md index 8fa66c7a..6e857b85 100644 --- a/proposals/1708-well-known-for-federation.md +++ b/proposals/1708-well-known-for-federation.md @@ -1,21 +1,17 @@ # MSC1708: .well-known support for server name resolution Currently, mapping from a server name to a hostname for federation is done via -`SRV` records. This presents two principal difficulties: - - * SRV records are not widely used, and administrators may be unfamiliar with - them, and there may be other practical difficulties in their deployment such - as poor support from hosting providers. [^1] - - * [MSC1711](https://github.com/matrix-org/matrix-doc/pull/1711) proposes - requiring valid X.509 certificates on the - federation endpoint. It will then be necessary for the homeserver to present - a certificate which is valid for the server name. This presents difficulties - for hosted server offerings: BigCorp may be reluctant to hand over the - keys for `bigcorp.com` to the administrators of the `bigcorp.com` matrix - homeserver. - -Here we propose to solve these problems by augmenting the current `SRV` record +`SRV` records. However, +[MSC1711](https://github.com/matrix-org/matrix-doc/pull/1711) proposes +requiring valid X.509 certificates on the federation endpoint. It will then be +necessary for the homeserver to present a certificate which is valid for the +server name. This presents difficulties for hosted server offerings: BigCorp +may want to delegate responsibility for running its Matrix homeserver to an +outside supplier, but it may be difficult for that supplier to obtain a TLS +certificate for `bigcorp.com` (and BigCorp may be reluctant to let them have +one). + +This MSC proposes to solve this problem by augmenting the current `SRV` record with a `.well-known` lookup. ## Proposal @@ -24,59 +20,80 @@ For reference, the current [specification for resolving server names](https://matrix.org/docs/spec/server_server/unstable.html#resolving-server-names) is as follows: -* If the hostname is an IP literal, then that IP address should be used, - together with the given port number, or 8448 if no port is given. +1. If the hostname is an IP literal, then that IP address should be used, + together with the given port number, or 8448 if no port is given. + +2. Otherwise, if the port is present, then an IP address is discovered by + looking up an AAAA or A record for the hostname, and the specified port is + used. + +3. If the hostname is not an IP literal and no port is given, the server is + discovered by first looking up a `_matrix._tcp` SRV record for the + hostname, which may give a hostname (to be looked up using AAAA or A queries) + and port. + +4. Finally, the server is discovered by looking up an AAAA or A record on the + hostname, and taking the default fallback port number of 8448. + +We insert the following between Steps 3 and 4: + +If the SRV record does not exist, the requesting server should make a `GET` +request to `https:///.well-known/matrix/server`, with normal +X.509 certificate validation. If the request does not return a 200, continue +to step 4, otherwise: + +XXX: should we follow redirects? -* Otherwise, if the port is present, then an IP address is discovered by - looking up an AAAA or A record for the hostname, and the specified port is - used. +The response must have a `Content-Type` of `application/json`, and must be +valid JSON which follows the structure documented below. Otherwise, the +request is aborted. -* If the hostname is not an IP literal and no port is given, the server is - discovered by first looking up a `_matrix._tcp` SRV record for the - hostname, which may give a hostname (to be looked up using AAAA or A queries) - and port. If the SRV record does not exist, then the server is discovered by - looking up an AAAA or A record on the hostname and taking the default - fallback port number of 8448. +If the response is valid, the `m.server` property is parsed as +`[:]`, and processed as follows: - Homeservers may use SRV records to load balance requests between multiple TLS - endpoints or to failover to another endpoint if an endpoint fails. + a. If `` is an IP literal, then that IP address should + be used, together with ``, or 8448 if no port is + given. The server should present a valid TLS certificate for + ``. -The first two points remain unchanged: if the server name is an IP literal, or -contains a port, then requests will be made directly as before. + b. Otherwise, if the port is present, then an IP address is discovered by + looking up an AAAA or A record for ``, and the + specified port is used. The server should present a valid TLS certificate + for ``. -If the hostname is neither an IP literal, nor does it have an explicit port, -then the requesting server should continue to make an SRV lookup as before, and -use the result if one is found. + (In other words, the federation connection is made to + `https://:`). -If *no* SRV result is found, the requesting server should make a `GET` request -to `https://\/.well-known/matrix/server`, with normal X.509 -certificate validation. If the request fails in any way, then we fall back as -before to using using port 8448 on the hostname. + c. If the hostname is not an IP literal and no port is given, a second SRV + record is looked up; this time for `_matrix._tcp.`, + which may give yet another hostname (to be looked up using A/AAAA queries) + and port. The server must present a TLS cert for the + `` from the .well-known. -Rationale: Falling back to port 8448 (rather than aborting the request) is -necessary to maintain compatibility with existing deployments, which may not -present valid certificates on port 443, or may return 4xx or 5xx errors. + d. If no SRV record is found, the server is discovered by looking up an AAAA + or A record on ``, and taking the default fallback + port number of 8448. -If the GET request succeeds, it should result in a JSON response, with contents -structured as shown: + (In other words, the federation connection is made to + `https://:8448`). + +### Structure of the `.well-known` response + +The contents of the `.well-known` response should be structured as shown: ```json { - "server": "[:]" + "m.server": "[:]" } ``` -The `server` property should be a hostname or IP address, followed by an +The `m.server` property should be a hostname or IP address, followed by an optional port. If the response cannot be parsed as JSON, or lacks a valid `server` property, the request is considered to have failed, and no fallback to port 8448 takes place. -Otherwise, the requesting server performs an `AAAA/A` lookup on the hostname -(if necessary), and connects to the resultant address and the specifed -port. The port defaults to 8448, if unspecified. - (The formal grammar for the `server` property is identical to that of a [server name](https://matrix.org/docs/spec/appendices.html#server-name).) @@ -92,18 +109,10 @@ sensible default: 24 hours is suggested. Because there is no way to request a revalidation, it is also recommended that requesting servers cap the expiry time. 48 hours is suggested. -Similarly, a failure to retrieve the `.well-known` file should be cached for -a reasonable period. 24 hours is suggested again. - -### The future of SRV records - -It's worth noting that this proposal is very clear in that we will maintain -support for SRV records for the immediate future; there are no current plans to -deprecate them. - -However, clearly a `.well-known` file can provide much of the functionality of -an SRV record, and having to support both may be undesirable. Accordingly, we -may consider sunsetting SRV record support at some point in the future. +A failure to retrieve the `.well-known` file should also be cached, though care +must be taken that a single 500 error or connection failure should not break +federation for an extended period. A short cache time of about an hour might be +appropriate; alternatively, servers might use an exponential backoff. ### Outstanding questions @@ -127,7 +136,6 @@ as soon as possible, to maximise uptake in the ecosystem. It is likely that, as we approach Matrix 1.0, there will be sufficient other new features (such as new Room versions) that upgrading will be necessary anyway. - ## Security considerations The `.well-known` file potentially broadens the attack surface for an attacker @@ -138,6 +146,3 @@ wishing to intercept federation traffic to a particular server. This proposal adds a new mechanism, alongside the existing `SRV` record lookup for finding the server responsible for a particular matrix server_name, which will allow greater flexibility in deploying homeservers. - - -[^1] For example, Cloudflare automatically "flattens" SRV record responses. From 12fc50cea785d0f071fd29c8cd2ea153a360f1de Mon Sep 17 00:00:00 2001 From: Richard van der Hoff Date: Tue, 8 Jan 2019 11:03:36 +0000 Subject: [PATCH 25/40] clarify that a whitelist is useful for cjdns too --- proposals/1711-x509-for-federation.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/proposals/1711-x509-for-federation.md b/proposals/1711-x509-for-federation.md index 43fd9657..4eda65ef 100644 --- a/proposals/1711-x509-for-federation.md +++ b/proposals/1711-x509-for-federation.md @@ -79,9 +79,8 @@ private federation using their own CA. It would also be useful for administrators to be able to disable the certificate checks for a whitelist of domains/netmasks. This would be useful -for `.onion` domains (where a certificate is hard to obtain, and where server -verification is provided at the network level), as well as for testing with IP -literals. +for testing, or for networks that provide server verification themselves, +such as like `.onion` domains on Tor or `fc00::/8` IPs on cjdns. ### Interaction with SRV records From fb171cadf48def72258433d2f19fd7d17df03c9d Mon Sep 17 00:00:00 2001 From: Richard van der Hoff Date: Tue, 8 Jan 2019 12:51:02 +0000 Subject: [PATCH 26/40] formatting fix --- proposals/1708-well-known-for-federation.md | 50 ++++++++++----------- 1 file changed, 25 insertions(+), 25 deletions(-) diff --git a/proposals/1708-well-known-for-federation.md b/proposals/1708-well-known-for-federation.md index 6e857b85..14ba3bf6 100644 --- a/proposals/1708-well-known-for-federation.md +++ b/proposals/1708-well-known-for-federation.md @@ -51,31 +51,31 @@ request is aborted. If the response is valid, the `m.server` property is parsed as `[:]`, and processed as follows: - a. If `` is an IP literal, then that IP address should - be used, together with ``, or 8448 if no port is - given. The server should present a valid TLS certificate for - ``. - - b. Otherwise, if the port is present, then an IP address is discovered by - looking up an AAAA or A record for ``, and the - specified port is used. The server should present a valid TLS certificate - for ``. - - (In other words, the federation connection is made to - `https://:`). - - c. If the hostname is not an IP literal and no port is given, a second SRV - record is looked up; this time for `_matrix._tcp.`, - which may give yet another hostname (to be looked up using A/AAAA queries) - and port. The server must present a TLS cert for the - `` from the .well-known. - - d. If no SRV record is found, the server is discovered by looking up an AAAA - or A record on ``, and taking the default fallback - port number of 8448. - - (In other words, the federation connection is made to - `https://:8448`). +a. If `` is an IP literal, then that IP address should + be used, together with ``, or 8448 if no port is + given. The server should present a valid TLS certificate for + ``. + +b. Otherwise, if the port is present, then an IP address is discovered by + looking up an AAAA or A record for ``, and the + specified port is used. The server should present a valid TLS certificate + for ``. + + (In other words, the federation connection is made to + `https://:`). + +c. If the hostname is not an IP literal and no port is given, a second SRV + record is looked up; this time for `_matrix._tcp.`, + which may give yet another hostname (to be looked up using A/AAAA queries) + and port. The server must present a TLS cert for the + `` from the .well-known. + +d. If no SRV record is found, the server is discovered by looking up an AAAA + or A record on ``, and taking the default fallback + port number of 8448. + + (In other words, the federation connection is made to + `https://:8448`). ### Structure of the `.well-known` response From f1ebbc358bd873988b2e987e32c53105a0e55293 Mon Sep 17 00:00:00 2001 From: Richard van der Hoff Date: Tue, 8 Jan 2019 12:44:22 +0000 Subject: [PATCH 27/40] document dismissed options --- proposals/1708-well-known-for-federation.md | 67 +++++++++++++++++++++ 1 file changed, 67 insertions(+) diff --git a/proposals/1708-well-known-for-federation.md b/proposals/1708-well-known-for-federation.md index 14ba3bf6..b100ef38 100644 --- a/proposals/1708-well-known-for-federation.md +++ b/proposals/1708-well-known-for-federation.md @@ -141,6 +141,73 @@ new Room versions) that upgrading will be necessary anyway. The `.well-known` file potentially broadens the attack surface for an attacker wishing to intercept federation traffic to a particular server. +## Dismissed alternatives + +For future reference, here are the alternative solutions which have been +considered and dismissed. + +### Look up the `.well-known` file before the SRV record + +We could make the request for `.well-known` before looking up the `SRV` +record. On the one hand this is maybe marginally simpler (and avoids the +overhead of having to make *two* `SRV` lookups in the case that a `.well-known` +is found. It might also open a future path for using `.well-known` for +information other than delegation. + +Ultimately we decided to include the initial `SRV` lookup so that deployments +have a mechanism to avoid the `.well-known` overhead in the common case that it +is not required. + +### Subdomain hack + +As well as accepting TLS certs for `example.com`, we could also accept them for +`delegated--matrix.example.com`. This would allow `example.com` to delegate its +matrix hosting by (a) setting up the SRV record at `_matrix._tcp.example.com` +and (b) setting up a CNAME at `delegated--matrix.example.com`. The latter would +enable the delegatee to obtain an acceptable TLS certificate. + +This was certainly an interesting idea, but we dismissed it for the following +reasons: + +* There's a security trap for anybody who lets people sign up for subdomains + (which is certainly not an uncommon business model): if you can register for + delegated--matrix.example.com, you get to intercept all the matrix traffic + for example.com. + +* Generally it feels quite unintuitive and violates the principle of least + surprise. + +* The fact that we can't find any prior art for this sets off alarm bells too. + +### Rely on DNS/DNSSEC + +If we could trust SRV records, we would be able to accept TLS certs for the +*target* of the SRV record, which avoids this whole problem. + +Such trust could come from assuming that plain DNS is "good enough". However, +DNS cache poisoning attacks are a real thing, and the fact that the designers +of TLS chose to implement a server-name check specifically to deal with this +case suggests we would be foolish to make this assumption. + +The alternative is to rely on DNSSEC to provide security for SRV records. The +problem here is simply that DNSSEC is not that widely deployed currently. A +number of large organisations are actively avoiding enabling it on their +domains, so requiring DNSSEC would be a direct impediment to the uptake of +Matrix. Furthermore, if we required DNSSEC-authenticated SRV records for +domains doing delegation, we would end up with a significant number of +homeservers unable to talk to such domains, because their local DNS +infrastructure may not implement DNSSEC. + +Finally, if we're expecting servers to present the cert for the *target* of the +SRV record, then we'll have to change the Host and SNI fields, and that will +break backwards compat everywhere (and it's hard to see how to mitigate that). + +### Stick with perspectives + +The final option is to double-down on the Perspectives approach, ie to skip +[MSC1711](https://github.com/matrix-org/matrix-doc/pull/1711). MSC1711 +discusses the reasons we do not believe this to be a viable option. + ## Conclusion This proposal adds a new mechanism, alongside the existing `SRV` record lookup From 5812450299fc88c58acf284e9f911152e2484812 Mon Sep 17 00:00:00 2001 From: Richard van der Hoff Date: Tue, 8 Jan 2019 12:50:42 +0000 Subject: [PATCH 28/40] spec that we follow redirects --- proposals/1708-well-known-for-federation.md | 18 ++++-------------- 1 file changed, 4 insertions(+), 14 deletions(-) diff --git a/proposals/1708-well-known-for-federation.md b/proposals/1708-well-known-for-federation.md index b100ef38..5981ab9f 100644 --- a/proposals/1708-well-known-for-federation.md +++ b/proposals/1708-well-known-for-federation.md @@ -35,14 +35,12 @@ is as follows: 4. Finally, the server is discovered by looking up an AAAA or A record on the hostname, and taking the default fallback port number of 8448. -We insert the following between Steps 3 and 4: +We insert the following between Steps 3 and 4. If the SRV record does not exist, the requesting server should make a `GET` -request to `https:///.well-known/matrix/server`, with normal -X.509 certificate validation. If the request does not return a 200, continue -to step 4, otherwise: - -XXX: should we follow redirects? +request to `https:///.well-known/matrix/server`, with normal X.509 +certificate validation, and following 30x redirects. If the request does not +return a 200, continue to step 4, otherwise: The response must have a `Content-Type` of `application/json`, and must be valid JSON which follows the structure documented below. Otherwise, the @@ -114,14 +112,6 @@ must be taken that a single 500 error or connection failure should not break federation for an extended period. A short cache time of about an hour might be appropriate; alternatively, servers might use an exponential backoff. -### Outstanding questions - -Should we follow 30x redirects for the .well-known file? On the one hand, there -is no obvious usecase and they add complexity (for example: how do they -interact with caches?). On the other hand, we'll presumably be using an HTTP -client library to handle some of the caching stuff, and they might be useful -for something? - ## Problems It will take a while for `.well-known` to be supported across the ecosystem; From b541c2a247d6b849031574e3151ca44427c4cdb0 Mon Sep 17 00:00:00 2001 From: Richard van der Hoff Date: Tue, 8 Jan 2019 12:54:52 +0000 Subject: [PATCH 29/40] more formatting --- proposals/1708-well-known-for-federation.md | 49 ++++++++++----------- 1 file changed, 24 insertions(+), 25 deletions(-) diff --git a/proposals/1708-well-known-for-federation.md b/proposals/1708-well-known-for-federation.md index 5981ab9f..98cfe8d8 100644 --- a/proposals/1708-well-known-for-federation.md +++ b/proposals/1708-well-known-for-federation.md @@ -49,31 +49,30 @@ request is aborted. If the response is valid, the `m.server` property is parsed as `[:]`, and processed as follows: -a. If `` is an IP literal, then that IP address should - be used, together with ``, or 8448 if no port is - given. The server should present a valid TLS certificate for - ``. - -b. Otherwise, if the port is present, then an IP address is discovered by - looking up an AAAA or A record for ``, and the - specified port is used. The server should present a valid TLS certificate - for ``. - - (In other words, the federation connection is made to - `https://:`). - -c. If the hostname is not an IP literal and no port is given, a second SRV - record is looked up; this time for `_matrix._tcp.`, - which may give yet another hostname (to be looked up using A/AAAA queries) - and port. The server must present a TLS cert for the - `` from the .well-known. - -d. If no SRV record is found, the server is discovered by looking up an AAAA - or A record on ``, and taking the default fallback - port number of 8448. - - (In other words, the federation connection is made to - `https://:8448`). +* If `` is an IP literal, then that IP address should be + used, together with ``, or 8448 if no port is given. The + server should present a valid TLS certificate for ``. + +* Otherwise, if the port is present, then an IP address is discovered by + looking up an AAAA or A record for ``, and the + specified port is used. The server should present a valid TLS certificate + for ``. + + (In other words, the federation connection is made to + `https://:`). + +* If the hostname is not an IP literal and no port is given, a second SRV + record is looked up; this time for `_matrix._tcp.`, + which may give yet another hostname (to be looked up using A/AAAA queries) + and port. The server must present a TLS cert for the + `` from the .well-known. + +* If no SRV record is found, the server is discovered by looking up an AAAA + or A record on ``, and taking the default fallback + port number of 8448. + + (In other words, the federation connection is made to + `https://:8448`). ### Structure of the `.well-known` response From 3e7a5f5ea4841e96508f6eed7e950736a714abc9 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 9 Jan 2019 00:09:38 -0700 Subject: [PATCH 30/40] Initial draft for SSO support --- api/client-server/sso_login_redirect.yaml | 46 ++++++++++ specification/client_server_api.rst | 12 ++- specification/modules/sso_login.rst | 100 ++++++++++++++++++++++ specification/targets.yaml | 1 + 4 files changed, 158 insertions(+), 1 deletion(-) create mode 100644 api/client-server/sso_login_redirect.yaml create mode 100644 specification/modules/sso_login.rst diff --git a/api/client-server/sso_login_redirect.yaml b/api/client-server/sso_login_redirect.yaml new file mode 100644 index 00000000..acbafc57 --- /dev/null +++ b/api/client-server/sso_login_redirect.yaml @@ -0,0 +1,46 @@ +# 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. +swagger: '2.0' +info: + title: "Matrix Client-Server SSO Login API" + version: "1.0.0" +host: localhost:8008 +schemes: + - https + - http +basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% +paths: + "/login/sso/redirect": + get: + summary: Redirect the user's browser to the SSO interface. + description: |- + A web-based Matrix client should instruct the user's browser to + navigate to this endpoint in order to log in via SSO. + + The server MUST respond with an HTTP redirect to the SSO interface. + operationId: redirectToSSO + parameters: + - in: query + type: string + name: redirectUrl + description: |- + URI to which the user will be redirected after the homeserver has + authenticated the user with SSO. + required: true + responses: + 302: + description: A redirect to the SSO interface. + headers: + Location: + type: "string" diff --git a/specification/client_server_api.rst b/specification/client_server_api.rst index 82a576f1..973d3b55 100644 --- a/specification/client_server_api.rst +++ b/specification/client_server_api.rst @@ -1016,9 +1016,19 @@ follows: } As with `token-based`_ interactive login, the ``token`` must encode the -user id. In the case that the token is not valid, the homeserver must respond +user ID. In the case that the token is not valid, the homeserver must respond with ``403 Forbidden`` and an error code of ``M_FORBIDDEN``. +To log in with through a Central Authentication Service (CAS) or via Single +Sign-On (SSO), clients should first make a request to ``GET /login`` to ensure +the homeserver supports the appropriate login type. Clients should use the +`CAS endpoints`_ to complete logins for ``m.login.cas`` and the `SSO endpoints`_ +for ``m.login.sso``. In either case, the client is expected to redirect the user +to the appropriate ``/redirect`` endpoint. + +.. _`CAS endpoints`: #cas-based-client-login +.. _`SSO endpoints`: #sso-based-client-login + {{login_cs_http_api}} {{logout_cs_http_api}} diff --git a/specification/modules/sso_login.rst b/specification/modules/sso_login.rst new file mode 100644 index 00000000..a493c851 --- /dev/null +++ b/specification/modules/sso_login.rst @@ -0,0 +1,100 @@ +.. 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. + +SSO-based client login +====================== + +.. _module:sso_login: + +Single Sign-On (SSO) is a generic web-based protocol for logging in users. +This section is the more generic version of `CAS-based client login`_ and +is applicable to a wider range of SSO protocols. + +An overview of the process, as used in Matrix, is as follows: + +1. The Matrix client instructs the user's browser to navigate to the + |/login/sso/redirect|_ endpoint on the user's homeserver. + +2. The homeserver responds with an HTTP redirect to the SSO user interface, + which the browser follows. + +3. The SSO system authenticates the user. + +4. The SSO server and the homeserver interact to verify the user's identity + and other authentication information, potentially using a number of redirects. + +7. The Matrix client receives the login token and passes it to the |/login|_ + API. + +Client behaviour +---------------- + +The client starts the process by instructing the browser to navigate to +|/login/sso/redirect|_ with an appropriate ``redirectUrl``. Once authentication +is successful, the browser will be redirected to that ``redirectUrl``. + +.. TODO-spec + + Should we recommend some sort of CSRF protection here (specifically, we + should guard against people accidentally logging in by sending them a link + to ``/login/sso/redirect``. + + Maybe we should recommend that the ``redirectUrl`` should contain a CSRF + token which the client should then check before sending the login token to + ``/login``? + +{{sso_login_redirect_cs_http_api}} + +Server behaviour +---------------- + +The URI for the SSO system to be used should be configured on the server by the +server administrator. The server is expected to set up any endpoints required to +interact with that SSO system. + +Handling the redirect endpoint +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +When responding to the ``/login/sso/redirect`` endpoint, the server must +generate a URI for the SSO login page with any appropriate parameters. + +.. TODO-spec: + + It might be nice if the server did some validation of the ``redirectUrl`` + parameter, so that we could check that aren't going to redirect to a non-TLS + endpoint, and to give more meaningful errors in the case of + faulty/poorly-configured clients. + +Handling the authentication endpoint +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Once the homeserver has verified the user's identity with the SSO system, it +MUST map the user ID to a valid `Matrix user identifier <../index.html#user-identifiers>`_. +The guidance in `Mapping from other character sets +<../index.html#mapping-from-other-character-sets>`_ may be useful. + +If the generated user identifier represents a new user, it should be registered +as a new user. + +Finally, the server should generate a short-term login token. The generated +token should be a macaroon, suitable for use with the ``m.login.token`` type of +the |/login|_ API, and `token-based interactive login <#token-based>`_. The +lifetime of this token SHOULD be limited to around five seconds. + + +.. |/login| replace:: ``/login`` +.. _/login: #post-matrix-client-%CLIENT_MAJOR_VERSION%-login +.. |/login/sso/redirect| replace:: ``/login/sso/redirect`` +.. _/login/sso/redirect: #get-matrix-client-%CLIENT_MAJOR_VERSION%-login-sso-redirect +.. _`CAS-based client login`: #cas-based-client-login diff --git a/specification/targets.yaml b/specification/targets.yaml index 93e1b8a6..493814ac 100644 --- a/specification/targets.yaml +++ b/specification/targets.yaml @@ -62,6 +62,7 @@ groups: # reusable blobs of files when prefixed with 'group:' - modules/admin.rst - modules/event_context.rst - modules/cas_login.rst + - modules/sso_login.rst - modules/dm.rst - modules/ignore_users.rst - modules/stickers.rst From c10394d03f9f82533c8db0a823052df6ba23453d Mon Sep 17 00:00:00 2001 From: Richard van der Hoff Date: Wed, 9 Jan 2019 11:26:14 +0000 Subject: [PATCH 31/40] Clarifications thanks to @uhoreg --- proposals/1708-well-known-for-federation.md | 23 ++++++++++----------- 1 file changed, 11 insertions(+), 12 deletions(-) diff --git a/proposals/1708-well-known-for-federation.md b/proposals/1708-well-known-for-federation.md index 98cfe8d8..8105a638 100644 --- a/proposals/1708-well-known-for-federation.md +++ b/proposals/1708-well-known-for-federation.md @@ -39,8 +39,9 @@ We insert the following between Steps 3 and 4. If the SRV record does not exist, the requesting server should make a `GET` request to `https:///.well-known/matrix/server`, with normal X.509 -certificate validation, and following 30x redirects. If the request does not -return a 200, continue to step 4, otherwise: +certificate validation, and following 30x redirects (being careful to avoid +redirect loops). If the request does not return a 200, continue to step 4, +otherwise: The response must have a `Content-Type` of `application/json`, and must be valid JSON which follows the structure documented below. Otherwise, the @@ -53,10 +54,10 @@ If the response is valid, the `m.server` property is parsed as used, together with ``, or 8448 if no port is given. The server should present a valid TLS certificate for ``. -* Otherwise, if the port is present, then an IP address is discovered by - looking up an AAAA or A record for ``, and the - specified port is used. The server should present a valid TLS certificate - for ``. +* If `` is not an IP literal, and `` is + present, then an IP address is discovered by looking up an AAAA or A record + for ``, and the specified port is used. The server + should present a valid TLS certificate for ``. (In other words, the federation connection is made to `https://:`). @@ -84,15 +85,13 @@ The contents of the `.well-known` response should be structured as shown: } ``` -The `m.server` property should be a hostname or IP address, followed by an -optional port. - -If the response cannot be parsed as JSON, or lacks a valid `server` property, +If the response cannot be parsed as JSON, or lacks a valid `m.server` property, the request is considered to have failed, and no fallback to port 8448 takes place. -(The formal grammar for the `server` property is identical to that of a [server -name](https://matrix.org/docs/spec/appendices.html#server-name).) +The formal grammar for the `m.server` property is the same as that of a [server +name](https://matrix.org/docs/spec/appendices.html#server-name): it is a +hostname or IP address, followed by an optional port. ### Caching From f738f671d1ed682bcfe2bdee1f035520016af344 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Wed, 9 Jan 2019 15:16:18 +0000 Subject: [PATCH 32/40] Sticky headers for proposals page --- scripts/css/basic.css | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/scripts/css/basic.css b/scripts/css/basic.css index dc86bc26..8d99f6da 100644 --- a/scripts/css/basic.css +++ b/scripts/css/basic.css @@ -462,6 +462,16 @@ dl.glossary dt { font-style: oblique; } +/* -- proposals page -------------------------------------------------------- */ + +#tables-of-tracked-proposals h2 { + margin-top: 7px; + padding-left: 10px; + position: -webkit-sticky; + position: sticky; + top: 0px; +} + /* -- code displays --------------------------------------------------------- */ pre { From d6c33ea0a5d5ea17cfe54a2aa4828831a5025042 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 9 Jan 2019 14:41:46 -0700 Subject: [PATCH 33/40] Make CAS a subset of SSO --- specification/client_server_api.rst | 19 ++--- specification/modules/cas_login.rst | 119 ---------------------------- specification/modules/sso_login.rst | 97 +++++++++++++++++++++-- specification/targets.yaml | 1 - 4 files changed, 102 insertions(+), 134 deletions(-) delete mode 100644 specification/modules/cas_login.rst diff --git a/specification/client_server_api.rst b/specification/client_server_api.rst index 973d3b55..03d71246 100644 --- a/specification/client_server_api.rst +++ b/specification/client_server_api.rst @@ -1019,15 +1019,16 @@ As with `token-based`_ interactive login, the ``token`` must encode the user ID. In the case that the token is not valid, the homeserver must respond with ``403 Forbidden`` and an error code of ``M_FORBIDDEN``. -To log in with through a Central Authentication Service (CAS) or via Single -Sign-On (SSO), clients should first make a request to ``GET /login`` to ensure -the homeserver supports the appropriate login type. Clients should use the -`CAS endpoints`_ to complete logins for ``m.login.cas`` and the `SSO endpoints`_ -for ``m.login.sso``. In either case, the client is expected to redirect the user -to the appropriate ``/redirect`` endpoint. - -.. _`CAS endpoints`: #cas-based-client-login -.. _`SSO endpoints`: #sso-based-client-login +If the homeserver advertises ``m.login.sso`` as a viable flow, and the client +supports it, the client should redirect the user to the ``/redirect`` endpoint +for `Single Sign-On <#sso-client-login>`_. After authentication is complete, the +client will need to submit a ``/login`` request matching ``m.login.token``. + +If the homeserver advertises ``m.login.cas`` as a viable flow, and the client +supports it, the client should redirect the user to the ``/redirect`` endpoint +for `CAS <#cas-based-client-login>`_. Just like SSO authentication, the client +is expected to submit a ``/login`` request matching ``m.login.token`` upon +successful authentication. {{login_cs_http_api}} diff --git a/specification/modules/cas_login.rst b/specification/modules/cas_login.rst deleted file mode 100644 index 5de98057..00000000 --- a/specification/modules/cas_login.rst +++ /dev/null @@ -1,119 +0,0 @@ -.. Copyright 2016 OpenMarket 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. - -CAS-based client login -====================== - -.. _module:cas_login: - -`Central Authentication Service -`_ -(CAS) is a web-based single sign-on protocol. - -An overview of the process, as used in Matrix, is as follows: - -1. The Matrix client instructs the user's browser to navigate to the - |/login/cas/redirect|_ endpoint on the user's homeserver. - -2. The homeserver responds with an HTTP redirect to the CAS user interface, - which the browser follows. - -3. The CAS system authenticates the user. - -4. The CAS server responds to the user's browser with a redirect back to the - |/login/cas/ticket|_ endpoint on the homeserver, which the browser - follows. A 'ticket' identifier is passed as a query parameter in the - redirect. - -5. The homeserver receives the ticket ID from the user's browser, and makes a - request to the CAS server to validate the ticket. - -6. Having validated the ticket, the homeserver responds to the browser with a - third HTTP redirect, back to the Matrix client application. A login token - is passed as a query parameter in the redirect. - -7. The Matrix client receives the login token and passes it to the |/login|_ - API. - -Client behaviour ----------------- - -The client starts the process by instructing the browser to navigate to -|/login/cas/redirect|_ with an appropriate ``redirectUrl``. Once authentication -is successful, the browser will be redirected to that ``redirectUrl``. - -.. TODO-spec - - Should we recommend some sort of CSRF protection here (specifically, we - should guard against people accidentally logging in by sending them a link - to ``/login/cas/redirect``. - - Maybe we should recommend that the ``redirectUrl`` should contain a CSRF - token which the client should then check before sending the login token to - ``/login``? - -{{cas_login_redirect_cs_http_api}} -{{cas_login_ticket_cs_http_api}} - -Server behaviour ----------------- - -The URI for the CAS system to be used should be configured on the server by the -server administrator. - -Handling the redirect endpoint -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -When responding to the ``/login/cas/redirect`` endpoint, the server must -generate a URI for the CAS login page. The server should take the base CAS URI -described above, and add a ``service`` query parameter. This parameter MUST be -the URI of the ``/login/cas/ticket`` endpoint, including the ``redirectUrl`` -query parameter. Because the homeserver may not know its base URI, this may -also require manual configuration. - -.. TODO-spec: - - It might be nice if the server did some validation of the ``redirectUrl`` - parameter, so that we could check that aren't going to redirect to a non-TLS - endpoint, and to give more meaningful errors in the case of - faulty/poorly-configured clients. - -Handling the authentication endpoint -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -When responding to the ``/login/cas/ticket`` endpoint, the server MUST make a -request to the CAS server to validate the provided ticket. The server MAY also -check for certain user attributes in the response. Any required attributes -should be configured by the server administrator. - -Once the ticket has been validated, the server MUST map the CAS ``user_id`` -to a valid `Matrix user identifier <../index.html#user-identifiers>`_. The -guidance in `Mapping from other character sets -<../index.html#mapping-from-other-character-sets>`_ may be useful. - -If the generated user identifier represents a new user, it should be registered -as a new user. - -Finally, the server should generate a short-term login token. The generated -token should be a macaroon, suitable for use with the ``m.login.token`` type of -the |/login|_ API, and `token-based interactive login <#token-based>`_. The -lifetime of this token SHOULD be limited to around five seconds. - - -.. |/login| replace:: ``/login`` -.. _/login: #post-matrix-client-%CLIENT_MAJOR_VERSION%-login -.. |/login/cas/redirect| replace:: ``/login/cas/redirect`` -.. _/login/cas/redirect: #get-matrix-client-%CLIENT_MAJOR_VERSION%-login-cas-redirect -.. |/login/cas/ticket| replace:: ``/login/cas/ticket`` -.. _/login/cas/ticket: #get-matrix-client-%CLIENT_MAJOR_VERSION%-login-cas-ticket diff --git a/specification/modules/sso_login.rst b/specification/modules/sso_login.rst index a493c851..977278a7 100644 --- a/specification/modules/sso_login.rst +++ b/specification/modules/sso_login.rst @@ -12,14 +12,14 @@ .. See the License for the specific language governing permissions and .. limitations under the License. -SSO-based client login -====================== +SSO client login +================ .. _module:sso_login: Single Sign-On (SSO) is a generic web-based protocol for logging in users. -This section is the more generic version of `CAS-based client login`_ and -is applicable to a wider range of SSO protocols. +As a special case, the Matrix specification supports `CAS-based login <#cas-based-client-login>`_ +as well as a subset of SSO login. An overview of the process, as used in Matrix, is as follows: @@ -93,8 +93,95 @@ the |/login|_ API, and `token-based interactive login <#token-based>`_. The lifetime of this token SHOULD be limited to around five seconds. +CAS-based client login +---------------------- + +.. _module:cas_login: + +`Central Authentication Service +`_ +(CAS) is a web-based single sign-on protocol. The protocol defined here is an +extension of the SSO protocol defined in this module: it is largely the same, +but has some specific details which make it different. + +An overview of the process, as used in Matrix, is as follows: + +1. The Matrix client instructs the user's browser to navigate to the + |/login/cas/redirect|_ endpoint on the user's homeserver. + +2. The homeserver responds with an HTTP redirect to the CAS user interface, + which the browser follows. + +3. The CAS system authenticates the user. + +4. The CAS server responds to the user's browser with a redirect back to the + |/login/cas/ticket|_ endpoint on the homeserver, which the browser + follows. A 'ticket' identifier is passed as a query parameter in the + redirect. + +5. The homeserver receives the ticket ID from the user's browser, and makes a + request to the CAS server to validate the ticket. + +6. Having validated the ticket, the homeserver responds to the browser with a + third HTTP redirect, back to the Matrix client application. A login token + is passed as a query parameter in the redirect. + +7. The Matrix client receives the login token and passes it to the |/login|_ + API. + +Client behaviour +~~~~~~~~~~~~~~~~ + +The client starts the process by instructing the browser to navigate to +|/login/cas/redirect|_ with an appropriate ``redirectUrl``. Once authentication +is successful, the browser will be redirected to that ``redirectUrl``. + +{{cas_login_redirect_cs_http_api}} +{{cas_login_ticket_cs_http_api}} + +Server behaviour +~~~~~~~~~~~~~~~~ + +The URI for the CAS system to be used should be configured on the server by the +server administrator. + +Handling the redirect endpoint +++++++++++++++++++++++++++++++ + +When responding to the ``/login/cas/redirect`` endpoint, the server must +generate a URI for the CAS login page. The server should take the base CAS URI +described above, and add a ``service`` query parameter. This parameter MUST be +the URI of the ``/login/cas/ticket`` endpoint, including the ``redirectUrl`` +query parameter. Because the homeserver may not know its base URI, this may +also require manual configuration. + +Handling the authentication endpoint +++++++++++++++++++++++++++++++++++++ + +When responding to the ``/login/cas/ticket`` endpoint, the server MUST make a +request to the CAS server to validate the provided ticket. The server MAY also +check for certain user attributes in the response. Any required attributes +should be configured by the server administrator. + +Once the ticket has been validated, the server MUST map the CAS ``user_id`` +to a valid `Matrix user identifier <../index.html#user-identifiers>`_. The +guidance in `Mapping from other character sets +<../index.html#mapping-from-other-character-sets>`_ may be useful. + +If the generated user identifier represents a new user, it should be registered +as a new user. + +Finally, the server should generate a short-term login token. The generated +token should be a macaroon, suitable for use with the ``m.login.token`` type of +the |/login|_ API, and `token-based interactive login <#token-based>`_. The +lifetime of this token SHOULD be limited to around five seconds. + + .. |/login| replace:: ``/login`` .. _/login: #post-matrix-client-%CLIENT_MAJOR_VERSION%-login +.. |/login/cas/redirect| replace:: ``/login/cas/redirect`` +.. _/login/cas/redirect: #get-matrix-client-%CLIENT_MAJOR_VERSION%-login-cas-redirect +.. |/login/cas/ticket| replace:: ``/login/cas/ticket`` +.. _/login/cas/ticket: #get-matrix-client-%CLIENT_MAJOR_VERSION%-login-cas-ticket .. |/login/sso/redirect| replace:: ``/login/sso/redirect`` .. _/login/sso/redirect: #get-matrix-client-%CLIENT_MAJOR_VERSION%-login-sso-redirect -.. _`CAS-based client login`: #cas-based-client-login diff --git a/specification/targets.yaml b/specification/targets.yaml index 493814ac..4172e617 100644 --- a/specification/targets.yaml +++ b/specification/targets.yaml @@ -61,7 +61,6 @@ groups: # reusable blobs of files when prefixed with 'group:' - modules/account_data.rst - modules/admin.rst - modules/event_context.rst - - modules/cas_login.rst - modules/sso_login.rst - modules/dm.rst - modules/ignore_users.rst From 510468a3b1736d55a4823596bc6359ed2fccb0c8 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 9 Jan 2019 15:31:04 -0700 Subject: [PATCH 34/40] Changelog --- changelogs/client_server/newsfragments/1789.feature | 1 + 1 file changed, 1 insertion(+) create mode 100644 changelogs/client_server/newsfragments/1789.feature diff --git a/changelogs/client_server/newsfragments/1789.feature b/changelogs/client_server/newsfragments/1789.feature new file mode 100644 index 00000000..97c1e5ca --- /dev/null +++ b/changelogs/client_server/newsfragments/1789.feature @@ -0,0 +1 @@ +Add a generic SSO login API. From 1ea03da9b6781102ba990e79978ce48e95e89763 Mon Sep 17 00:00:00 2001 From: Erik Johnston Date: Thu, 10 Jan 2019 12:18:22 +0000 Subject: [PATCH 35/40] Add .vscode to .gitignore --- .gitignore | 1 + 1 file changed, 1 insertion(+) diff --git a/.gitignore b/.gitignore index a850d2fa..800be2fa 100644 --- a/.gitignore +++ b/.gitignore @@ -11,3 +11,4 @@ *.pyc *.swp _rendered.rst +/.vscode/ From afa0caee93c8c21c008139babd0061a8a12f2c53 Mon Sep 17 00:00:00 2001 From: Richard van der Hoff Date: Thu, 10 Jan 2019 18:16:39 +0000 Subject: [PATCH 36/40] remove lying footnote --- proposals/1711-x509-for-federation.md | 9 +-------- 1 file changed, 1 insertion(+), 8 deletions(-) diff --git a/proposals/1711-x509-for-federation.md b/proposals/1711-x509-for-federation.md index 4eda65ef..e97b8532 100644 --- a/proposals/1711-x509-for-federation.md +++ b/proposals/1711-x509-for-federation.md @@ -175,8 +175,7 @@ certificates comes with a number of downsides. Configuring a working, federating homeserver is a process fraught with pitfalls. This proposal adds the requirement to obtain a signed certificate to that process. Even with modern intiatives such as Let's Encrypt, this is -another procedure requiring manual intervention across several moving parts[3](#f3). +another procedure requiring manual intervention across several moving parts. On the other hand: obtaining an SSL certificate should be a familiar process to anybody capable of hosting a production homeserver (indeed, they should @@ -229,9 +228,3 @@ way. [↩](#a1) [2] I've not been able to find an authoritative source on this, but most reverse-proxies will reject requests where the SNI and Host headers do not match. [↩](#a2) - -[3] Let's Encrypt will issue ACME challenges via port 80 or DNS -(for the `http-01` or `dns-01` challenge types respectively). It is unlikely -that a homeserver implementation would be able to control either port 80 or DNS -responses, so we will be unable to automate a Let's Encrypt certificate -request. [↩](#a3) From b7b96833d0ea436191be36ead1a98a353c9e0ae9 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Fri, 11 Jan 2019 16:15:06 +0000 Subject: [PATCH 37/40] Fix sticky headers so they don't hide behind header bar on desktop --- scripts/css/basic.css | 22 +++++++++++++++++----- 1 file changed, 17 insertions(+), 5 deletions(-) diff --git a/scripts/css/basic.css b/scripts/css/basic.css index 8d99f6da..fdf2980d 100644 --- a/scripts/css/basic.css +++ b/scripts/css/basic.css @@ -465,11 +465,23 @@ dl.glossary dt { /* -- proposals page -------------------------------------------------------- */ #tables-of-tracked-proposals h2 { - margin-top: 7px; - padding-left: 10px; - position: -webkit-sticky; - position: sticky; - top: 0px; + padding-left: 10px; + position: -webkit-sticky; + position: sticky; +} + +/* Move sticky headers below header bar on desktop */ +@media all and (min-width:980px) { + #tables-of-tracked-proposals h2 { + top: 52px; + } +} + +/* Sticky headers stick to the top on mobile */ +@media all and (min-width:0px) and (max-width: 980px) { + #tables-of-tracked-proposals h2 { + top: 0px; + } } /* -- code displays --------------------------------------------------------- */ From aeb524ef89f2ef6751dd0b7067c225b0c8a6a7c2 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 16 Jan 2019 16:13:53 -0700 Subject: [PATCH 38/40] Remove CAS login and reference it against r0.4.0 The SSO module should cover what CAS provides, and r0.4.0 is good as a reference for how CAS could be implemented without us repeating it here. --- api/client-server/cas_login_redirect.yaml | 54 ----------- api/client-server/cas_login_ticket.yaml | 66 ------------- specification/client_server_api.rst | 6 -- specification/modules/sso_login.rst | 110 ++++------------------ 4 files changed, 18 insertions(+), 218 deletions(-) delete mode 100644 api/client-server/cas_login_redirect.yaml delete mode 100644 api/client-server/cas_login_ticket.yaml diff --git a/api/client-server/cas_login_redirect.yaml b/api/client-server/cas_login_redirect.yaml deleted file mode 100644 index abe9069b..00000000 --- a/api/client-server/cas_login_redirect.yaml +++ /dev/null @@ -1,54 +0,0 @@ -# Copyright 2016 OpenMarket 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. -swagger: '2.0' -info: - title: "Matrix Client-Server CAS Login API" - version: "1.0.0" -host: localhost:8008 -schemes: - - https - - http -basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% -paths: - "/login/cas/redirect": - get: - summary: Redirect the user's browser to the CAS interface. - description: |- - A web-based Matrix client should instruct the user's browser to - navigate to this endpoint in order to log in via CAS. - - The server MUST respond with an HTTP redirect to the CAS interface. The - URI MUST include a ``service`` parameter giving the path of the - |/login/cas/ticket|_ endpoint (including the ``redirectUrl`` query - parameter). - - For example, if the endpoint is called with - ``redirectUrl=https://client.example.com/?q=p``, it might redirect to - ``https://cas.example.com/?service=https%3A%2F%2Fserver.example.com%2F_matrix%2Fclient%2F%CLIENT_MAJOR_VERSION%%2Flogin%2Fcas%2Fticket%3FredirectUrl%3Dhttps%253A%252F%252Fclient.example.com%252F%253Fq%253Dp``. - - operationId: redirectToCAS - parameters: - - in: query - type: string - name: redirectUrl - description: |- - URI to which the user will be redirected after the homeserver has - authenticated the user with CAS. - required: true - responses: - 302: - description: A redirect to the CAS interface. - headers: - Location: - type: "string" diff --git a/api/client-server/cas_login_ticket.yaml b/api/client-server/cas_login_ticket.yaml deleted file mode 100644 index a08565a0..00000000 --- a/api/client-server/cas_login_ticket.yaml +++ /dev/null @@ -1,66 +0,0 @@ -# Copyright 2016 OpenMarket 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. -swagger: '2.0' -info: - title: "Matrix Client-Server CAS Login API" - version: "1.0.0" -host: localhost:8008 -schemes: - - https - - http -basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% -paths: - "/login/cas/ticket": - get: - summary: Receive and validate a CAS login ticket. - description: |- - Once the CAS server has authenticated the user, it will redirect the - browser to this endpoint (assuming |/login/cas/redirect|_ gave it the - correct ``service`` parameter). - - The server MUST call ``/proxyValidate`` on the CAS server, to validate - the ticket supplied by the browser. - - If validation is successful, the server must generate a Matrix login - token. It must then respond with an HTTP redirect to the URI given in - the ``redirectUrl`` parameter, adding a ``loginToken`` query parameter - giving the generated token. - - If validation is unsuccessful, the server should respond with a ``401 - Unauthorized`` error, the body of which will be displayed to the user. - operationId: loginByCASTicket - parameters: - - in: query - type: string - name: redirectUrl - description: |- - The ``redirectUrl`` originally provided by the client to - |/login/cas/redirect|_. - required: true - - in: query - type: string - name: ticket - description: |- - CAS authentication ticket. - required: true - responses: - 302: - description: A redirect to the Matrix client. - headers: - Location: - type: "string" - x-example: |- - https://client.example.com/?q=p&loginToken=secrettoken - 401: - description: The server was unable to validate the CAS ticket. diff --git a/specification/client_server_api.rst b/specification/client_server_api.rst index 03d71246..4df83814 100644 --- a/specification/client_server_api.rst +++ b/specification/client_server_api.rst @@ -1024,12 +1024,6 @@ supports it, the client should redirect the user to the ``/redirect`` endpoint for `Single Sign-On <#sso-client-login>`_. After authentication is complete, the client will need to submit a ``/login`` request matching ``m.login.token``. -If the homeserver advertises ``m.login.cas`` as a viable flow, and the client -supports it, the client should redirect the user to the ``/redirect`` endpoint -for `CAS <#cas-based-client-login>`_. Just like SSO authentication, the client -is expected to submit a ``/login`` request matching ``m.login.token`` upon -successful authentication. - {{login_cs_http_api}} {{logout_cs_http_api}} diff --git a/specification/modules/sso_login.rst b/specification/modules/sso_login.rst index 977278a7..57188500 100644 --- a/specification/modules/sso_login.rst +++ b/specification/modules/sso_login.rst @@ -34,8 +34,17 @@ An overview of the process, as used in Matrix, is as follows: 4. The SSO server and the homeserver interact to verify the user's identity and other authentication information, potentially using a number of redirects. -7. The Matrix client receives the login token and passes it to the |/login|_ - API. +5. The browser is directed to the ``redirectUrl`` provided by the client with + a ``loginToken`` query parameter for the client to log in with. + +.. Note:: + In the older `r0.4.0 version `_ + of this specification it was possible to authenticate via CAS when the server + provides a ``m.login.cas`` login flow. This specification deprecates the use + of ``m.login.cas`` to instead prefer ``m.login.sso``, 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. Client behaviour ---------------- @@ -61,7 +70,11 @@ Server behaviour The URI for the SSO system to be used should be configured on the server by the server administrator. The server is expected to set up any endpoints required to -interact with that SSO system. +interact with that SSO system. For example, for CAS authentication the homeserver +should provide a means for the administrator to configure where the CAS server is +and the REST endpoints which consume the ticket. A good reference for how CAS could +be implemented is available in the older `r0.4.0 version `_ +of this specification. Handling the redirect endpoint ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -90,98 +103,11 @@ as a new user. Finally, the server should generate a short-term login token. The generated token should be a macaroon, suitable for use with the ``m.login.token`` type of the |/login|_ API, and `token-based interactive login <#token-based>`_. The -lifetime of this token SHOULD be limited to around five seconds. - - -CAS-based client login ----------------------- - -.. _module:cas_login: - -`Central Authentication Service -`_ -(CAS) is a web-based single sign-on protocol. The protocol defined here is an -extension of the SSO protocol defined in this module: it is largely the same, -but has some specific details which make it different. - -An overview of the process, as used in Matrix, is as follows: - -1. The Matrix client instructs the user's browser to navigate to the - |/login/cas/redirect|_ endpoint on the user's homeserver. - -2. The homeserver responds with an HTTP redirect to the CAS user interface, - which the browser follows. - -3. The CAS system authenticates the user. - -4. The CAS server responds to the user's browser with a redirect back to the - |/login/cas/ticket|_ endpoint on the homeserver, which the browser - follows. A 'ticket' identifier is passed as a query parameter in the - redirect. - -5. The homeserver receives the ticket ID from the user's browser, and makes a - request to the CAS server to validate the ticket. - -6. Having validated the ticket, the homeserver responds to the browser with a - third HTTP redirect, back to the Matrix client application. A login token - is passed as a query parameter in the redirect. - -7. The Matrix client receives the login token and passes it to the |/login|_ - API. - -Client behaviour -~~~~~~~~~~~~~~~~ - -The client starts the process by instructing the browser to navigate to -|/login/cas/redirect|_ with an appropriate ``redirectUrl``. Once authentication -is successful, the browser will be redirected to that ``redirectUrl``. - -{{cas_login_redirect_cs_http_api}} -{{cas_login_ticket_cs_http_api}} - -Server behaviour -~~~~~~~~~~~~~~~~ - -The URI for the CAS system to be used should be configured on the server by the -server administrator. - -Handling the redirect endpoint -++++++++++++++++++++++++++++++ - -When responding to the ``/login/cas/redirect`` endpoint, the server must -generate a URI for the CAS login page. The server should take the base CAS URI -described above, and add a ``service`` query parameter. This parameter MUST be -the URI of the ``/login/cas/ticket`` endpoint, including the ``redirectUrl`` -query parameter. Because the homeserver may not know its base URI, this may -also require manual configuration. - -Handling the authentication endpoint -++++++++++++++++++++++++++++++++++++ - -When responding to the ``/login/cas/ticket`` endpoint, the server MUST make a -request to the CAS server to validate the provided ticket. The server MAY also -check for certain user attributes in the response. Any required attributes -should be configured by the server administrator. - -Once the ticket has been validated, the server MUST map the CAS ``user_id`` -to a valid `Matrix user identifier <../index.html#user-identifiers>`_. The -guidance in `Mapping from other character sets -<../index.html#mapping-from-other-character-sets>`_ may be useful. - -If the generated user identifier represents a new user, it should be registered -as a new user. - -Finally, the server should generate a short-term login token. The generated -token should be a macaroon, suitable for use with the ``m.login.token`` type of -the |/login|_ API, and `token-based interactive login <#token-based>`_. The -lifetime of this token SHOULD be limited to around five seconds. +lifetime of this token SHOULD be limited to around five seconds. This token is +given to the client via the ``loginToken`` query parameter previously mentioned. .. |/login| replace:: ``/login`` .. _/login: #post-matrix-client-%CLIENT_MAJOR_VERSION%-login -.. |/login/cas/redirect| replace:: ``/login/cas/redirect`` -.. _/login/cas/redirect: #get-matrix-client-%CLIENT_MAJOR_VERSION%-login-cas-redirect -.. |/login/cas/ticket| replace:: ``/login/cas/ticket`` -.. _/login/cas/ticket: #get-matrix-client-%CLIENT_MAJOR_VERSION%-login-cas-ticket .. |/login/sso/redirect| replace:: ``/login/sso/redirect`` .. _/login/sso/redirect: #get-matrix-client-%CLIENT_MAJOR_VERSION%-login-sso-redirect From 82ee3a6035bb56240898f23a40fc83c2fd92c7e3 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Thu, 17 Jan 2019 11:18:48 -0700 Subject: [PATCH 39/40] Adjust wording for SSO introduction --- specification/modules/sso_login.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/specification/modules/sso_login.rst b/specification/modules/sso_login.rst index 57188500..6dd4a332 100644 --- a/specification/modules/sso_login.rst +++ b/specification/modules/sso_login.rst @@ -17,9 +17,9 @@ SSO client login .. _module:sso_login: -Single Sign-On (SSO) is a generic web-based protocol for logging in users. -As a special case, the Matrix specification supports `CAS-based login <#cas-based-client-login>`_ -as well as a subset of SSO login. +Single Sign-On (SSO) is a generic term which refers to protocols which allow +users to log into applications via a single web-based authentication portal. +Examples include "Central Authentication Service" (CAS) and SAML. An overview of the process, as used in Matrix, is as follows: From 5f12419afb108fab117840dfbed517165ef69049 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Thu, 17 Jan 2019 11:41:50 -0700 Subject: [PATCH 40/40] Clarify that changelog entries end with a full stop --- CONTRIBUTING.rst | 6 +++--- changelogs/client_server/newsfragments/1744.clarification | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index c592cf02..0666c579 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -76,11 +76,11 @@ Adding to the changelog Currently only changes to the client-server API need to end up in a changelog. The other APIs are not yet stable and therefore do not have a changelog. Adding to the changelog can only be done after you've opened your pull request, so be sure to do -that first. +that first. The changelog is managed by Towncrier (https://github.com/hawkowl/towncrier) in the form of "news fragments". The news fragments for the client-server API are stored -under ``changelogs/client_server/newsfragments``. +under ``changelogs/client_server/newsfragments``. To create a changelog entry, create a file named in the format ``prNumber.type`` in the ``newsfragments`` directory. The ``type`` can be one of the following: @@ -99,7 +99,7 @@ the ``newsfragments`` directory. The ``type`` can be one of the following: * ``deprecation`` - Used when deprecating something All news fragments must have a brief summary explaining the change in the contents -of the file. +of the file. The summary must end in a full stop to be in line with the style guide. Changes that do not change the spec, such as changes to the build script, formatting, CSS, etc should not get a news fragment. diff --git a/changelogs/client_server/newsfragments/1744.clarification b/changelogs/client_server/newsfragments/1744.clarification index 6ed00067..dc103920 100644 --- a/changelogs/client_server/newsfragments/1744.clarification +++ b/changelogs/client_server/newsfragments/1744.clarification @@ -1 +1 @@ -Add missing status_msg to m.presence schema +Add missing status_msg to m.presence schema.