Merge pull request #1405 from turt2live/travis/s2s/keys-swagger

Convert server keys to swagger
pull/977/head
Travis Ralston 6 years ago committed by GitHub
commit a84a9a6af7
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23

@ -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

@ -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"

@ -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
}

@ -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"

@ -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"

@ -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
+++++++++

Loading…
Cancel
Save