Merge pull request #1830 from matrix-org/travis/spec/x509-wk

Specify .well-known s2s discovery and X.509 validation

api/server-server/definitions/keys.yaml

@@ -25,9 +25,9 @@ properties:
   verify_keys:
     type: object
     description: |-
-      Public keys of the homeserver for verifying digital signatures. 
-      
-      The object's key is the algorithm and version combined (``ed25519`` being the 
+      Public keys of the homeserver for verifying digital signatures.
+
+      The object's key is the algorithm and version combined (``ed25519`` being the
       algorithm and ``abc123`` being the version in the example below). Together,
       this forms the Key ID. The version must have characters matching the regular
       expression ``[a-zA-Z0-9_]``.
@@ -49,9 +49,9 @@ properties:
   old_verify_keys:
     type: object
     description: |-
-      The public keys that the server used to use and when it stopped using them. 
-      
-      The object's key is the algorithm and version combined (``ed25519`` being the 
+      The public keys that the server used to use and when it stopped using them.
+
+      The object's key is the algorithm and version combined (``ed25519`` being the
       algorithm and ``0ldK3y`` being the version in the example below). Together,
       this forms the Key ID. The version must have characters matching the regular
       expression ``[a-zA-Z0-9_]``.
@@ -90,17 +90,6 @@ properties:
       additionalProperties:
         type: string
         name: Encoded Signature Verification Key
-  tls_fingerprints:
-    type: array
-    description: Hashes of X.509 TLS certificates used by this server.
-    items:
-      type: object
-      title: TLS Fingerprint
-      properties:
-        sha256:
-          type: string
-          description: The `Unpadded Base64`_ encoded fingerprint.
-          example: "VGhpcyBpcyBoYXNoIHdoaWNoIHNob3VsZCBiZSBieXRlcw"
   valid_until_ts:
     type: integer
     format: int64

api/server-server/examples/server_key.json

@@ -16,8 +16,5 @@
             "ed25519:auto2": "VGhpcyBzaG91bGQgYWN0dWFsbHkgYmUgYSBzaWduYXR1cmU"
         }
     },
-    "tls_fingerprints": [{
-        "sha256": "VGhpcyBpcyBoYXNoIHdoaWNoIHNob3VsZCBiZSBieXRlcw"
-    }],
     "valid_until_ts": 1652262000000
-}
+}

api/server-server/wellknown.yaml

@@ -0,0 +1,53 @@
+# Copyright 2019 New Vector Ltd
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+swagger: '2.0'
+info:
+  title: "Matrix Federation Server Discovery API"
+  version: "1.0.0"
+host: localhost:443
+schemes:
+  - https
+basePath: /.well-known
+produces:
+  - application/json
+paths:
+  "/matrix/server":
+    get:
+      summary: Gets information about the delegated server for server-server communication.
+      description: |-
+        Gets information about the delegated server for server-server communication
+        between Matrix homeservers. Servers should follow 30x redirects, carefully
+        avoiding redirect loops, and use normal X.509 certificate validation.
+      responses:
+        200:
+          description:
+            The delegated server information. The ``Content-Type`` for this response SHOULD
+            be ``application/json``, however servers parsing the response should assume that
+            the body is JSON regardless of type. Failures parsing the JSON or invalid data
+            provided in the resulting parsed JSON must result in server discovery failure (no
+            attempts should be made to continue finding an IP address/port number to connect
+            to).
+          examples:
+            application/json: {
+              "m.server": "delegated.example.com:1234"
+            }
+          schema:
+            type: object
+            properties:
+              "m.server":
+                type: string
+                description: |-
+                  The server name to delegate server-server communciations to, with optional
+                  port. The delegated server name uses the same grammar as
+                  `server names in the appendices <../appendices.html#server-name>`_.