From 80699812525655fa1f251eb527993af3c71df955 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 27 Aug 2018 14:19:10 -0600 Subject: [PATCH 1/6] Add federation /user/* endpoints Fixes https://github.com/matrix-org/matrix-doc/issues/1438 --- api/server-server/user_devices.yaml | 84 +++++++++++++ api/server-server/user_keys.yaml | 188 ++++++++++++++++++++++++++++ specification/server_server_api.rst | 17 ++- 3 files changed, 288 insertions(+), 1 deletion(-) create mode 100644 api/server-server/user_devices.yaml create mode 100644 api/server-server/user_keys.yaml diff --git a/api/server-server/user_devices.yaml b/api/server-server/user_devices.yaml new file mode 100644 index 000000000..d16442706 --- /dev/null +++ b/api/server-server/user_devices.yaml @@ -0,0 +1,84 @@ +# 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 Device 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/devices/{userId}": + get: + summary: Gets all of the user's devices + description: Gets information on all of the user's devices + operationId: getUserDevices + security: + - signedRequest: [] + parameters: + - in: path + name: userId + type: string + required: true + description: |- + The user ID to retrieve devices for. Must be a user local to the + receiving homeserver. + required: true + x-example: "@alice:example.org" + responses: + 200: + description: The user's devices. + schema: + type: object + properties: + user_id: + type: string + description: The user ID devices were requested for. + example: "@alice:example.org" + stream_id: + type: integer + description: |- + An ID the requesting homeserver may use to detect changes in the + device list. This should increase as time goes on, and always + produce the same ``devices`` list if not incremented. + example: 334608 + devices: + type: array + description: The user's devices. May be empty. + items: + type: object + title: User Device + properties: + device_id: + type: string + description: The device ID. + example: "JLAFKJWSCS" + keys: + type: object + description: Identity keys for the device. + $ref: "../client-server/definitions/device_keys.yaml" + device_display_name: + type: string + description: Optional display name for the device. + example: "Alice's Mobile Phone" + required: ['device_id', 'keys'] + required: ['user_id', 'stream_id', 'devices'] \ No newline at end of file diff --git a/api/server-server/user_keys.yaml b/api/server-server/user_keys.yaml new file mode 100644 index 000000000..869934331 --- /dev/null +++ b/api/server-server/user_keys.yaml @@ -0,0 +1,188 @@ +# 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": [] + } + 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 dbde8b104..634b8fd01 100644 --- a/specification/server_server_api.rst +++ b/specification/server_server_api.rst @@ -890,6 +890,20 @@ nothing else. {{openid_ss_http_api}} +End-to-End Encryption +--------------------- + +This section compliments 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}} + +{{user_devices_ss_http_api}} + + Send-to-device messaging ------------------------ @@ -1077,7 +1091,8 @@ that are too long. .. _`Invitation storage`: ../identity_service/unstable.html#invitation-storage .. _`Identity Service API`: ../identity_service/unstable.html -.. _`Client-Server API`: ../client_server/unstable.html +.. _`Client-Server API`: ../client_server/%CLIENT_RELEASE_LABEL%.html .. _`Inviting to a room`: #inviting-to-a-room .. _`Canonical JSON`: ../appendices.html#canonical-json .. _`Unpadded Base64`: ../appendices.html#unpadded-base64 +.. _`End-to-End Encryption module`: ../client-server/%CLIENT_RELEASE_LABEL%.html#end-to-end-encryption From be97e95dc123080514a07ef6b90a4842616b8921 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 27 Aug 2018 14:49:38 -0600 Subject: [PATCH 2/6] Promote device management to be a dedicated section --- specification/server_server_api.rst | 16 ++++++++++++++-- 1 file changed, 14 insertions(+), 2 deletions(-) diff --git a/specification/server_server_api.rst b/specification/server_server_api.rst index 634b8fd01..cc23a83dc 100644 --- a/specification/server_server_api.rst +++ b/specification/server_server_api.rst @@ -890,6 +890,19 @@ nothing else. {{openid_ss_http_api}} + +Device Management +----------------- + +.. TODO: TravisR - Incorporate https://github.com/matrix-org/matrix-doc/issues/1212 + +A user's devices may need to be queried over federation for different purposes, such +as end-to-end encryption or for utilizing send-to-device messaging. This section is +intended to compliment the `Device Management module`_ of the Client-Server API. + +{{user_devices_ss_http_api}} + + End-to-End Encryption --------------------- @@ -901,8 +914,6 @@ through to federation, and have the response also be proxied through to the clie {{user_keys_ss_http_api}} -{{user_devices_ss_http_api}} - Send-to-device messaging ------------------------ @@ -1095,4 +1106,5 @@ that are too long. .. _`Inviting to a room`: #inviting-to-a-room .. _`Canonical JSON`: ../appendices.html#canonical-json .. _`Unpadded Base64`: ../appendices.html#unpadded-base64 +.. _`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 From 8950f0b2cc08d96f9d835804f78b59b08273b8c5 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 29 Aug 2018 14:36:43 -0600 Subject: [PATCH 3/6] Spelling --- specification/server_server_api.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specification/server_server_api.rst b/specification/server_server_api.rst index cc23a83dc..9a68f33c2 100644 --- a/specification/server_server_api.rst +++ b/specification/server_server_api.rst @@ -804,7 +804,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. @@ -906,7 +906,7 @@ intended to compliment the `Device Management module`_ of the Client-Server API. End-to-End Encryption --------------------- -This section compliments the `End-to-End Encryption module`_ of the Client-Server +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 From f2d02c9559339f51b7ed0f75d2b408132df7f757 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 29 Aug 2018 14:37:30 -0600 Subject: [PATCH 4/6] Take out device management section for now This will be handled by the implementation of https://github.com/matrix-org/matrix-doc/issues/1212 --- api/server-server/user_devices.yaml | 84 ----------------------------- specification/server_server_api.rst | 12 ----- 2 files changed, 96 deletions(-) delete mode 100644 api/server-server/user_devices.yaml diff --git a/api/server-server/user_devices.yaml b/api/server-server/user_devices.yaml deleted file mode 100644 index d16442706..000000000 --- a/api/server-server/user_devices.yaml +++ /dev/null @@ -1,84 +0,0 @@ -# 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 Device 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/devices/{userId}": - get: - summary: Gets all of the user's devices - description: Gets information on all of the user's devices - operationId: getUserDevices - security: - - signedRequest: [] - parameters: - - in: path - name: userId - type: string - required: true - description: |- - The user ID to retrieve devices for. Must be a user local to the - receiving homeserver. - required: true - x-example: "@alice:example.org" - responses: - 200: - description: The user's devices. - schema: - type: object - properties: - user_id: - type: string - description: The user ID devices were requested for. - example: "@alice:example.org" - stream_id: - type: integer - description: |- - An ID the requesting homeserver may use to detect changes in the - device list. This should increase as time goes on, and always - produce the same ``devices`` list if not incremented. - example: 334608 - devices: - type: array - description: The user's devices. May be empty. - items: - type: object - title: User Device - properties: - device_id: - type: string - description: The device ID. - example: "JLAFKJWSCS" - keys: - type: object - description: Identity keys for the device. - $ref: "../client-server/definitions/device_keys.yaml" - device_display_name: - type: string - description: Optional display name for the device. - example: "Alice's Mobile Phone" - required: ['device_id', 'keys'] - required: ['user_id', 'stream_id', 'devices'] \ No newline at end of file diff --git a/specification/server_server_api.rst b/specification/server_server_api.rst index 9a68f33c2..558a5f8d7 100644 --- a/specification/server_server_api.rst +++ b/specification/server_server_api.rst @@ -891,18 +891,6 @@ nothing else. {{openid_ss_http_api}} -Device Management ------------------ - -.. TODO: TravisR - Incorporate https://github.com/matrix-org/matrix-doc/issues/1212 - -A user's devices may need to be queried over federation for different purposes, such -as end-to-end encryption or for utilizing send-to-device messaging. This section is -intended to compliment the `Device Management module`_ of the Client-Server API. - -{{user_devices_ss_http_api}} - - End-to-End Encryption --------------------- From caaa688e37750fea10788aced24330cfc283e8f7 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Thu, 30 Aug 2018 16:28:26 -0600 Subject: [PATCH 5/6] Fix links to client-server spec --- specification/server_server_api.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/specification/server_server_api.rst b/specification/server_server_api.rst index a71240101..76aed91d4 100644 --- a/specification/server_server_api.rst +++ b/specification/server_server_api.rst @@ -1110,9 +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 +.. _`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 From 2a08a308f34f7583534e3e9009f390471d1faf07 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Thu, 30 Aug 2018 16:29:24 -0600 Subject: [PATCH 6/6] device_keys are required --- api/server-server/user_keys.yaml | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/api/server-server/user_keys.yaml b/api/server-server/user_keys.yaml index 869934331..63c74d20e 100644 --- a/api/server-server/user_keys.yaml +++ b/api/server-server/user_keys.yaml @@ -55,7 +55,7 @@ paths: description: algorithm example: "signed_curve25519" example: { - "@alice:example.com": { + "@alice:example.com": { "JLAFKJWSCS": "signed_curve25519" } } @@ -126,6 +126,7 @@ paths: example: { "@alice:example.com": [] } + required: ['device_keys'] responses: 200: description: The device information. @@ -178,7 +179,7 @@ paths: "@alice:example.com": { "ed25519:JLAFKJWSCS": "dSO80A01XiigH3uBiDVx/EjzaoycHcjq9lfQX0uWsqxl2giMIiSPR8a4d291W1ihKJL/a+myXS367WT6NAIcBA" } - }, + }, "unsigned": { "device_display_name": "Alice's mobile phone" }