matrix-spec-proposals/api/server-server/definitions/keys.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. The version must have characters matching the regular
      expression ``[a-zA-Z0-9_]``.      
    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. The version must have characters matching the regular
      expression ``[a-zA-Z0-9_]``.      
    additionalProperties:
      type: object
      title: Old Verify Key
      example: {
        "ed25519:0ldK3y": {
          "expired_ts": 1532645052628,
          "key": "VGhpcyBzaG91bGQgYmUgeW91ciBvbGQga2V5J3MgZWQyNTUxOSBwYXlsb2FkLg"
        }
      }
      properties:
        expired_ts:
          type: integer
          format: int64
          description: POSIX timestamp in milliseconds for when this key expired.
          required: true
          example: 1532645052628
        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
  valid_until_ts:
    type: integer
    format: int64
    description: |-
      POSIX timestamp 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`_.

      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