-
-
Notifications
You must be signed in to change notification settings - Fork 89
/
user_keys.yaml
253 lines (251 loc) · 10.5 KB
/
user_keys.yaml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
# 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:
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.
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