# 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. Requested users must be local to the receiving homeserver. patternProperties: "^@": x-pattern-format: mx-user-id 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 `:` 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 patternProperties: "^@": x-pattern-format: mx-user-id 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. Requested users must be local to the receiving homeserver. patternProperties: "^@": x-pattern-format: mx-user-id 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. patternProperties: "^@": x-pattern-format: mx-user-id 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. patternProperties: "^@": x-pattern-format: mx-user-id 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`. patternProperties: "^@": x-pattern-format: mx-user-id 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: signedRequest: $ref: definitions/security.yaml#/signedRequest