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.

swagger: '2.0'
info:
  title: "Matrix Federation User Key Management API"
  version: "1.0.0"
host: localhost:8448
schemes:
  - https
basePath: /_matrix/federation/v1
consumes:
  - application/json
produces:
  - application/json
securityDefinitions:
  $ref: definitions/security.yaml
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: []
      parameters:
        - in: body
          name: body
          type: object
          required: true
          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
      responses:
        200:
          description: The claimed keys.
          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.
                additionalProperties:
                  type: object
                  additionalProperties:
                    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: []
      parameters:
        - in: body
          name: body
          type: object
          required: true
          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']
      responses:
        200:
          description: The device information.
          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:
                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:
                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:
            application/json: {
              "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"
                    }
                  }
                }
              }
            }