clarify federation Authorization header an add destination property (#1067)

* clarify federation Authorization header an add destination property

* add changelogs

* some clarifications

* more clarifications, fixes

* use HTML in the added-in/changed-in shortcodes

* Apply suggestions from code review

Co-authored-by: Travis Ralston <travpc@gmail.com>

changelogs/server_server/newsfragments/1067.clarification

@@ -0,0 +1 @@
+Clarify the format for the Authorization header.

changelogs/server_server/newsfragments/1067.feature

@@ -0,0 +1 @@
+Add a destination property to the Authorization header.

content/server-server-api.md

@@ -255,7 +255,7 @@ condition applies throughout the request signing process.
 Step 2 add Authorization header:
 
     GET /target HTTP/1.1
-    Authorization: X-Matrix origin=origin.hs.example.com,key="ed25519:key1",sig="ABCDEF..."
+    Authorization: X-Matrix origin="origin.hs.example.com",destination="destination.hs.example.com",key="ed25519:key1",sig="ABCDEF..."
     Content-Type: application/json
 
     <JSON-encoded request body>
@@ -283,14 +283,52 @@ def authorization_headers(origin_name, origin_signing_key,
 
     for key, sig in signed_json["signatures"][origin_name].items():
         authorization_headers.append(bytes(
-            "X-Matrix origin=%s,key=\"%s\",sig=\"%s\"" % (
+            "X-Matrix origin=\"%s\",destination=\"%s\",key=\"%s\",sig=\"%s\"" % (
-                origin_name, key, sig,
+                origin_name, destination_name, key, sig,
             )
         ))
 
-    return ("Authorization", authorization_headers)
+    return ("Authorization", authorization_headers[0])
 ```
 
+The format of the Authorization header is given in
+[RFC 7235](https://datatracker.ietf.org/doc/html/rfc7235#section-2.1). In
+summary, the header begins with authorization scheme `X-Matrix`, followed by
+one or more spaces, followed by a comma-separated list of parameters written as
+name=value pairs. The names are case insensitive and order does not matter. The
+values must be enclosed in quotes if they contain characters that are not
+allowed in `token`s, as defined in
+[RFC 7230](https://datatracker.ietf.org/doc/html/rfc7230#section-3.2.6); if a
+value is a valid `token`, it may or may not be enclosed in quotes. Quoted
+values may include backslash-escaped characters. When parsing the header, the
+recipient must unescape the characters. That is, a backslash-character pair is
+replaced by the character that follows the backslash.
+
+For compatibility with older servers, the sender should
+- only include one space after `X-Matrix`,
+- only use lower-case names, and
+- avoid using backslashes in parameter values.
+
+For compatibility with older servers, the recipient should allow colons to be
+included in values without requiring the value to be enclosed in quotes.
+
+The authorization parameters to include are:
+
+- `origin`: the server name of the sending server. This is the same as the
+  `origin` field from JSON described in step 1.
+- `destination`: {{< added-in v="1.3" >}} the server name of the receiving
+  sender. This is the same as the `destination` field from the JSON described
+  in step 1. For compatibility with older servers, recipients should accept
+  requests without this parameter, but MUST always send it. If this property
+  is included, but the value does not match the receiving server's name, the
+  receiving server must deny the request with an HTTP status code 401
+  Unauthorized.
+- `key`: the ID, including the algorithm name, of the sending server's key used
+  to sign the request.
+- `signature`: the signature of the JSON as calculated in step 1.
+
+Unknown parameters are ignored.
+
 ### Response Authentication
 
 Responses are authenticated by the TLS server certificate. A homeserver

layouts/shortcodes/added-in.html

@@ -2,7 +2,7 @@
 {{ $this := .Params.this }}
 
 {{ if $this }}
-  <span>**[New in this version]**</span>
+  <span><strong>[New in this version]</strong></span>
 {{ else }}
-  <span>**[Added in `v{{ $ver }}`]**</span>
+  <span><strong>[Added in <code>v{{ $ver }}</code>]</strong></span>
 {{ end }} {{/* Do not leave an empty line at the end of this file otherwise the inline behaviour breaks. */}}

layouts/shortcodes/changed-in.html

@@ -2,7 +2,7 @@
 {{ $this := .Params.this }}
 
 {{ if $this }}
-  <span>**[Changed in this version]**</span>
+  <span><strong>[Changed in this version]</strong></span>
 {{ else }}
-  <span>**[Changed in `v{{ $ver }}`]**</span>
+  <span><strong>[Changed in <code>v{{ $ver }}</code>]</strong></span>
 {{ end }} {{/* Do not leave an empty line at the end of this file otherwise the inline behaviour breaks. */}}