# 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 `:` 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: 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: 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: 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" } } } } }