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>
284 lines
12 KiB
YAML
284 lines
12 KiB
YAML
# 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 Federation User Key Management API
|
|
version: 1.0.0
|
|
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.
|
|
|
|
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: claimUserEncryptionKeys
|
|
security:
|
|
- signedRequest: []
|
|
requestBody:
|
|
content:
|
|
application/json:
|
|
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. Requested users must be local
|
|
to the receiving homeserver.
|
|
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
|
|
required: true
|
|
responses:
|
|
"200":
|
|
description: The claimed keys.
|
|
content:
|
|
application/json:
|
|
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.
|
|
|
|
See the [Client-Server Key Algorithms](/client-server-api/#key-algorithms) section for more information on
|
|
the Key Object format.
|
|
# User
|
|
patternProperties:
|
|
"^@":
|
|
x-pattern-format: mx-user-id
|
|
type: object
|
|
# Device
|
|
additionalProperties:
|
|
type: object
|
|
# Key
|
|
additionalProperties:
|
|
oneOf:
|
|
- type: string
|
|
- type: object
|
|
title: KeyObject
|
|
properties:
|
|
key:
|
|
type: string
|
|
description: The key, encoded using unpadded base64.
|
|
signatures:
|
|
type: object
|
|
title: Signatures
|
|
additionalProperties:
|
|
type: object
|
|
additionalProperties:
|
|
type: string
|
|
description: |-
|
|
Signature of the key object.
|
|
|
|
The signature is calculated using the process described at [Signing JSON](/appendices/#signing-json).
|
|
required:
|
|
- key
|
|
- signatures
|
|
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
|
|
/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: []
|
|
requestBody:
|
|
content:
|
|
application/json:
|
|
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. Requested users must be local to the
|
|
receiving homeserver.
|
|
patternProperties:
|
|
"^@":
|
|
x-pattern-format: mx-user-id
|
|
type: array
|
|
items:
|
|
type: string
|
|
description: Device ID
|
|
example:
|
|
"@alice:example.com": []
|
|
required:
|
|
- device_keys
|
|
required: true
|
|
responses:
|
|
"200":
|
|
description: The device information.
|
|
content:
|
|
application/json:
|
|
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.
|
|
patternProperties:
|
|
"^@":
|
|
x-pattern-format: mx-user-id
|
|
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.
|
|
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 user is
|
|
allowed to see.
|
|
patternProperties:
|
|
"^@":
|
|
x-pattern-format: mx-user-id
|
|
allOf:
|
|
- $ref: ../client-server/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: ../client-server/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
|
|
required:
|
|
- device_keys
|
|
examples:
|
|
response:
|
|
value: {
|
|
"device_keys": {
|
|
"@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"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
servers:
|
|
- url: "{protocol}://{hostname}{basePath}"
|
|
variables:
|
|
protocol:
|
|
enum:
|
|
- http
|
|
- https
|
|
default: https
|
|
hostname:
|
|
default: localhost:8448
|
|
basePath:
|
|
default: /_matrix/federation/v1
|
|
components:
|
|
securitySchemes:
|
|
signedRequest:
|
|
$ref: definitions/security.yaml#/signedRequest
|