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

464 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.
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:
# $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 OpenAPI 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:
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:
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.
additionalProperties:
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.
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:
- 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.
additionalProperties:
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.
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:
- 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