mirror of
https://github.com/matrix-org/matrix-spec
synced 2026-02-17 19:43:43 +01:00
8e97b0ca81
Most of the text has been shuffled into the swagger definitions to bring it closer to where it matters. This also attempts to clarify what is out in the wild. Most importantly, the first version of the key exchange is outright removed from the specification. Other research points/questions are: * What is a "Key ID"? *1241156c82/synapse/rest/key/v2/local_key_resource.py (L81-L83)*1241156c82/synapse/rest/key/v2/local_key_resource.py (L88-L91)* Returning a cached response if the server throws a 400, 500, or otherwise not-offline status code *1241156c82/synapse/rest/key/v2/remote_key_resource.py (L227-L229)* `minimum_valid_until_ts` default * This branch of the ladder:1241156c82/synapse/rest/key/v2/remote_key_resource.py (L192)* Returning empty arrays when querying offline/no servers * Queried by hand against matrix.org as a notary server with a fake domain name to query * Returning all keys even when querying for specific keys * Queried by hand using matrix.org as a notary server against a server publishing multiple keys. The examples and descriptions were also improved as part of this commit.
129 lines
4.7 KiB
YAML
129 lines
4.7 KiB
YAML
# 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: Query for another server's keys
|
|
description: |-
|
|
Query for another server's keys. The receiving (notary) server must
|
|
sign the keys returned by the queried server.
|
|
operationId: getQueryKeys
|
|
parameters:
|
|
- in: path
|
|
name: serverName
|
|
type: string
|
|
description: The server's DNS name to query
|
|
required: true
|
|
x-example: matrix.org
|
|
- in: path
|
|
name: keyId
|
|
type: string
|
|
description: |-
|
|
The key ID to look up. If omitted or empty, all the server's keys
|
|
are to be queried for.
|
|
required: false
|
|
x-example: "ed25519:abc123"
|
|
- in: query
|
|
name: minimum_valid_until_ts
|
|
type: integer
|
|
format: int64
|
|
description: |-
|
|
A millisecond POSIX timestamp indicating when the returned certificates
|
|
will need to be valid until to be useful to the requesting server.
|
|
|
|
If not supplied, the current time as determined by the notary server is used.
|
|
required: false
|
|
x-example: 1234567890
|
|
responses:
|
|
200:
|
|
description: |-
|
|
The keys for the server, or an empty array if the server could not be reached
|
|
and no cached keys were available.
|
|
schema:
|
|
$ref: "definitions/keys_query_response.yaml"
|
|
"/query":
|
|
post:
|
|
summary: Query for several server's keys
|
|
description: |-
|
|
Query for keys from multiple servers in a batch format. The receiving (notary)
|
|
server must sign the keys returned by the queried servers.
|
|
operationId: postQueryKeys
|
|
parameters:
|
|
- in: body
|
|
name: body
|
|
schema:
|
|
type: object
|
|
example: {
|
|
"server_keys": {
|
|
"example.org": {
|
|
"ed25519:abc123": {
|
|
"minimum_valid_until_ts": 1234567890
|
|
}
|
|
}
|
|
}
|
|
}
|
|
properties:
|
|
server_keys:
|
|
type: object
|
|
description: |-
|
|
The query criteria. The outer ``string`` key on the object is the
|
|
server name (eg: ``matrix.org``). The inner ``string`` key is the
|
|
Key ID to query for the particular server. If no key IDs are given
|
|
to be queried, the notary server should query for all keys. If no
|
|
servers are given, the notary server must return an empty ``server_keys``
|
|
array in the response.
|
|
|
|
The notary server may return multiple keys regardless of the Key IDs
|
|
given.
|
|
additionalProperties:
|
|
type: object
|
|
name: ServerName
|
|
description: The server names to query.
|
|
additionalProperties:
|
|
type: object
|
|
title: Query Criteria
|
|
description: The server key IDs to query.
|
|
properties:
|
|
minimum_valid_until_ts:
|
|
type: integer
|
|
format: int64
|
|
description: |-
|
|
A millisecond POSIX timestamp indicating when the returned
|
|
certificates will need to be valid until to be useful to the
|
|
requesting server.
|
|
|
|
If not supplied, the current time as determined by the notary
|
|
server is used.
|
|
example: 1234567890
|
|
required: ['server_keys']
|
|
responses:
|
|
200:
|
|
description: |-
|
|
The keys for the queried servers, signed by the notary server. Servers which
|
|
are offline and have no cached keys will not be included in the result. This
|
|
may result in an empty array.
|
|
schema:
|
|
$ref: "definitions/keys_query_response.yaml"
|