You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
matrix-spec/data/api/server-server/definitions/keys.yaml

102 lines
3.8 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: The homeserver's [server name](/appendices/#server-name).
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. The version must have characters matching the regular
expression `[a-zA-Z0-9_]`.
additionalProperties:
type: object
title: Verify Key
properties:
key:
type: string
description: The [Unpadded base64](/appendices/#unpadded-base64) encoded key.
example: "VGhpcyBzaG91bGQgYmUgYSByZWFsIGVkMjU1MTkgcGF5bG9hZA"
required: ["key"]
example: {
"ed25519:abc123": {
"key": "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. The version must have characters matching the regular
expression `[a-zA-Z0-9_]`.
additionalProperties:
type: object
title: Old Verify Key
properties:
expired_ts:
type: integer
format: int64
description: POSIX timestamp in milliseconds for when this key expired.
example: 1532645052628
key:
type: string
description: The [Unpadded base64](/appendices/#unpadded-base64) encoded key.
example: "VGhpcyBzaG91bGQgYmUgeW91ciBvbGQga2V5J3MgZWQyNTUxOSBwYXlsb2FkLg"
required: ["expired_ts", "key"]
example: {
"ed25519:0ldK3y": {
"expired_ts": 1532645052628,
"key": "VGhpcyBzaG91bGQgYmUgeW91ciBvbGQga2V5J3MgZWQyNTUxOSBwYXlsb2FkLg"
}
}
signatures:
type: object
description: |-
Digital signatures for this object signed using the `verify_keys`.
The signature is calculated using the process described at [Signing JSON](/appendices/#signing-json).
title: Signatures
additionalProperties:
type: object
additionalProperties:
type: string
valid_until_ts:
type: integer
format: int64
description: |-
POSIX timestamp in milliseconds when the list of valid keys should be refreshed.
This field MUST be ignored in room versions 1, 2, 3, and 4. Keys used beyond this
timestamp MUST be considered invalid, depending on the
[room version specification](/rooms).
Servers MUST use the lesser of this field and 7 days into the future when
determining if a key is valid. This is to avoid a situation where an attacker
publishes a key which is valid for a significant amount of time without a way
for the homeserver owner to revoke it.
example: 1052262000000
required: ["server_name", "verify_keys", "signatures", "valid_until_ts"]