From 268613a0160a7f94ddbbb6ad63e87f9d2f932a97 Mon Sep 17 00:00:00 2001 From: Stefan Matting Date: Fri, 13 Jan 2023 14:09:15 +0100 Subject: [PATCH 1/4] fix small mistakes --- docs/src/how-to/install/configure-federation.md | 4 ++-- docs/src/understand/federation/architecture.md | 13 ++++++------- 2 files changed, 8 insertions(+), 9 deletions(-) diff --git a/docs/src/how-to/install/configure-federation.md b/docs/src/how-to/install/configure-federation.md index c7e46849bc..0652c9e263 100644 --- a/docs/src/how-to/install/configure-federation.md +++ b/docs/src/how-to/install/configure-federation.md @@ -14,7 +14,7 @@ detailed in the sections below: - Choose a backend domain name -- DNS setup for federation (including a `SRV` record) +- DNS setup for federation (including an `SRV` record) - Generate and configure TLS certificates: @@ -31,7 +31,7 @@ detailed in the sections below: ## Choose a Backend Domain As of the release \[helm chart 0.129.0, Wire docker version 2.94.0\] from -2020-12-15, the `federationDomain` is a mandatory configuration setting, which +2020-12-15, `federationDomain` is a mandatory configuration setting, which defines the {ref}`backend domain ` of your installation. Regardless of whether you want to enable federation for a backend or not, you must decide what its domain is going to be. This helps in keeping diff --git a/docs/src/understand/federation/architecture.md b/docs/src/understand/federation/architecture.md index 392806ac91..6bf64bb17a 100644 --- a/docs/src/understand/federation/architecture.md +++ b/docs/src/understand/federation/architecture.md @@ -6,19 +6,18 @@ ## Backends In the following we call a **backend** the set of servers, databases and DNS -configurations that together form one single Wire Server entity as seen from +configurations that together form one single Wire Server entity as seen from the outside. It can also be called a Wire \"instance\" or \"server\" or \"Wire installation\". Every resource (e.g. users, conversations, assets and teams) exists and is *owned* by a single backend, which we can refer to as that resource\'s backend. The communication between federated backends is facilitated by two components in -each backend: {ref}`federation_ingress` and {ref}`federator`. The -*Federation Ingress* is, as the name suggests the -ingress point for incoming connections from other backends, which are then -forwarded to the *Federator*. The *Federator* forwards requests -to internal components. It also acts as a *egress* point for requests from -internal backend components to other, remote backends. +each backend: {ref}`federation_ingress` and {ref}`federator`. The *Federation +Ingress* is, as the name suggests, the ingress point for incoming connections +from other backends, which are then forwarded to the *Federator*. The +*Federator* forwards requests to internal components. It also acts as a *egress* +point for requests from internal backend components to other, remote backends. ![image](img/federated-backend-architecture.png) From 0f88dd454017e7a7c9914db073e185a224afece1 Mon Sep 17 00:00:00 2001 From: Stefan Matting Date: Fri, 13 Jan 2023 14:11:31 +0100 Subject: [PATCH 2/4] infra domain -> infrastructure domain --- .../how-to/install/configure-federation.md | 10 +++--- docs/src/understand/federation/api.md | 4 +-- .../src/understand/federation/architecture.md | 10 +++--- .../federation/backend-communication.md | 35 +++++++++---------- 4 files changed, 29 insertions(+), 30 deletions(-) diff --git a/docs/src/how-to/install/configure-federation.md b/docs/src/how-to/install/configure-federation.md index 0652c9e263..69396c92b5 100644 --- a/docs/src/how-to/install/configure-federation.md +++ b/docs/src/how-to/install/configure-federation.md @@ -118,7 +118,7 @@ The fields of the SRV record need to be populated as follows - `weight`: \>0 for your server to be reachable. A good default value could be 10 - `port`: `443` -- `target`: the infra domain +- `target`: the infrastructure domain To give an example, assuming @@ -237,7 +237,7 @@ trust when interacting with other backends. ### (B) Manual server and client certificates Use your usual method of obtaining X.509 certificates for your {ref}`federation -infra domain ` (alongside the other domains needed for a +infrastructure domain ` (alongside the other domains needed for a wire-server installation). You can use one single certificate and key for both server and client @@ -266,7 +266,7 @@ X509v3 extensions: TLS Web Server Authentication, TLS Web Client Authentication ``` -And your {ref}`federation infra domain ` (e.g. +And your {ref}`federation infrastructure domain ` (e.g. `federator.wire.example.com` from the running example) needs to either figure explictly in the list of your SAN (Subject Alternative Name): @@ -304,7 +304,7 @@ The *server certificate* and *private key* need to be configured in just the federator component. If you have installed wire-server before without federation, server certificates may already be configured *(though you probably need to create new certificates to include the -federation infra domain if you\'re not making use of wildcard +federation infrastructure domain if you\'re not making use of wildcard certificates)*. Server certificates go here: ``` yaml @@ -515,7 +515,7 @@ Ensure that the IP matches where your backend ingress runs. Refer to {ref}`how-to-see-tls-certs` and set DOMAIN to your -{ref}`federation infra domain `. They should include your domain as part of the SAN (Subject +{ref}`federation infrastructure domain `. They should include your domain as part of the SAN (Subject Alternative Names) and not have expired. ### Manually test that federation works diff --git a/docs/src/understand/federation/api.md b/docs/src/understand/federation/api.md index 2a8325606c..e48e642294 100644 --- a/docs/src/understand/federation/api.md +++ b/docs/src/understand/federation/api.md @@ -231,9 +231,9 @@ their precise inputs and outputs. In the following the interactions between *Federator* and *Federation Ingress* components of the backends involved are omitted for simplicity. Also the backend -domain and infra domain are assumed the same. +domain and infrastructure domain are assumed the same. -Additionally we assume that the backend domain and the infra domain of +Additionally we assume that the backend domain and the infrastructure domain of the respective backends involved are the same and each domain identifies a distinct backend. diff --git a/docs/src/understand/federation/architecture.md b/docs/src/understand/federation/architecture.md index 6bf64bb17a..6bb1e782bc 100644 --- a/docs/src/understand/federation/architecture.md +++ b/docs/src/understand/federation/architecture.md @@ -31,7 +31,7 @@ point for requests from internal backend components to other, remote backends. Each backend has two domain: an {ref}`infrastructure domain ` and a {ref}`backend domain `. -The **infrastructure domain** (short **infra domain**) is the domain name under which the backend +The **infrastructure domain** is the domain name under which the backend is actually reachable via the network. It is also the domain name that each backend uses in authenticating itself to other backends. @@ -41,7 +41,7 @@ context of federation. The distinction between the two domains allows the owner of a backend domain, e.g. `example.com`, to host their Wire backend under a -different infra domain, e.g. `wire.infra.example.com`. +different infrastructure domain, e.g. `wire.infra.example.com`. (federation_ingress)= @@ -52,7 +52,7 @@ ingress](https://kubernetes.io/docs/concepts/services-networking/ingress/) and uses [nginx](https://nginx.org/en/) as its underlying software. It is configured with a set of X.509 certificates, which acts as root of -trust for the authentication of the infra domain of remote backends, as +trust for the authentication of the infrastructure domain of remote backends, as well as with a certificate, which it uses to authenticate itself toward other backends. @@ -73,7 +73,7 @@ point for other backend components. It can be configured to use an {ref}`allow list ` to authorize incoming and outgoing connections, and it keeps an X.509 client certificate for the -backend\'s infra domain to authenticate itself towards other backends. +backend\'s infrastructure domain to authenticate itself towards other backends. Additionally, it requires a connection to a DNS resolver to {ref}`discover` other backends. @@ -96,7 +96,7 @@ from remote backends (forwarded via the local 1. Discover the mapping between backend domain claimed by the remote backend and its infra domain, -2. Verify that the discovered infra domain matches the domain in the +2. Verify that the discovered infrastructure domain matches the domain in the remote backend\'s client certificate, 3. If enabled, ensure that the backend domain of the other backend is in the allow list. diff --git a/docs/src/understand/federation/backend-communication.md b/docs/src/understand/federation/backend-communication.md index 7fa3e71cb9..1f91e14645 100644 --- a/docs/src/understand/federation/backend-communication.md +++ b/docs/src/understand/federation/backend-communication.md @@ -9,7 +9,7 @@ need to ensure the following: - **Authentication** - Determine the identity (infra domain name) of the other backend. + Determine the identity (infrastructure domain name) of the other backend. - **Discovery** @@ -36,7 +36,7 @@ Conversely, every *Federator* needs to be provisioned with a client certificate which it uses to authenticate itself towards other backends. Note that the client certificate is required to be issued with the backend\'s -infra domain as one of the subject alternative names (SAN), which is defined in +infrastructure domain as one of the subject alternative names (SAN), which is defined in [RFC 5280](https://tools.ietf.org/html/rfc5280). See {ref}`federation-certificate-setup` for technical instructions. @@ -48,7 +48,7 @@ with an `AuthenticationFailure` error. ## Discovery -The discovery process allows a backend to determine the infra domain of +The discovery process allows a backend to determine the infrastructure domain of a given backend domain. This step is necessary in two scenarios: @@ -59,18 +59,17 @@ This step is necessary in two scenarios: {ref}`qualified username `, which only includes that user\'s backend\'s backend domain. - When receiving a message from another backend that authenticates - with a given infra domain and claims to represent a given backend + with a given infrastructure domain and claims to represent a given backend domain, a backend would like to ensure the backend domain owner - authorized the owner of the infra domain to run their Wire backend. + authorized the owner of the infrastructure domain to run their Wire backend. To make discovery possible, any party hosting a Wire backend has to -announce the infra domain via a DNS *SRV* record as defined in [RFC +announce the infrastructure domain via a DNS *SRV* record as defined in [RFC 2782](https://tools.ietf.org/html/rfc2782) with `service = wire-server-federator, proto = tcp` and with `name` pointing -to the backend\'s domain and *target* to the backend\'s infra domain. +to the backend\'s domain and *target* to the backend\'s infrastructure domain. -For example, Company A with backend domain *company-a.com* and infra -domain *wire.company-a.com* could publish +For example, Company A with backend domain *company-a.com* and infrastructure domain *wire.company-a.com* could publish ``` bash _wire-server-federator._tcp.company-a.com. 600 IN SRV 10 5 443 federator.wire.company-a.com. @@ -86,7 +85,7 @@ In case this process fails the Federator fails to forward the request with a `Di ### DNS Scope The network scope of the SRV record (as well as that of the DNS records -for backend and infra domain), depends on the desired federation +for backend and infrastructure domain), depends on the desired federation topology in the same way as other parameters such as the availability of the CA certificate that allows authentication of the *Federation Ingress*\' server certificate or the *Federator*\'s client certificate. @@ -99,18 +98,18 @@ strongly depends on the network architecture of the backends involved. ### SRV TTL and Caching After retrieving the SRV record for a given domain, the local backend -caches the *backend domain \<\--\> infra domain* mapping for the +caches the *backend domain \<\--\> infrastructure domain* mapping for the duration indicated in the TTL field of the record. Due to this caching behavior, the TTL value of the SRV record dictates at which intervals remote backends will refresh their mapping of the -local backend\'s backend domain to infra domain. As a consequence a +local backend\'s backend domain to infrastructure domain. As a consequence a value in the order of magnitude of 24 hours will reduce the amount of overhead for remote backends. -On the other hand in the setup phase of a backend, or when a change of infra +On the other hand in the setup phase of a backend, or when a change of infrastructure domain is required, a TTL value in the magnitude of a few minutes allows remote -backends to recover more quickly from a change of the infra domain. +backends to recover more quickly from a change of the infrastructure domain. (authorization)= @@ -122,10 +121,10 @@ After an incoming connection is authenticated the backend authorizes the request. It does so by verifying that the backend domain of the sender is contained in the {ref}`domain allow list `. -Since the request is authenticated only by the infra domain the sending backend +Since the request is authenticated only by the infrastructure domain the sending backend is required to add its backend domain as a `Wire-Origin-Domain` header to the request. The receiving backend follows the process described in {ref}`discovery` -and verifies that the discovered infra domain for the backend domain indicated +and verifies that the discovered infrastructure domain for the backend domain indicated in the `Wire-Origin-Domain` header is one of the Subject Alternative Names contained in the client certificate used to sign the request. If this is not the case, the receiving backend fails the request with a `ValidationError`. @@ -150,8 +149,8 @@ details. ## Example The following is an example for the message and information flow between -a backend with backend domain `a.com` and infra domain `infra.a.com` and -another backend with backend domain `b.com` and infra domain +a backend with backend domain `a.com` and infrastructure domain `infra.a.com` and +another backend with backend domain `b.com` and infrastructure domain `infra.b.com`. The content and format of the message is meant to be representative. For From ab46188a9fb3ce2dd413cdd07c7cd22305e0dc7f Mon Sep 17 00:00:00 2001 From: Stefan Matting Date: Fri, 13 Jan 2023 14:15:45 +0100 Subject: [PATCH 3/4] apply fix "only includes the backend domain..." --- docs/src/understand/federation/backend-communication.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/src/understand/federation/backend-communication.md b/docs/src/understand/federation/backend-communication.md index 1f91e14645..81169ddb6b 100644 --- a/docs/src/understand/federation/backend-communication.md +++ b/docs/src/understand/federation/backend-communication.md @@ -56,8 +56,7 @@ This step is necessary in two scenarios: - A backend would like to establish a connection to another backend that it only knows the backend domain of. This is the case, for example, when a user of a local backend searches for a - {ref}`qualified username `, which only includes that user\'s backend\'s backend - domain. + {ref}`qualified username `, which only includes the backend domain of that user's backend. - When receiving a message from another backend that authenticates with a given infrastructure domain and claims to represent a given backend domain, a backend would like to ensure the backend domain owner From a89b816a7d471feb1cceac830942ce1c71c4e275 Mon Sep 17 00:00:00 2001 From: Stefan Matting Date: Fri, 13 Jan 2023 14:17:04 +0100 Subject: [PATCH 4/4] Remove "DNS Scope" section --- .../src/understand/federation/backend-communication.md | 10 ---------- 1 file changed, 10 deletions(-) diff --git a/docs/src/understand/federation/backend-communication.md b/docs/src/understand/federation/backend-communication.md index 81169ddb6b..a71c6e158b 100644 --- a/docs/src/understand/federation/backend-communication.md +++ b/docs/src/understand/federation/backend-communication.md @@ -81,16 +81,6 @@ In case this process fails the Federator fails to forward the request with a `Di (dns-scope)= -### DNS Scope - -The network scope of the SRV record (as well as that of the DNS records -for backend and infrastructure domain), depends on the desired federation -topology in the same way as other parameters such as the availability of -the CA certificate that allows authentication of the *Federation -Ingress*\' server certificate or the *Federator*\'s client certificate. -The general rule is that the SRV entry should be \"visible\" from the -point of view of the desired federation partners. The exact scope -strongly depends on the network architecture of the backends involved. (srv-ttl-and-caching)=