matrix-spec/data/api/server-server/user_keys.yaml

# Copyright 2018 New Vector Ltd
# Copyright 2020 The Matrix.org Foundation C.I.C.
#
# 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.
openapi: 3.1.0
info:
  title: Matrix Federation User Key Management API
  version: 1.0.0
paths:
  /user/keys/claim:
    post:
      summary: Claims one-time encryption keys for a user.
      description: Claims one-time keys for use in pre-key messages.
      operationId: claimUserEncryptionKeys
      security:
        - signedRequest: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                one_time_keys:
                  type: object
                  description: |-
                    The keys to be claimed. A map from user ID, to a map from
                    device ID to algorithm name.
                  additionalProperties:
                    type: object
                    additionalProperties:
                      type: string
                      description: algorithm
                      example: signed_curve25519
                  example:
                    "@alice:example.com":
                      JLAFKJWSCS: signed_curve25519
              required:
                - one_time_keys
        required: true
      responses:
        "200":
          description: The claimed keys.
          content:
            application/json:
              schema:
                type: object
                properties:
                  one_time_keys:
                    type: object
                    description: |-
                      One-time keys for the queried devices. A map from user ID, to a
                      map from devices to a map from `<algorithm>:<key_id>` to the key object.

                      See the [Client-Server Key Algorithms](/client-server-api/#key-algorithms) section for more information on
                      the Key Object format.
                    # User
                    additionalProperties:
                      type: object
                      # Device
                      additionalProperties:
                        type: object
                        # Key
                        additionalProperties:
                          oneOf:
                            - type: string
                            - type: object
                              title: KeyObject
                              properties:
                                key:
                                  type: string
                                  description: The key, encoded using unpadded base64.
                                signatures:
                                  type: object
                                  title: Signatures
                                  additionalProperties:
                                    type: object
                                    additionalProperties:
                                      type: string
                                  description: |-
                                    Signature of the key object.

                                    The signature is calculated using the process described at [Signing JSON](/appendices/#signing-json).
                              required:
                                - key
                                - signatures
                    example:
                      "@alice:example.com":
                        JLAFKJWSCS:
                          signed_curve25519:AAAAHg:
                            key: zKbLg+NrIjpnagy+pIY6uPL4ZwEG2v+8F9lmgsnlZzs
                            signatures:
                              "@alice:example.com":
                                ed25519:JLAFKJWSCS: FLWxXqGbwrb8SM3Y795eB6OA8bwBcoMZFXBqnTn58AYWZSqiD45tlBVcDa2L7RwdKXebW/VzDlnfVJ+9jok1Bw
                required:
                  - one_time_keys
  /user/keys/query:
    post:
      summary: Download device identity keys.
      description: Returns the current devices and identity keys for the given users.
      operationId: queryUserEncryptionKeys
      security:
        - signedRequest: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                device_keys:
                  type: object
                  description: |-
                    The keys to be downloaded. A map from user ID, to a list of
                    device IDs, or to an empty list to indicate all devices for the
                    corresponding user.
                  additionalProperties:
                    type: array
                    items:
                      type: string
                      description: Device ID
                  example:
                    "@alice:example.com": []
              required:
                - device_keys
        required: true
      responses:
        "200":
          description: The device information.
          content:
            application/json:
              schema:
                type: object
                properties:
                  device_keys:
                    type: object
                    description: |-
                      Information on the queried devices. A map from user ID, to a
                      map from device ID to device information.  For each device,
                      the information returned will be the same as uploaded via
                      `/keys/upload`, with the addition of an `unsigned`
                      property.
                    additionalProperties:
                      type: object
                      additionalProperties:
                        allOf:
                          - $ref: ../client-server/definitions/device_keys.yaml
                        properties:
                          unsigned:
                            title: UnsignedDeviceInfo
                            type: object
                            description: |-
                              Additional data added to the device key information
                              by intermediate servers, and not covered by the
                              signatures.
                            properties:
                              device_display_name:
                                type: string
                                description: The display name which the user set on the device.
                  master_keys:
                    x-addedInMatrixVersion: "1.1"
                    type: object
                    description: |-
                      Information on the master cross-signing keys of the queried users.
                      A map from user ID, to master key information.  For each key, the
                      information returned will be the same as uploaded via
                      `/keys/device_signing/upload`, along with the signatures
                      uploaded via `/keys/signatures/upload` that the user is
                      allowed to see.
                    additionalProperties:
                      allOf:
                        - $ref: ../client-server/definitions/cross_signing_key.yaml
                    example:
                      "@alice:example.com":
                        user_id: "@alice:example.com"
                        usage:
                          - master
                        keys:
                          ed25519:base64+master+public+key: base64+master+public+key
                  self_signing_keys:
                    x-addedInMatrixVersion: "1.1"
                    type: object
                    description: |-
                      Information on the self-signing keys of the queried users. A map
                      from user ID, to self-signing key information.  For each key, the
                      information returned will be the same as uploaded via
                      `/keys/device_signing/upload`.
                    additionalProperties:
                      allOf:
                        - $ref: ../client-server/definitions/cross_signing_key.yaml
                    example:
                      "@alice:example.com":
                        user_id: "@alice:example.com"
                        usage:
                          - self_signing
                        keys:
                          ed25519:base64+self+signing+public+key: base64+self+signing+master+public+key
                        signatures:
                          "@alice:example.com":
                            ed25519:base64+master+public+key: signature+of+self+signing+key
                required:
                  - device_keys
              examples:
                response:
                  value: {
                    "device_keys": {
                      "@alice:example.com": {
                        "JLAFKJWSCS": {
                          "user_id": "@alice:example.com",
                          "device_id": "JLAFKJWSCS",
                          "algorithms": [
                            "m.olm.v1.curve25519-aes-sha2",
                            "m.megolm.v1.aes-sha2"
                          ],
                          "keys": {
                            "curve25519:JLAFKJWSCS": "3C5BFWi2Y8MaVvjM8M22DBmh24PmgR0nPvJOIArzgyI",
                            "ed25519:JLAFKJWSCS": "lEuiRJBit0IG6nUf5pUzWTUEsRVVe/HJkoKuEww9ULI"
                          },
                          "signatures": {
                            "@alice:example.com": {
                              "ed25519:JLAFKJWSCS": "dSO80A01XiigH3uBiDVx/EjzaoycHcjq9lfQX0uWsqxl2giMIiSPR8a4d291W1ihKJL/a+myXS367WT6NAIcBA"
                            }
                          },
                          "unsigned": {
                            "device_display_name": "Alice's mobile phone"
                          }
                        }
                      }
                    }
                  }
servers:
  - url: "{protocol}://{hostname}{basePath}"
    variables:
      protocol:
        enum:
          - http
          - https
        default: https
      hostname:
        default: localhost:8448
      basePath:
        default: /_matrix/federation/v1
components:
  securitySchemes:
    $ref: definitions/security.yaml