You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
matrix-spec/data/api/client-server/keys.yaml

494 lines
20 KiB
YAML

# Copyright 2016 OpenMarket Ltd
# 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.
swagger: '2.0'
info:
title: "Matrix Client-Server Client Config API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/v3
consumes:
- application/json
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
paths:
"/keys/upload":
post:
summary: Upload end-to-end encryption keys.
description: |-
Publishes end-to-end encryption keys for the device.
operationId: uploadKeys
security:
- accessToken: []
parameters:
- in: body
name: keys
description: |-
The keys to be published
required: true
schema:
type: object
properties:
device_keys:
description: |-
Identity keys for the device. May be absent if no new
identity keys are required.
allOf:
- $ref: definitions/device_keys.yaml
one_time_keys:
# $ref: "definitions/one_time_keys.yaml"
# XXX: We can't define an actual object here, so we have to hope
# that people will look at the swagger source or can figure it out
# from the other endpoints/example.
type: object
title: OneTimeKeys
description: |-
One-time public keys for "pre-key" messages. The names of
the properties should be in the format
`<algorithm>:<key_id>`. The format of the key is determined
by the [key algorithm](/client-server-api/#key-algorithms).
May be absent if no new one-time keys are required.
example: {
"curve25519:AAAAAQ": "/qyvZvwjiTxGdGU0RCguDCLeR+nmsb3FfNG3/Ve4vU8",
"signed_curve25519:AAAAHg": {
"key": "zKbLg+NrIjpnagy+pIY6uPL4ZwEG2v+8F9lmgsnlZzs",
"signatures": {
"@alice:example.com": {
"ed25519:JLAFKJWSCS": "FLWxXqGbwrb8SM3Y795eB6OA8bwBcoMZFXBqnTn58AYWZSqiD45tlBVcDa2L7RwdKXebW/VzDlnfVJ+9jok1Bw"
}
}
},
"signed_curve25519:AAAAHQ": {
"key": "j3fR3HemM16M7CWhoI4Sk5ZsdmdfQHsKL1xuSft6MSw",
"signatures": {
"@alice:example.com": {
"ed25519:JLAFKJWSCS": "IQeCEPb9HFk217cU9kw9EOiusC6kMIkoIRnbnfOh5Oc63S1ghgyjShBGpu34blQomoalCyXWyhaaT3MrLZYQAA"
}
}
}
}
fallback_keys:
x-addedInMatrixVersion: "1.2"
# $ref: "definitions/one_time_keys.yaml"
# XXX: We can't define an actual object here - see above.
type: object
title: OneTimeKeys
description: |-
The public key which should be used if the device's one-time keys
are exhausted. The fallback key is not deleted once used, but should
be replaced when additional one-time keys are being uploaded. The
server will notify the client of the fallback key being used through
`/sync`.
There can only be at most one key per algorithm uploaded, and the server
will only persist one key per algorithm.
When uploading a signed key, an additional `fallback: true` key should
be included to denote that the key is a fallback key.
May be absent if a new fallback key is not required.
example: {
"curve25519:AAAAAG": "/qyvZvwjiTxGdGU0RCguDCLeR+nmsb3FfNG3/Ve4vU8",
"signed_curve25519:AAAAGj": {
"key": "zKbLg+NrIjpnagy+pIY6uPL4ZwEG2v+8F9lmgsnlZzs",
"fallback": true,
"signatures": {
"@alice:example.com": {
"ed25519:JLAFKJWSCS": "FLWxXqGbwrb8SM3Y795eB6OA8bwBcoMZFXBqnTn58AYWZSqiD45tlBVcDa2L7RwdKXebW/VzDlnfVJ+9jok1Bw"
}
}
}
}
responses:
200:
description:
The provided keys were successfully uploaded.
schema:
type: object
properties:
one_time_key_counts:
type: object
additionalProperties:
type: integer
description: |-
For each key algorithm, the number of unclaimed one-time keys
of that type currently held on the server for this device.
If an algorithm is not listed, the count for that algorithm
is to be assumed zero.
example:
curve25519: 10
signed_curve25519: 20
required:
- one_time_key_counts
tags:
- End-to-end encryption
"/keys/query":
post:
summary: Download device identity keys.
description: |-
Returns the current devices and identity keys for the given users.
operationId: queryKeys
security:
- accessToken: []
parameters:
- in: body
name: query
description: |-
Query defining the keys to be downloaded
required: true
schema:
type: object
properties:
timeout:
type: integer
description: |-
The time (in milliseconds) to wait when downloading keys from
remote servers. 10 seconds is the recommended default.
example: 10000
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": []
token:
type: string
description: |-
If the client is fetching keys as a result of a device update received
in a sync request, this should be the 'since' token of that sync request,
or any later sync token. This allows the server to ensure its response
contains the keys advertised by the notification in that sync.
required:
- device_keys
responses:
200:
description:
The device information
schema:
type: object
properties:
failures:
type: object
description: |-
If any remote homeservers could not be reached, they are
recorded here. The names of the properties are the names of
the unreachable servers.
If the homeserver could be reached, but the user or device
was unknown, no failure is recorded. Instead, the corresponding
user or device is missing from the `device_keys` result.
additionalProperties:
type: object
example: {}
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:
title: DeviceInformation
allOf:
- $ref: 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.
example:
"@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"
}
}
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 requesting user
is allowed to see.
additionalProperties:
allOf:
- $ref: 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`.
additionalProperties:
allOf:
- $ref: 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"
}
}
}
}
user_signing_keys:
type: object
description: |-
Information on the user-signing key of the user making the
request, if they queried their own device information. A map
from user ID, to user-signing key information. The
information returned will be the same as uploaded via
`/keys/device_signing/upload`.
additionalProperties:
allOf:
- $ref: definitions/cross_signing_key.yaml
example: {
"@alice:example.com": {
"user_id": "@alice:example.com",
"usage": ["user_signing"],
"keys": {
"ed25519:base64+user+signing+public+key": "base64+user+signing+master+public+key",
},
"signatures": {
"@alice:example.com": {
"ed25519:base64+master+public+key": "signature+of+user+signing+key"
}
}
}
}
tags:
- End-to-end encryption
"/keys/claim":
post:
summary: Claim one-time encryption keys.
description: |-
Claims one-time keys for use in pre-key messages.
operationId: claimKeys
security:
- accessToken: []
parameters:
- in: body
name: query
description: |-
Query defining the keys to be claimed
required: true
schema:
type: object
properties:
timeout:
type: integer
description: |-
The time (in milliseconds) to wait when downloading keys from
remote servers. 10 seconds is the recommended default.
example: 10000
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:
failures:
type: object
description: |-
If any remote homeservers could not be reached, they are
recorded here. The names of the properties are the names of
the unreachable servers.
If the homeserver could be reached, but the user or device
was unknown, no failure is recorded. Instead, the corresponding
user or device is missing from the `one_time_keys` result.
additionalProperties:
type: object
example: {}
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.
See the [key algorithms](/client-server-api/#key-algorithms) section for information
on the Key Object format.
If necessary, the claimed key might be a fallback key. Fallback
keys are re-used by the server until replaced by the device.
additionalProperties:
type: object
additionalProperties:
# $ref: "definitions/one_time_keys.yaml"
# XXX: We can't define an actual object here, so we have to hope
# that people will read the link provided in the description
# and figure it out from the other endpoints/example.
# See also one_time_key parameter for /keys/upload above.
type: object
title: OneTimeKeys
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']
tags:
- End-to-end encryption
"/keys/changes":
get:
summary: Query users with recent device key updates.
description: |-
Gets a list of users who have updated their device identity keys since a
previous sync token.
The server should include in the results any users who:
* currently share a room with the calling user (ie, both users have
membership state `join`); *and*
* added new device identity keys or removed an existing device with
identity keys, between `from` and `to`.
operationId: getKeysChanges
security:
- accessToken: []
parameters:
- in: query
name: from
type: string
description: |-
The desired start point of the list. Should be the `next_batch` field
from a response to an earlier call to [`/sync`](/client-server-api/#get_matrixclientv3sync). Users who have not
uploaded new device identity keys since this point, nor deleted
existing devices with identity keys since then, will be excluded
from the results.
required: true
x-example: "s72594_4483_1934"
- in: query
name: to
type: string
description: |-
The desired end point of the list. Should be the `next_batch`
field from a recent call to [`/sync`](/client-server-api/#get_matrixclientv3sync) - typically the most recent
such call. This may be used by the server as a hint to check its
caches are up to date.
required: true
x-example: "s75689_5632_2435"
responses:
200:
description:
The list of users who updated their devices.
schema:
type: object
properties:
changed:
type: array
items:
type: string
description: |-
The Matrix User IDs of all users who updated their device
identity keys.
example: ["@alice:example.com", "@bob:example.org"]
left:
type: array
items:
type: string
description: |-
The Matrix User IDs of all users who may have left all
the end-to-end encrypted rooms they previously shared
with the user.
example: ["@clara:example.com", "@doug:example.org"]
tags:
- End-to-end encryption