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/server-server/user_keys.yaml

252 lines
10 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.
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.
additionalProperties:
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
additionalProperties:
type: object
# Device
additionalProperties:
type: object
# Key
additionalProperties:
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.
additionalProperties:
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.
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.
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 user is
allowed to see.
additionalProperties:
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`.
additionalProperties:
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:
$ref: definitions/security.yaml