Add federation /user/* endpoints

Fixes https://github.com/matrix-org/matrix-doc/issues/1438
pull/1576/head
Travis Ralston 6 years ago
parent 32ce676eb6
commit 8069981252

@ -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']

@ -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 ``<algorithm>:<key_id>`` 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"
}
}
}
}
}

@ -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

Loading…
Cancel
Save