From bd2c0b7c98612635c514567094caccda974fafba Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 11 Jul 2018 13:09:19 -0600 Subject: [PATCH 1/4] Convert server keys to swagger --- api/server-server/definitions/keys.yaml | 96 ++++++++++++++ .../definitions/keys_query_response.yaml | 27 ++++ api/server-server/examples/server_key.json | 23 ++++ api/server-server/keys.yaml | 121 ++++++++++++++++++ specification/server_server_api.rst | 34 +---- 5 files changed, 269 insertions(+), 32 deletions(-) create mode 100644 api/server-server/definitions/keys.yaml create mode 100644 api/server-server/definitions/keys_query_response.yaml create mode 100644 api/server-server/examples/server_key.json create mode 100644 api/server-server/keys.yaml diff --git a/api/server-server/definitions/keys.yaml b/api/server-server/definitions/keys.yaml new file mode 100644 index 00000000..5d1c39de --- /dev/null +++ b/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 diff --git a/api/server-server/definitions/keys_query_response.yaml b/api/server-server/definitions/keys_query_response.yaml new file mode 100644 index 00000000..8223f9ec --- /dev/null +++ b/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" diff --git a/api/server-server/examples/server_key.json b/api/server-server/examples/server_key.json new file mode 100644 index 00000000..a3934bd3 --- /dev/null +++ b/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 +} \ No newline at end of file diff --git a/api/server-server/keys.yaml b/api/server-server/keys.yaml new file mode 100644 index 00000000..e8e5167d --- /dev/null +++ b/api/server-server/keys.yaml @@ -0,0 +1,121 @@ +# 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" + "/query/{serverName}/{keyId}": + get: + summary: Retreive a server key + description: Retreive a server key + operationId: getQueryKeys + 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: Retreive a server key + description: Retreive a server key + operationId: postQueryKeys + 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 + required: true + additionalProperties: + type: object + name: ServerName + description: The server names to query + additionalProperties: + type: array + name: ServerKey + description: The server keys to query + items: + type: object + title: Query Criteria + description: The query criteria + properties: + minimum_valid_until_ts: + type: integer + format: int64 + description: Minimum Valid Until MS + required: true # TODO: Verify + x-example: 1234567890 + responses: + 200: + description: The keys for the server + schema: + $ref: "definitions/keys_query_response.yaml" diff --git a/specification/server_server_api.rst b/specification/server_server_api.rst index f2b3204a..86151991 100644 --- a/specification/server_server_api.rst +++ b/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. @@ -232,38 +233,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_ss_http_api}} Version 1 +++++++++ From 96889f16e93aed1a273d0e9ef4621ab079b64f32 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 11 Jul 2018 13:20:44 -0600 Subject: [PATCH 2/4] Split out and fix the /server and /query key APIs --- .../{keys.yaml => keys_query.yaml} | 39 ++++------------ api/server-server/keys_server.yaml | 42 +++++++++++++++++ specification/server_server_api.rst | 46 +------------------ 3 files changed, 53 insertions(+), 74 deletions(-) rename api/server-server/{keys.yaml => keys_query.yaml} (72%) create mode 100644 api/server-server/keys_server.yaml diff --git a/api/server-server/keys.yaml b/api/server-server/keys_query.yaml similarity index 72% rename from api/server-server/keys.yaml rename to api/server-server/keys_query.yaml index e8e5167d..c0811dbc 100644 --- a/api/server-server/keys.yaml +++ b/api/server-server/keys_query.yaml @@ -23,23 +23,6 @@ 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" "/query/{serverName}/{keyId}": get: summary: Retreive a server key @@ -100,20 +83,16 @@ paths: name: ServerName description: The server names to query additionalProperties: - type: array - name: ServerKey + type: object + title: Query Criteria description: The server keys to query - items: - type: object - title: Query Criteria - description: The query criteria - properties: - minimum_valid_until_ts: - type: integer - format: int64 - description: Minimum Valid Until MS - required: true # TODO: Verify - x-example: 1234567890 + properties: + minimum_valid_until_ts: + type: integer + format: int64 + description: Minimum Valid Until MS + required: true # TODO: Verify + example: 1234567890 responses: 200: description: The keys for the server diff --git a/api/server-server/keys_server.yaml b/api/server-server/keys_server.yaml new file mode 100644 index 00000000..819a2599 --- /dev/null +++ b/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" diff --git a/specification/server_server_api.rst b/specification/server_server_api.rst index 86151991..92507687 100644 --- a/specification/server_server_api.rst +++ b/specification/server_server_api.rst @@ -167,50 +167,8 @@ 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 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -233,7 +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. -{{keys_ss_http_api}} +{{keys_query_ss_http_api}} Version 1 +++++++++ From 3e13ec2841e2d8c0a67a4e4ae595734d5dc3e757 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 11 Jul 2018 13:43:15 -0600 Subject: [PATCH 3/4] Fix required properties in POST /query --- api/server-server/keys_query.yaml | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/api/server-server/keys_query.yaml b/api/server-server/keys_query.yaml index c0811dbc..1ba0f5ba 100644 --- a/api/server-server/keys_query.yaml +++ b/api/server-server/keys_query.yaml @@ -77,7 +77,6 @@ paths: server_keys: type: object description: The query criteria - required: true additionalProperties: type: object name: ServerName @@ -91,8 +90,8 @@ paths: type: integer format: int64 description: Minimum Valid Until MS - required: true # TODO: Verify example: 1234567890 + required: ['server_keys'] responses: 200: description: The keys for the server From bafdcf364011c5e8e1337b23762eea71f8256aab Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 18 Jul 2018 10:37:56 -0600 Subject: [PATCH 4/4] Full stops, spelling, and operation IDs. --- api/server-server/definitions/keys.yaml | 18 ++++++------ .../definitions/keys_query_response.yaml | 2 +- api/server-server/keys_query.yaml | 28 +++++++++---------- api/server-server/keys_server.yaml | 4 +-- 4 files changed, 26 insertions(+), 26 deletions(-) diff --git a/api/server-server/definitions/keys.yaml b/api/server-server/definitions/keys.yaml index 5d1c39de..b08f2465 100644 --- a/api/server-server/definitions/keys.yaml +++ b/api/server-server/definitions/keys.yaml @@ -19,12 +19,12 @@ example: properties: server_name: type: string - description: DNS name of the homeserver + 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 + description: Public keys of the homeserver for verifying digital signatures. required: true # TODO: Verify additionalProperties: type: object @@ -42,7 +42,7 @@ properties: 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 + description: The public keys that the server used to use and when it stopped using them. additionalProperties: type: object title: Old Verify Key @@ -56,17 +56,17 @@ properties: expired_ts: type: integer format: int64 - description: The expiration time + description: The expiration time. required: true example: 922834800000 key: type: string - description: The key + 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`` + description: Digital signatures for this object signed using the ``verify_keys``. additionalProperties: type: object title: Signed Server @@ -80,17 +80,17 @@ properties: name: Encoded Signature Verification Key tls_fingerprints: type: array - description: Hashes of X.509 TLS certificates used by this server encoded as `Unpadded Base64`_ + 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 + 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 + description: POSIX timestamp when the list of valid keys should be refreshed. example: 1052262000000 diff --git a/api/server-server/definitions/keys_query_response.yaml b/api/server-server/definitions/keys_query_response.yaml index 8223f9ec..bf2d238f 100644 --- a/api/server-server/definitions/keys_query_response.yaml +++ b/api/server-server/definitions/keys_query_response.yaml @@ -22,6 +22,6 @@ properties: server_keys: type: array title: Server Keys - description: The server keys + description: The server keys. items: $ref: "keys.yaml" diff --git a/api/server-server/keys_query.yaml b/api/server-server/keys_query.yaml index 1ba0f5ba..f41cb35b 100644 --- a/api/server-server/keys_query.yaml +++ b/api/server-server/keys_query.yaml @@ -25,27 +25,27 @@ produces: paths: "/query/{serverName}/{keyId}": get: - summary: Retreive a server key - description: Retreive a server key - operationId: getQueryKeys + summary: Retrieve a server key. + description: Retrieve a server key. + operationId: perspectivesKeyQuery parameters: - in: path name: serverName type: string - description: Server name + description: Server name. required: true x-example: matrix.org - in: path name: keyId type: string - description: Key ID + 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 + description: Minimum Valid Until Milliseconds. required: true # TODO: Verify x-example: 1234567890 responses: @@ -55,9 +55,9 @@ paths: $ref: "definitions/keys_query_response.yaml" "/query": post: - summary: Retreive a server key - description: Retreive a server key - operationId: postQueryKeys + summary: Retrieve a server key + description: Retrieve a server key. + operationId: bulkPerspectivesKeyQuery parameters: - in: body name: body @@ -76,24 +76,24 @@ paths: properties: server_keys: type: object - description: The query criteria + description: The query criteria. additionalProperties: type: object name: ServerName - description: The server names to query + description: The server names to query. additionalProperties: type: object title: Query Criteria - description: The server keys to query + description: The server keys to query. properties: minimum_valid_until_ts: type: integer format: int64 - description: Minimum Valid Until MS + description: Minimum Valid Until MS. example: 1234567890 required: ['server_keys'] responses: 200: - description: The keys for the server + description: The keys for the server. schema: $ref: "definitions/keys_query_response.yaml" diff --git a/api/server-server/keys_server.yaml b/api/server-server/keys_server.yaml index 819a2599..46beeebb 100644 --- a/api/server-server/keys_server.yaml +++ b/api/server-server/keys_server.yaml @@ -26,7 +26,7 @@ paths: "/server/{keyId}": get: summary: Get the server's key - description: Get the server's key + description: Get the server's key. operationId: getServerKey parameters: - in: path @@ -37,6 +37,6 @@ paths: x-example: TODO # No examples in the spec so far responses: 200: - description: The server's keys + description: The server's keys. schema: $ref: "definitions/keys.yaml"