From af515012ea7a2ff07e16447439947390ae7a0273 Mon Sep 17 00:00:00 2001 From: Richard van der Hoff Date: Tue, 4 Oct 2016 11:53:39 +0100 Subject: [PATCH] Device management API --- .../definitions/client_device.yaml | 44 ++++++ api/client-server/device_management.yaml | 139 ++++++++++++++++++ changelogs/client_server.rst | 4 +- specification/modules/device_management.rst | 41 ++++++ specification/targets.yaml | 1 + 5 files changed, 228 insertions(+), 1 deletion(-) create mode 100644 api/client-server/definitions/client_device.yaml create mode 100644 api/client-server/device_management.yaml create mode 100644 specification/modules/device_management.rst diff --git a/api/client-server/definitions/client_device.yaml b/api/client-server/definitions/client_device.yaml new file mode 100644 index 00000000..6dc3abf3 --- /dev/null +++ b/api/client-server/definitions/client_device.yaml @@ -0,0 +1,44 @@ +# Copyright 2016 OpenMarket 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. + +type: object +description: A client device +title: Device +properties: + device_id: + type: string + description: Identifier of this device. + example: QBUAZIFURK + display_name: + type: string + description: |- + Display name set by the user for this device. Absent if no name has been + set. + example: android + last_seen_ip: + type: string + description: |- + The IP address where this device was last seen. (May be a few minutes out + of date, for efficiency reasons). + example: 1.2.3.4 + last_seen_ts: + type: integer + format: int64 + description: |- + The timestamp (in milliseconds since the unix epoch) when this devices + was last seen. (May be a few minutes out of date, for efficiency + reasons). + example: 1474491775024 +required: + - device_id diff --git a/api/client-server/device_management.yaml b/api/client-server/device_management.yaml new file mode 100644 index 00000000..64e0751a --- /dev/null +++ b/api/client-server/device_management.yaml @@ -0,0 +1,139 @@ +# Copyright 2016 OpenMarket 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 Client-Server device management API" + version: "1.0.0" +host: localhost:8008 +schemes: + - https + - http +basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% +consumes: + - application/json +produces: + - application/json +securityDefinitions: + $ref: definitions/security.yaml +paths: + "/devices": + get: + summary: List registered devices for the current user + description: |- + Gets information about all devices for the current user. + security: + - accessToken: [] + responses: + 200: + description: Device information + schema: + type: object + properties: + devices: + type: array + description: A list of all registered devices for this user. + items: + type: object + allOf: + - $ref: "definitions/client_device.yaml" + examples: + application/json: |- + { + "devices": [ + { + "device_id": "QBUAZIFURK", + "display_name": "android", + "last_seen_ip": "1.2.3.4", + "last_seen_ts": 1474491775024 + } + ] + } + tags: + - Device management + "/devices/{deviceId}": + get: + summary: Get a single device + description: |- + Gets information on a single device, by device id. + security: + - accessToken: [] + parameters: + - in: path + type: string + name: deviceId + description: The device to retrieve. + required: true + x-example: "QBUAZIFURK" + responses: + 200: + description: Device information + schema: + type: object + allOf: + - $ref: "definitions/client_device.yaml" + examples: + application/json: |- + { + "device_id": "QBUAZIFURK", + "display_name": "android", + "last_seen_ip": "1.2.3.4", + "last_seen_ts": 1474491775024 + } + 404: + description: The current user has no device with the given ID. + tags: + - Device management + delete: + summary: Delete a device + description: |- + This API endpoint uses the `User-Interactive Authentication API`_. + + Deletes the given device, and invalidates any access token assoicated with it. + security: + - accessToken: [] + parameters: + - in: path + type: string + name: deviceId + description: The device to retrieve. + required: true + x-example: "QBUAZIFURK" + - in: body + name: body + schema: + type: object + properties: + auth: + description: |- + Additional authentication information for the + user-interactive authentication API. + "$ref": "definitions/auth_data.yaml" + responses: + 200: + description: |- + The device was successfully removed, or had been removed + previously. + schema: + type: object + examples: + application/json: |- + {} + 401: + description: |- + The homeserver requires additional authentication information. + schema: + "$ref": "definitions/auth_response.yaml" + tags: + - Device management diff --git a/changelogs/client_server.rst b/changelogs/client_server.rst index fc539dc0..b06b8988 100644 --- a/changelogs/client_server.rst +++ b/changelogs/client_server.rst @@ -32,8 +32,10 @@ (`#390 `_). - Add ``filter`` optional query param to ``/messages`` (`#390 `_). - - Add "Send-to-Device messaging" module + - Add 'Send-to-Device messaging' module (`#386 `_). + - Add 'Device management' module + (`#402 `_). - Require that User-Interactive auth fallback pages call ``window.postMessage`` to notify apps of completion (`#398 `_). diff --git a/specification/modules/device_management.rst b/specification/modules/device_management.rst new file mode 100644 index 00000000..3f9c8452 --- /dev/null +++ b/specification/modules/device_management.rst @@ -0,0 +1,41 @@ +.. Copyright 2016 OpenMarket 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. + +Device Management +================= + +.. _module:device-management: + +This module provides a means for a user to manage their `devices`_. + +Client behaviour +---------------- +Clients that implement this module should offer the user a list of registered +devices, as well as the means to update their display names. Clients should +also allow users to delete disused devices. + +{{device_management_cs_http_api}} + +Security considerations +----------------------- + +Deleting devices has security implications: it invalidates the access_token +assigned to the device, so an attacker could use it to log out the real user +(and do it repeatedly every time the real user tries to log in to block the +attacker). Servers should require additional authentication beyond the access +token when deleting devices (for example, requiring that the user resubmit +their password). + +The display names of devices are publicly visible. Clients should consider +advising the user of this. diff --git a/specification/targets.yaml b/specification/targets.yaml index a157366f..2fb55c6d 100644 --- a/specification/targets.yaml +++ b/specification/targets.yaml @@ -42,6 +42,7 @@ groups: # reusable blobs of files when prefixed with 'group:' - modules/presence.rst - modules/content_repo.rst - modules/send_to_device.rst + - modules/device_management.rst - modules/end_to_end_encryption.rst - modules/history_visibility.rst - modules/push.rst