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

253 lines
9.7 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.
swagger: '2.0'
info:
title: "Matrix Federation User Key Management API"
version: "1.0.0"
host: localhost:8448
schemes:
- https
basePath: /_matrix/federation/v1
consumes:
- application/json
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
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: []
parameters:
- in: body
name: body
type: object
required: true
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
responses:
200:
description: The claimed keys.
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.
additionalProperties:
type: object
additionalProperties:
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: []
parameters:
- in: body
name: body
type: object
required: true
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']
responses:
200:
description: The device information.
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:
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:
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:
application/json: {
"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"
}
}
}
}
}