From 278005519826d6fa9390470c6dda2e2ea8db23eb Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Mon, 30 May 2022 17:33:56 -0400 Subject: [PATCH] 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 --- .../newsfragments/1067.clarification | 1 + .../server_server/newsfragments/1067.feature | 1 + content/server-server-api.md | 46 +++++++++++++++++-- layouts/shortcodes/added-in.html | 6 +-- layouts/shortcodes/changed-in.html | 6 +-- 5 files changed, 50 insertions(+), 10 deletions(-) create mode 100644 changelogs/server_server/newsfragments/1067.clarification create mode 100644 changelogs/server_server/newsfragments/1067.feature diff --git a/changelogs/server_server/newsfragments/1067.clarification b/changelogs/server_server/newsfragments/1067.clarification new file mode 100644 index 00000000..ad1ca8f0 --- /dev/null +++ b/changelogs/server_server/newsfragments/1067.clarification @@ -0,0 +1 @@ +Clarify the format for the Authorization header. diff --git a/changelogs/server_server/newsfragments/1067.feature b/changelogs/server_server/newsfragments/1067.feature new file mode 100644 index 00000000..1e88a3d9 --- /dev/null +++ b/changelogs/server_server/newsfragments/1067.feature @@ -0,0 +1 @@ +Add a destination property to the Authorization header. diff --git a/content/server-server-api.md b/content/server-server-api.md index 24b6a889..f70e8994 100644 --- a/content/server-server-api.md +++ b/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 @@ -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\"" % ( - origin_name, key, sig, + "X-Matrix origin=\"%s\",destination=\"%s\",key=\"%s\",sig=\"%s\"" % ( + 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 diff --git a/layouts/shortcodes/added-in.html b/layouts/shortcodes/added-in.html index 4113d922..149be685 100644 --- a/layouts/shortcodes/added-in.html +++ b/layouts/shortcodes/added-in.html @@ -2,7 +2,7 @@ {{ $this := .Params.this }} {{ if $this }} - **[New in this version]** + [New in this version] {{ else }} - **[Added in `v{{ $ver }}`]** -{{ end }} {{/* Do not leave an empty line at the end of this file otherwise the inline behaviour breaks. */}} \ No newline at end of file + [Added in v{{ $ver }}] +{{ end }} {{/* Do not leave an empty line at the end of this file otherwise the inline behaviour breaks. */}} diff --git a/layouts/shortcodes/changed-in.html b/layouts/shortcodes/changed-in.html index 0eb35faa..8da2559a 100644 --- a/layouts/shortcodes/changed-in.html +++ b/layouts/shortcodes/changed-in.html @@ -2,7 +2,7 @@ {{ $this := .Params.this }} {{ if $this }} - **[Changed in this version]** + [Changed in this version] {{ else }} - **[Changed in `v{{ $ver }}`]** -{{ end }} {{/* Do not leave an empty line at the end of this file otherwise the inline behaviour breaks. */}} \ No newline at end of file + [Changed in v{{ $ver }}] +{{ end }} {{/* Do not leave an empty line at the end of this file otherwise the inline behaviour breaks. */}}