mirror of
https://github.com/matrix-org/matrix-spec
synced 2026-02-14 18:13:47 +01:00
48bbc53045
- the naming of the master signing key has been harmonised (no more 'master cross-signing key' or 'master key'). - in the QR code example, the term 'cross-signing key' has been replaced by 'master signing key' since in mode 0x00, the current user's own master signing key and what the device thinks the other user's master signng key is used. - it has been made more explicit that cross-signing private keys stored on the server are stored as described in the secrets module (as opposed to store them in unencrypted form) Signed-off-by: codedust <codedust@so.urceco.de> Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>
483 lines
21 KiB
YAML
483 lines
21 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.
|
|
openapi: 3.1.0
|
|
info:
|
|
title: Matrix Client-Server Client Config API
|
|
version: 1.0.0
|
|
paths:
|
|
/keys/upload:
|
|
post:
|
|
summary: Upload end-to-end encryption keys.
|
|
description: Publishes end-to-end encryption keys for the device.
|
|
operationId: uploadKeys
|
|
security:
|
|
- accessTokenQuery: []
|
|
- accessTokenBearer: []
|
|
requestBody:
|
|
content:
|
|
application/json:
|
|
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:
|
|
allOf:
|
|
- $ref: "definitions/one_time_keys.yaml"
|
|
type: object
|
|
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:
|
|
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"
|
|
allOf:
|
|
- $ref: "definitions/one_time_keys.yaml"
|
|
type: object
|
|
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:
|
|
signed_curve25519:AAAAGj:
|
|
key: zKbLg+NrIjpnagy+pIY6uPL4ZwEG2v+8F9lmgsnlZzs
|
|
fallback: true
|
|
signatures:
|
|
"@alice:example.com":
|
|
ed25519:JLAFKJWSCS: FLWxXqGbwrb8SM3Y795eB6OA8bwBcoMZFXBqnTn58AYWZSqiD45tlBVcDa2L7RwdKXebW/VzDlnfVJ+9jok1Bw
|
|
description: The keys to be published
|
|
required: true
|
|
responses:
|
|
"200":
|
|
description: The provided keys were successfully uploaded.
|
|
content:
|
|
application/json:
|
|
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:
|
|
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:
|
|
- accessTokenQuery: []
|
|
- accessTokenBearer: []
|
|
requestBody:
|
|
content:
|
|
application/json:
|
|
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.
|
|
patternProperties:
|
|
"^@":
|
|
x-pattern-format: mx-user-id
|
|
type: array
|
|
items:
|
|
type: string
|
|
description: device ID
|
|
example:
|
|
"@alice:example.com": []
|
|
required:
|
|
- device_keys
|
|
description: Query defining the keys to be downloaded
|
|
required: true
|
|
responses:
|
|
"200":
|
|
description: The device information
|
|
content:
|
|
application/json:
|
|
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.
|
|
patternProperties:
|
|
"^@":
|
|
x-pattern-format: mx-user-id
|
|
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 signing keys of the queried users.
|
|
A map from user ID, to master signing 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.
|
|
patternProperties:
|
|
"^@":
|
|
x-pattern-format: mx-user-id
|
|
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`.
|
|
patternProperties:
|
|
"^@":
|
|
x-pattern-format: mx-user-id
|
|
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`.
|
|
patternProperties:
|
|
"^@":
|
|
x-pattern-format: mx-user-id
|
|
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.
|
|
|
|
The request contains the user ID, device ID and algorithm name of the
|
|
keys that are required. If a key matching these requirements can be
|
|
found, the response contains it. The returned key is a one-time key
|
|
if one is available, and otherwise a fallback key.
|
|
|
|
One-time keys are given out in the order that they were uploaded via
|
|
[/keys/upload](/client-server-api/#post_matrixclientv3keysupload). (All
|
|
keys uploaded within a given call to `/keys/upload` are considered
|
|
equivalent in this regard; no ordering is specified within them.)
|
|
|
|
Servers must ensure that each one-time key is returned at most once,
|
|
so when a key has been returned, no other request will ever return
|
|
the same key.
|
|
operationId: claimKeys
|
|
security:
|
|
- accessTokenQuery: []
|
|
- accessTokenBearer: []
|
|
requestBody:
|
|
content:
|
|
application/json:
|
|
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.
|
|
patternProperties:
|
|
"^@":
|
|
x-pattern-format: mx-user-id
|
|
type: object
|
|
additionalProperties:
|
|
type: string
|
|
description: algorithm
|
|
example: signed_curve25519
|
|
example:
|
|
"@alice:example.com":
|
|
JLAFKJWSCS: signed_curve25519
|
|
required:
|
|
- one_time_keys
|
|
description: Query defining the keys to be claimed
|
|
required: true
|
|
responses:
|
|
"200":
|
|
description: The claimed keys.
|
|
content:
|
|
application/json:
|
|
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.
|
|
patternProperties:
|
|
"^@":
|
|
x-pattern-format: mx-user-id
|
|
type: object
|
|
additionalProperties:
|
|
$ref: "definitions/one_time_keys.yaml"
|
|
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:
|
|
- accessTokenQuery: []
|
|
- accessTokenBearer: []
|
|
parameters:
|
|
- in: query
|
|
name: from
|
|
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
|
|
example: s72594_4483_1934
|
|
schema:
|
|
type: string
|
|
- in: query
|
|
name: to
|
|
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
|
|
example: s75689_5632_2435
|
|
schema:
|
|
type: string
|
|
responses:
|
|
"200":
|
|
description: The list of users who updated their devices.
|
|
content:
|
|
application/json:
|
|
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
|
|
servers:
|
|
- url: "{protocol}://{hostname}{basePath}"
|
|
variables:
|
|
protocol:
|
|
enum:
|
|
- http
|
|
- https
|
|
default: https
|
|
hostname:
|
|
default: localhost:8008
|
|
basePath:
|
|
default: /_matrix/client/v3
|
|
components:
|
|
securitySchemes:
|
|
accessTokenQuery:
|
|
$ref: definitions/security.yaml#/accessTokenQuery
|
|
accessTokenBearer:
|
|
$ref: definitions/security.yaml#/accessTokenBearer
|