add documentation and changelogs

changelog.d/0-release-notes/WPB-227

@@ -0,0 +1,35 @@
+There is a new optional Boolean option, `multiSFT.enabled`, in `brig.yaml`,
+allowing calls between federated SFT servers. If provided, the field
+`is_federating` in the response of `/calls/config/authenticated` will reflect
+`multiSFT.enabled`'s value.
+
+Example:
+
+```
+# [brig.yaml]
+multiSFT:
+  enabled: true
+```
+
+Also, the optional object `sftToken` with its fields `ttl`, `secret`, and
+`secondsBeforeNew` define whether an SFT credential would be rendered in the
+response of `/calls/config/authenticated`. The field `ttl` determines the
+seconds for the credential to be valid, `secondsBeforeNew` determines the amount
+of time which has to pass before a new token will be generated, preventing one
+client to create too many new credentials, and `secret` is the path to the
+secret shared with SFT to create credentials.
+
+Example:
+
+```
+# [brig.yaml]
+sft:
+  sftBaseDomain: sft.wire.example.com
+  sftSRVServiceName: sft
+  sftDiscoveryIntervalSeconds: 10
+  sftListLength: 20
+  sftToken:
+    ttl: 120
+    secret: /path/to/secret
+    secondsBeforeNew: 60
+```

changelog.d/1-api-changes/WPB-227

@@ -0,0 +1,12 @@
+The new endpoint `/calls/config/authenticated` returns the same data as
+`/calls/config/v2` and in addition features a new optional field `is_federating`
+which reflects whether SFT federation is enabled or not. Also, the new optional
+fields `username` and `credential` in the `sft_servers_all` object of the
+endpoint's response provide the SFT credential which the authenticated client
+should use for connecting to SFT. The credential will only be generated if a
+secret shared between SFT and Brig has been configured for Brig. Repeated calls
+to the endpoint will not lead to newly issued SFT credentials until a configured
+timespan has been elapsed. During this timespan, the already provided SFT
+credential will be replayed in the endpoint's response. For this to work,
+clients have to send the `Z-Client` header in their requests to this new
+endpoint.

docs/src/developer/reference/config-options.md

@@ -517,6 +517,31 @@ This setting assumes that the sft load balancer has been deployed with the `sftd
 
 Additionally if `setSftListAllServers` is set to `enabled` (disabled by default) then the `/calls/config/v2` endpoint will include a list of all servers that are load balanced by `setSftStaticUrl` at field `sft_servers_all`. This is required to enable calls between federated instances of Wire.
 
+Calls between federated SFT servers can be enabled using the optional boolean `multiSFT.enabled`. If provided, the field `is_federating` in the response of `/calls/config/authenticated` will reflect `multiSFT.enabled`'s value.
+
+```
+# [brig.yaml]
+multiSFT:
+  enabled: true
+```
+
+Also, the optional object `sftToken` with its fields `ttl`, `secret`, and `secondsBeforeNew` define whether an SFT credential would be rendered in the response of `/calls/config/authenticated`. The field `ttl` determines the seconds for the credential to be valid, `secondsBeforeNew` determines the amount of time which has to pass before a new token will be generated, preventing one client to create too many new credentials, and `secret` is the path to the secret shared with SFT to create credentials.
+
+Example:
+
+```
+# [brig.yaml]
+sft:
+  sftBaseDomain: sft.wire.example.com
+  sftSRVServiceName: sft
+  sftDiscoveryIntervalSeconds: 10
+  sftListLength: 20
+  sftToken:
+    ttl: 120
+    secret: /path/to/secret
+    secondsBeforeNew: 60
+```
+
 ### Locale