Skip to content

Commit f352de9

Browse files
uhoreguhoreg
authored
Merge pull request #2536 from uhoreg/cross-signing-spec
initial spec for cross-signing
2 parents ba6a72f + c56c6a2 commit f352de9

File tree

13 files changed

+665
-8
lines changed

13 files changed

+665
-8
lines changed

‎api/client-server/cross_signing.yaml‎

Lines changed: 224 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,224 @@
1+
# Copyright 2020 The Matrix.org Foundation C.I.C.
2+
#
3+
# Licensed under the Apache License, Version 2.0 (the "License");
4+
# you may not use this file except in compliance with the License.
5+
# You may obtain a copy of the License at
6+
#
7+
# http://www.apache.org/licenses/LICENSE-2.0
8+
#
9+
# Unless required by applicable law or agreed to in writing, software
10+
# distributed under the License is distributed on an "AS IS" BASIS,
11+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
# See the License for the specific language governing permissions and
13+
# limitations under the License.
14+
swagger: '2.0'
15+
info:
16+
title: "Matrix Client-Server Cross Signing API"
17+
version: "1.0.0"
18+
host: localhost:8008
19+
schemes:
20+
- https
21+
- http
22+
basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
23+
consumes:
24+
- application/json
25+
produces:
26+
- application/json
27+
securityDefinitions:
28+
$ref: definitions/security.yaml
29+
paths:
30+
"/keys/device_signing/upload":
31+
post:
32+
summary: Upload cross-signing keys.
33+
description: |-
34+
Publishes cross-signing keys for the user.
35+
36+
This API endpoint uses the `User-Interactive Authentication API`_.
37+
operationId: uploadCrossSigningKeys
38+
security:
39+
- accessToken: []
40+
parameters:
41+
- in: body
42+
name: keys
43+
description: |-
44+
The keys to be published.
45+
schema:
46+
type: object
47+
properties:
48+
master_key:
49+
description: |-
50+
Optional. The user\'s master key.
51+
allOf:
52+
- $ref: definitions/cross_signing_key.yaml
53+
self_signing_key:
54+
description: |-
55+
Optional. The user\'s self-signing key. Must be signed by
56+
the accompanying master key, or by the user\'s most recently
57+
uploaded master key if no master key is included in the
58+
request.
59+
allOf:
60+
- $ref: definitions/cross_signing_key.yaml
61+
user_signing_key:
62+
description: |-
63+
Optional. The user\'s user-signing key. Must be signed by
64+
the accompanying master key, or by the user\'s most recently
65+
uploaded master key if no master key is included in the
66+
request.
67+
allOf:
68+
- $ref: definitions/cross_signing_key.yaml
69+
example: {
70+
"master_key": {
71+
"user_id": "@alice:example.com",
72+
"usage": ["master"],
73+
"keys": {
74+
"ed25519:base64+master+public+key": "base64+master+public+key",
75+
}
76+
},
77+
"self_signing_key": {
78+
"user_id": "@alice:example.com",
79+
"usage": ["self_signing"],
80+
"keys": {
81+
"ed25519:base64+self+signing+public+key": "base64+self+signing+master+public+key",
82+
},
83+
"signatures": {
84+
"@alice:example.com": {
85+
"ed25519:base64+master+public+key": "signature+of+self+signing+key"
86+
}
87+
}
88+
},
89+
"user_signing_key": {
90+
"user_id": "@alice:example.com",
91+
"usage": ["user_signing"],
92+
"keys": {
93+
"ed25519:base64+user+signing+public+key": "base64+user+signing+master+public+key",
94+
},
95+
"signatures": {
96+
"@alice:example.com": {
97+
"ed25519:base64+master+public+key": "signature+of+user+signing+key"
98+
}
99+
}
100+
}
101+
}
102+
responses:
103+
200:
104+
description: The provided keys were successfully uploaded.
105+
schema:
106+
type: object
107+
example: {}
108+
400:
109+
description: |-
110+
The input was invalid in some way. This can include one of the
111+
following error codes:
112+
113+
* ``M_INVALID_SIGNATURE``: For example, the self-signing or
114+
user-signing key had an incorrect signature.
115+
* ``M_MISSING_PARAM``: No master key is available.
116+
schema:
117+
type: object
118+
example: {
119+
"errcode": "M_INVALID_SIGNATURE",
120+
"error": "Invalid signature"
121+
}
122+
403:
123+
description: |-
124+
The public key of one of the keys is the same as one of the user\'s
125+
device IDs, or the request is not authorized for any other reason.
126+
schema:
127+
type: object
128+
example: {
129+
"errcode": "M_FORBIDDEN",
130+
"error": "Key ID in use"
131+
}
132+
"/keys/signatures/upload":
133+
post:
134+
summary: Upload cross-signing signatures.
135+
description: |-
136+
Publishes cross-signing signatures for the user. The request body is a
137+
map from user ID to key ID to signed JSON object.
138+
operationId: uploadCrossSigningSignatures
139+
security:
140+
- accessToken: []
141+
parameters:
142+
- in: body
143+
name: signatures
144+
description: |-
145+
The signatures to be published.
146+
schema:
147+
type: object
148+
title: Signatures
149+
additionalProperties:
150+
type: object
151+
additionalProperties:
152+
type: object
153+
example: {
154+
"@alice:example.com": {
155+
"HIJKLMN": {
156+
"user_id": "@alice:example.com",
157+
"device_id": "HIJKLMN",
158+
"algorithms": [
159+
"m.olm.curve25519-aes-sha256",
160+
"m.megolm.v1.aes-sha"
161+
],
162+
"keys": {
163+
"curve25519:HIJKLMN": "base64+curve25519+key",
164+
"ed25519:HIJKLMN": "base64+ed25519+key"
165+
},
166+
"signatures": {
167+
"@alice:example.com": {
168+
"ed25519:base64+self+signing+public+key": "base64+signature+of+HIJKLMN"
169+
}
170+
}
171+
},
172+
"base64+master+public+key": {
173+
"user_id": "@alice:example.com",
174+
"usage": ["master"],
175+
"keys": {
176+
"ed25519:base64+master+public+key": "base64+master+public+key"
177+
},
178+
"signatures": {
179+
"@alice:example.com": {
180+
"ed25519:HIJKLMN": "base64+signature+of+master+key"
181+
}
182+
}
183+
}
184+
},
185+
"@bob:example.com": {
186+
"bobs+base64+master+public+key": {
187+
"user_id": "@bob:example.com",
188+
"keys": {
189+
"ed25519:bobs+base64+master+public+key": "bobs+base64+master+public+key"
190+
},
191+
"usage": ["master"],
192+
"signatures": {
193+
"@alice:example.com": {
194+
"ed25519:base64+user+signing+public+key": "base64+signature+of+bobs+master+key"
195+
}
196+
}
197+
}
198+
}
199+
}
200+
responses:
201+
200:
202+
description: The provided signatures were processed.
203+
schema:
204+
type: object
205+
properties:
206+
failures:
207+
type: object
208+
description: |-
209+
A map from user ID to key ID to an error for any signatures
210+
that failed. If a signature was invalid, the ``errcode`` will
211+
be set to ``M_INVALID_SIGNATURE``.
212+
additionalProperties:
213+
type: object
214+
additionalProperties:
215+
type: object
216+
title: Error
217+
example: {
218+
"@alice:example.com": {
219+
"HIJKLMN": {
220+
"errcode": "M_INVALID_SIGNATURE",
221+
"error": "Invalid signature"
222+
}
223+
}
224+
}

‎api/client-server/definitions/cross_signing_key.yaml‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
# Copyright 2020 The Matrix.org Foundation C.I.C.
2+
#
3+
# Licensed under the Apache License, Version 2.0 (the "License");
4+
# you may not use this file except in compliance with the License.
5+
# You may obtain a copy of the License at
6+
#
7+
# http://www.apache.org/licenses/LICENSE-2.0
8+
#
9+
# Unless required by applicable law or agreed to in writing, software
10+
# distributed under the License is distributed on an "AS IS" BASIS,
11+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
# See the License for the specific language governing permissions and
13+
# limitations under the License.
14+
type: object
15+
title: CrossSigningKey
16+
description: Cross signing key
17+
properties:
18+
user_id:
19+
type: string
20+
description: |-
21+
The ID of the user the key belongs to.
22+
example: "@alice:example.com"
23+
usage:
24+
type: array
25+
description: |-
26+
What the key is used for.
27+
items:
28+
type: string
29+
enum: ["master", "self_signing", "user_signing"]
30+
keys:
31+
type: object
32+
additionalProperties:
33+
type: string
34+
description: |-
35+
The public key. The object must have exactly one property, whose name is
36+
in the form ``<algorithm>:<unpadded_base64_public_key>``, and whose value
37+
is the unpadded base64 public key.
38+
example:
39+
"ed25519:alice+base64+public+key": "alice+base64+public+key"
40+
signatures:
41+
type: object
42+
title: Signatures
43+
description: |-
44+
Signatures of the key, calculated using the process described at `Signing
45+
JSON`_. Optional for the master key. Other keys must be signed by the
46+
user\'s master key.
47+
example: {
48+
"@alice:example.com": {
49+
"ed25519:alice+base64+master+key": "signature+of+key"
50+
}
51+
}
52+
required:
53+
- user_id
54+
- usage
55+
- keys

‎api/client-server/keys.yaml‎

Lines changed: 71 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
# Copyright 2016 OpenMarket Ltd
22
# Copyright 2018 New Vector Ltd
3+
# Copyright 2020 The Matrix.org Foundation C.I.C.
34
#
45
# Licensed under the Apache License, Version 2.0 (the "License");
56
# you may not use this file except in compliance with the License.
@@ -236,7 +237,76 @@ paths:
236237
"device_display_name": "Alice's mobile phone"
237238
}
238239
}
239-
240+
master_keys:
241+
type: object
242+
description: |-
243+
Information on the master cross-signing keys of the queried users.
244+
A map from user ID, to master key information. For each key, the
245+
information returned will be the same as uploaded via
246+
``/keys/device_signing/upload``, along with the signatures
247+
uploaded via ``/keys/signatures/upload`` that the requesting user
248+
is allowed to see.
249+
additionalProperties:
250+
allOf:
251+
- $ref: definitions/cross_signing_key.yaml
252+
example: {
253+
"@alice:example.com": {
254+
"user_id": "@alice:example.com",
255+
"usage": ["master"],
256+
"keys": {
257+
"ed25519:base64+master+public+key": "base64+master+public+key",
258+
}
259+
}
260+
}
261+
self_signing_keys:
262+
type: object
263+
description: |-
264+
Information on the self-signing keys of the queried users. A map
265+
from user ID, to self-signing key information. For each key, the
266+
information returned will be the same as uploaded via
267+
``/keys/device_signing/upload``.
268+
additionalProperties:
269+
allOf:
270+
- $ref: definitions/cross_signing_key.yaml
271+
example: {
272+
"@alice:example.com": {
273+
"user_id": "@alice:example.com",
274+
"usage": ["self_signing"],
275+
"keys": {
276+
"ed25519:base64+self+signing+public+key": "base64+self+signing+master+public+key",
277+
},
278+
"signatures": {
279+
"@alice:example.com": {
280+
"ed25519:base64+master+public+key": "signature+of+self+signing+key"
281+
}
282+
}
283+
}
284+
}
285+
user_signing_keys:
286+
type: object
287+
description: |-
288+
Information on the user-signing key of the user making the
289+
request, if they queried their own device information. A map
290+
from user ID, to user-signing key information. The
291+
information returned will be the same as uploaded via
292+
``/keys/device_signing/upload``.
293+
additionalProperties:
294+
allOf:
295+
- $ref: definitions/cross_signing_key.yaml
296+
example: {
297+
"@alice:example.com": {
298+
"user_id": "@alice:example.com",
299+
"usage": ["user_signing"],
300+
"keys": {
301+
"ed25519:base64+user+signing+public+key": "base64+user+signing+master+public+key",
302+
},
303+
"signatures": {
304+
"@alice:example.com": {
305+
"ed25519:base64+master+public+key": "signature+of+user+signing+key"
306+
}
307+
}
308+
}
309+
}
240310
tags:
241311
- End-to-end encryption
242312
"/keys/claim":

‎api/client-server/login.yaml‎

Lines changed: 7 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -123,8 +123,10 @@ paths:
123123
type: string
124124
description: |-
125125
ID of the client device. If this does not correspond to a
126-
known client device, a new device will be created. The server
127-
will auto-generate a device_id if this is not specified.
126+
known client device, a new device will be created. The given
127+
device ID must not be the same as a `cross-signing key ID
128+
<#cross-signing>`_. The server will auto-generate a device_id
129+
if this is not specified.
128130
initial_device_display_name:
129131
type: string
130132
description: |-
@@ -195,7 +197,9 @@ paths:
195197
403:
196198
description: |-
197199
The login attempt failed. This can include one of the following error codes:
198-
* ``M_FORBIDDEN``: The provided authentication data was incorrect.
200+
* ``M_FORBIDDEN``: The provided authentication data was incorrect
201+
or the requested device ID is the same as a cross-signing key
202+
ID.
199203
* ``M_USER_DEACTIVATED``: The user has been deactivated.
200204
examples:
201205
application/json: {

0 commit comments

Comments
 (0)