Convert server keys to swagger

api/server-server/definitions/keys.yaml

@@ -0,0 +1,96 @@
+# Copyright 2018 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.
+type: object
+title: Server Keys
+description: Server keys
+example:
+  $ref: "../examples/server_key.json"
+properties:
+  server_name:
+    type: string
+    description: DNS name of the homeserver.
+    required: true # TODO: Verify
+    example: "example.org"
+  verify_keys:
+    type: object
+    description: Public keys of the homeserver for verifying digital signatures.
+    required: true # TODO: Verify
+    additionalProperties:
+      type: object
+      title: Verify Key
+      example: {
+        "ed25519:auto2": {
+          "key": "Base+64+Encoded+Signature+Verification+Key"
+        }
+      }
+      properties:
+        key:
+          type: string
+          description: The key
+          required: true
+          example: "Base+64+Encoded+Signature+Verification+Key"
+  old_verify_keys:
+    type: object
+    description: The public keys that the server used to use and when it stopped using them.
+    additionalProperties:
+      type: object
+      title: Old Verify Key
+      example: {
+        "ed25519:auto1": {
+          "expired_ts": 922834800000,
+          "key": "Base+64+Encoded+Signature+Verification+Key"
+        }
+      }
+      properties:
+        expired_ts:
+          type: integer
+          format: int64
+          description: The expiration time.
+          required: true
+          example: 922834800000
+        key:
+          type: string
+          description: The key.
+          required: true
+          example: "Base+64+Encoded+Signature+Verification+Key"
+  signatures:
+    type: object
+    description: Digital signatures for this object signed using the ``verify_keys``.
+    additionalProperties:
+      type: object
+      title: Signed Server
+      example: {
+        "example.org": {
+          "ad25519:auto2": "Base+64+Encoded+Signature+Verification+Key"
+        }
+      }
+      additionalProperties:
+        type: string
+        name: Encoded Signature Verification Key
+  tls_fingerprints:
+    type: array
+    description: Hashes of X.509 TLS certificates used by this server encoded as `Unpadded Base64`_.
+    items:
+      type: object
+      title: TLS Fingerprint
+      properties:
+        sha256:
+          type: string
+          description: The encoded fingerprint.
+          example: Base+64+Encoded+SHA-256-Fingerprint
+  valid_until_ts:
+    type: integer
+    format: int64
+    description: POSIX timestamp when the list of valid keys should be refreshed.
+    example: 1052262000000

api/server-server/definitions/keys_query_response.yaml

@@ -0,0 +1,27 @@
+# Copyright 2018 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.
+type: object
+description: Server keys
+example: {
+  "server_keys": [{
+    $ref: "../examples/server_key.json"
+  }]
+}
+properties:
+  server_keys:
+    type: array
+    title: Server Keys
+    description: The server keys.
+    items:
+      $ref: "keys.yaml"

api/server-server/examples/server_key.json

@@ -0,0 +1,23 @@
+{
+    "server_name": "example.org",
+    "verify_keys": {
+        "ed25519:auto2": {
+        "key": "Base+64+Encoded+Signature+Verification+Key"
+        }
+    },
+    "old_verify_keys": {
+        "ed25519:auto1": {
+        "expired_ts": 922834800000,
+            "key": "Base+64+Encoded+Old+Verify+Key"
+        }
+    },
+    "signatures": {
+        "example.org": {
+        "ed25519:auto2": "Base+64+Encoded+Signature"
+        }
+    },
+    "tls_fingerprints": [{
+        "sha256": "Base+64+Encoded+SHA-256-Fingerprint"
+    }],
+    "valid_until_ts": 1052262000000
+}

api/server-server/keys_query.yaml

@@ -0,0 +1,99 @@
+# Copyright 2018 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 Key Exchange API"
+  version: "1.0.0"
+host: localhost:8448
+schemes:
+  - https
+basePath: /_matrix/key/v2
+produces:
+  - application/json
+paths:
+  "/query/{serverName}/{keyId}":
+    get:
+      summary: Retrieve a server key.
+      description: Retrieve a server key.
+      operationId: perspectivesKeyQuery
+      parameters:
+        - in: path
+          name: serverName
+          type: string
+          description: Server name.
+          required: true
+          x-example: matrix.org
+        - in: path
+          name: keyId
+          type: string
+          description: Key ID.
+          required: true
+          x-example: TODO # No examples in spec so far
+        - in: query
+          name: minimum_valid_until_ts
+          type: integer
+          format: int64
+          description: Minimum Valid Until Milliseconds.
+          required: true # TODO: Verify 
+          x-example: 1234567890
+      responses:
+        200:
+          description: The keys for the server
+          schema:
+            $ref: "definitions/keys_query_response.yaml"
+  "/query":
+    post:
+      summary: Retrieve a server key
+      description: Retrieve a server key.
+      operationId: bulkPerspectivesKeyQuery
+      parameters:
+        - in: body
+          name: body
+          schema:
+            type: object
+            # TODO: Improve example
+            example: {
+              "server_keys": {
+                "{server_name}": {
+                  "{key_id}": {
+                    "minimum_valid_until_ts": 1234567890
+                  }
+                }
+              }
+            }
+            properties:
+              server_keys:
+                type: object
+                description: The query criteria.
+                additionalProperties:
+                  type: object
+                  name: ServerName
+                  description: The server names to query.
+                  additionalProperties:
+                    type: object
+                    title: Query Criteria
+                    description: The server keys to query.
+                    properties:
+                      minimum_valid_until_ts:
+                        type: integer
+                        format: int64
+                        description: Minimum Valid Until MS.
+                        example: 1234567890
+            required: ['server_keys']
+      responses:
+        200:
+          description: The keys for the server.
+          schema:
+            $ref: "definitions/keys_query_response.yaml"

api/server-server/keys_server.yaml

@@ -0,0 +1,42 @@
+# Copyright 2018 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 Key Exchange API"
+  version: "1.0.0"
+host: localhost:8448
+schemes:
+  - https
+basePath: /_matrix/key/v2
+produces:
+  - application/json
+paths:
+  "/server/{keyId}":
+    get:
+      summary: Get the server's key
+      description: Get the server's key.
+      operationId: getServerKey
+      parameters:
+        - in: path
+          name: keyId
+          type: string
+          description: Key ID
+          required: false
+          x-example: TODO # No examples in the spec so far
+      responses:
+        200:
+          description: The server's keys.
+          schema:
+            $ref: "definitions/keys.yaml"

specification/server_server_api.rst

@@ -1,5 +1,6 @@
 .. Copyright 2016 OpenMarket Ltd
 .. Copyright 2017 New Vector Ltd
+.. Copyright 2018 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.
@@ -166,51 +167,9 @@ If a server goes offline intermediate notary servers should continue to return
 the last response they received from that server so that the signatures of old
 events sent by that server can still be checked.
 
-==================== =================== ======================================
- Key                  Type                Description
-==================== =================== ======================================
-``server_name``      String              DNS name of the homeserver.
-``verify_keys``      Object              Public keys of the homeserver for
-                                         verifying digital signatures.
-``old_verify_keys``  Object              The public keys that the server used
-                                         to use and when it stopped using them.
-``signatures``       Object              Digital signatures for this object
-                                         signed using the ``verify_keys``.
-``tls_fingerprints`` Array of Objects    Hashes of X.509 TLS certificates used
-                                         by this server encoded as `Unpadded Base64`_.
-``valid_until_ts``   Integer             POSIX timestamp when the list of valid
-                                         keys should be refreshed.
-==================== =================== ======================================
+{{keys_server_ss_http_api}}
 
 
-.. code:: json
-
-    {
-        "old_verify_keys": {
-            "ed25519:auto1": {
-                "expired_ts": 922834800000,
-                "key": "Base+64+Encoded+Old+Verify+Key"
-            }
-        },
-        "server_name": "example.org",
-        "signatures": {
-            "example.org": {
-                "ed25519:auto2": "Base+64+Encoded+Signature"
-            }
-        },
-        "tls_fingerprints": [
-            {
-                "sha256": "Base+64+Encoded+SHA-256-Fingerprint"
-            }
-        ],
-        "valid_until_ts": 1052262000000,
-        "verify_keys": {
-            "ed25519:auto2": {
-                "key": "Base+64+Encoded+Signature+Verification+Key"
-            }
-        }
-    }
-
 Querying Keys Through Another Server
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -232,38 +191,7 @@ This API can return keys for servers that are offline by using cached responses
 taken from when the server was online. Keys can be queried from multiple
 servers to mitigate against DNS spoofing.
 
-Example request:
-
-.. code::
-
-    GET /_matrix/key/v2/query/{server_name}/{key_id}/?minimum_valid_until_ts={minimum_valid_until_ts} HTTP/1.1
-
-    POST /_matrix/key/v2/query HTTP/1.1
-    Content-Type: application/json
-
-    {
-        "server_keys": {
-            "{server_name}": {
-                "{key_id}": {
-                    "minimum_valid_until_ts": {posix_timestamp}
-                }
-            }
-        }
-    }
-
-
-Response:
-
-.. code::
-
-    HTTP/1.1 200 OK
-    Content-Type: application/json
-    {
-        "server_keys": [
-           # List of responses with same format as /_matrix/key/v2/server
-           # signed by both the originating server and this server.
-        ]
-    }
+{{keys_query_ss_http_api}}
 
 Version 1
 +++++++++