From 30b7be875c633e724d2fc4b00ca583ecf4bae562 Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Tue, 17 May 2022 18:24:09 -0400 Subject: [PATCH 1/6] clarify federation Authorization header an add destination property --- content/server-server-api.md | 44 ++++++++++++++++++++++++++++++++---- 1 file changed, 40 insertions(+), 4 deletions(-) diff --git a/content/server-server-api.md b/content/server-server-api.md index 991806aff..33fb49522 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,50 @@ 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 +[RFC7235](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. The values must be enclosed +in quotes if they contain characters that are not allowed in `token`s, as defined in +[RFC7230](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 following the backslash. + +For compatibility with older servers, the sender should +- only include one space after `X-Matrix`, +- only use lower-case names, +- 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. +- `destination`: {{< added-in v="1.3" >}} the server name of the receiving + sender. For compatibility with older servers, recipients should accept + requests without this parameter, but should 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. The + signature must be unpadded. + +Unknown parameters are ignored. + ### Response Authentication Responses are authenticated by the TLS server certificate. A homeserver From 484e4ad9f33ba4ad5c21b527c6285f63e7d229d0 Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Tue, 17 May 2022 18:28:26 -0400 Subject: [PATCH 2/6] add changelogs --- changelogs/server_server/newsfragments/1067.clarification | 1 + changelogs/server_server/newsfragments/1067.feature | 1 + 2 files changed, 2 insertions(+) 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 000000000..ad1ca8f0f --- /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 000000000..1e88a3d9a --- /dev/null +++ b/changelogs/server_server/newsfragments/1067.feature @@ -0,0 +1 @@ +Add a destination property to the Authorization header. From d68d209d1c4b704fdd5ac57c673e7f92eefb4627 Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Wed, 18 May 2022 13:04:14 -0400 Subject: [PATCH 3/6] some clarifications --- content/server-server-api.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/content/server-server-api.md b/content/server-server-api.md index 33fb49522..fd99ba13f 100644 --- a/content/server-server-api.md +++ b/content/server-server-api.md @@ -295,13 +295,14 @@ The format of the Authorization header is given in [RFC7235](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. The values must be enclosed -in quotes if they contain characters that are not allowed in `token`s, as defined in +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 [RFC7230](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 following the backslash. +recipient must unescape the characters. That is, a backslash-character pair is +replaced by the character following the backslash. For compatibility with older servers, the sender should - only include one space after `X-Matrix`, @@ -322,8 +323,7 @@ The authorization parameters to include are: 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. The - signature must be unpadded. +- `signature`: the signature of the JSON as calculated in step 1. Unknown parameters are ignored. From ebb55de80d4610312d16abb976bc7a1bf498e803 Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Wed, 18 May 2022 14:55:28 -0400 Subject: [PATCH 4/6] more clarifications, fixes --- content/server-server-api.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/content/server-server-api.md b/content/server-server-api.md index fd99ba13f..8cf22aeaa 100644 --- a/content/server-server-api.md +++ b/content/server-server-api.md @@ -302,11 +302,11 @@ allowed in `token`s, as defined in 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 following the backslash. +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, +- only use lower-case names, and - avoid using backslashes in parameter values. For compatibility with older servers, the recipient should allow colons to be @@ -314,15 +314,17 @@ 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. +- `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. For compatibility with older servers, recipients should accept + 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 should 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 + to sign the request. - `signature`: the signature of the JSON as calculated in step 1. Unknown parameters are ignored. From 972ccbd927bc818cd45670603a82fd6999f0a184 Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Fri, 27 May 2022 18:03:55 -0400 Subject: [PATCH 5/6] use HTML in the added-in/changed-in shortcodes --- layouts/shortcodes/added-in.html | 6 +++--- layouts/shortcodes/changed-in.html | 6 +++--- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/layouts/shortcodes/added-in.html b/layouts/shortcodes/added-in.html index 4113d9227..149be6850 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 0eb35faa5..8da2559a6 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. */}} From 88e81a5eb91050c43fd85f56b8f4c2e294105a82 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 30 May 2022 15:30:30 -0600 Subject: [PATCH 6/6] Apply suggestions from code review --- content/server-server-api.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/content/server-server-api.md b/content/server-server-api.md index 8cf22aeaa..b4543b465 100644 --- a/content/server-server-api.md +++ b/content/server-server-api.md @@ -292,13 +292,13 @@ def authorization_headers(origin_name, origin_signing_key, ``` The format of the Authorization header is given in -[RFC7235](https://datatracker.ietf.org/doc/html/rfc7235#section-2.1). 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 -[RFC7230](https://datatracker.ietf.org/doc/html/rfc7230#section-3.2.6); if a +[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 @@ -319,7 +319,7 @@ The authorization parameters to include are: - `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 should always send it. If this property + 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.