mirror of
https://github.com/matrix-org/matrix-spec
synced 2025-12-24 09:58:38 +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.
109 lines
3.6 KiB
YAML
109 lines
3.6 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.
|
|
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
|
|
example: "example.org"
|
|
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
|
|
algorithm and ``abc123`` being the version in the example below). Together,
|
|
this forms the Key ID.
|
|
required: true
|
|
additionalProperties:
|
|
type: object
|
|
title: Verify Key
|
|
example: {
|
|
"ed25519:abc123": {
|
|
"key": "VGhpcyBzaG91bGQgYmUgYSByZWFsIGVkMjU1MTkgcGF5bG9hZA=="
|
|
}
|
|
}
|
|
properties:
|
|
key:
|
|
type: string
|
|
description: The `Unpadded Base64`_ encoded key.
|
|
required: true
|
|
example: "VGhpcyBzaG91bGQgYmUgYSByZWFsIGVkMjU1MTkgcGF5bG9hZA=="
|
|
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
|
|
algorithm and ``0ldK3y`` being the version in the example below). Together,
|
|
this forms the Key ID.
|
|
additionalProperties:
|
|
type: object
|
|
title: Old Verify Key
|
|
example: {
|
|
"ed25519:0ldK3y": {
|
|
"expired_ts": 922834800000,
|
|
"key": "VGhpcyBzaG91bGQgYmUgeW91ciBvbGQga2V5J3MgZWQyNTUxOSBwYXlsb2FkLg=="
|
|
}
|
|
}
|
|
properties:
|
|
expired_ts:
|
|
type: integer
|
|
format: int64
|
|
description: POSIX timestamp for when this key expired.
|
|
required: true
|
|
example: 922834800000
|
|
key:
|
|
type: string
|
|
description: The `Unpadded Base64`_ encoded key.
|
|
required: true
|
|
example: "VGhpcyBzaG91bGQgYmUgeW91ciBvbGQga2V5J3MgZWQyNTUxOSBwYXlsb2FkLg=="
|
|
signatures:
|
|
type: object
|
|
description: Digital signatures for this object signed using the ``verify_keys``.
|
|
additionalProperties:
|
|
type: object
|
|
title: Signed Server
|
|
example: {
|
|
"example.org": {
|
|
"ad25519:abc123": "VGhpcyBzaG91bGQgYWN0dWFsbHkgYmUgYSBzaWduYXR1cmU="
|
|
}
|
|
}
|
|
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 `Unpadded Base64`_ encoded fingerprint
|
|
example: "VGhpcyBpcyBoYXNoIHdoaWNoIHNob3VsZCBiZSBieXRlcw=="
|
|
valid_until_ts:
|
|
type: integer
|
|
format: int64
|
|
description: |-
|
|
POSIX timestamp when the list of valid keys should be refreshed. Keys used beyond this
|
|
timestamp are no longer valid.
|
|
example: 1052262000000
|