diff --git a/api/server-server/user_keys.yaml b/api/server-server/user_keys.yaml new file mode 100644 index 00000000..63c74d20 --- /dev/null +++ b/api/server-server/user_keys.yaml @@ -0,0 +1,189 @@ +# 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. + +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. + additionalProperties: + type: object + additionalProperties: + type: + - string + - object + required: ['one_time_keys'] + examples: + application/json: { + "one_time_keys": { + "@alice:example.com": { + "JLAFKJWSCS": { + "signed_curve25518:AAAAHg": { + "key": "zKbLg+NrIjpnagy+pIY6uPL4ZwEG2v+8F9lmgsnlZzs", + "signatures": { + "@alice:example.com": { + "ed25519:JLAFKJWSCS": "FLWxXqGbwrb8SM3Y795eB6OA8bwBcoMZFXBqnTn58AYWZSqiD45tlBVcDa2L7RwdKXebW/VzDlnfVJ+9jok1Bw" + } + } + } + } + } + } + } + "/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. + 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-sha256", + "m.megolm.v1.aes-sha" + ], + "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" + } + } + } + } + } diff --git a/specification/server_server_api.rst b/specification/server_server_api.rst index 7898f69d..76aed91d 100644 --- a/specification/server_server_api.rst +++ b/specification/server_server_api.rst @@ -822,7 +822,7 @@ identifier. Public Room Directory --------------------- -To compliment the `Client-Server API`_'s room directory, homeservers need a +To complement the `Client-Server API`_'s room directory, homeservers need a way to query the public rooms for another server. This can be done by making a request to the ``/publicRooms`` endpoint for the server the room directory should be retrieved for. @@ -908,6 +908,19 @@ nothing else. {{openid_ss_http_api}} + +End-to-End Encryption +--------------------- + +This section complements the `End-to-End Encryption module`_ of the Client-Server +API. For detailed information about end-to-end encryption, please see that module. + +The APIs defined here are designed to be able to proxy much of the client's request +through to federation, and have the response also be proxied through to the client. + +{{user_keys_ss_http_api}} + + Send-to-device messaging ------------------------ @@ -1097,7 +1110,9 @@ Example code .. _`Inviting to a room`: #inviting-to-a-room .. _`Canonical JSON`: ../appendices.html#canonical-json .. _`Unpadded Base64`: ../appendices.html#unpadded-base64 -.. _`Server ACLs`: ../client_server/unstable.html#module-server-acls -.. _`redaction algorithm`: ../client_server/unstable.html#redactions +.. _`Server ACLs`: ../client_server/%CLIENT_RELEASE_LABEL%.html#module-server-acls +.. _`redaction algorithm`: ../client_server/%CLIENT_RELEASE_LABEL%.html#redactions .. _`Signing JSON`: ../appendices.html#signing-json .. _`Checking for a signature`: ../appendices.html#checking-for-a-signature +.. _`Device Management module`: ../client_server/%CLIENT_RELEASE_LABEL%.html#device-management +.. _`End-to-End Encryption module`: ../client_server/%CLIENT_RELEASE_LABEL%.html#end-to-end-encryption