-
Notifications
You must be signed in to change notification settings - Fork 376
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
initial spec for cross-signing #2536
Changes from all commits
a8910fe
f97b394
67edc3e
ec0b9ba
be01eeb
efebba6
902444c
c8e816d
a5ebedc
c56c6a2
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,224 @@ | ||
# 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 Client-Server Cross Signing API" | ||
version: "1.0.0" | ||
host: localhost:8008 | ||
schemes: | ||
- https | ||
- http | ||
basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% | ||
consumes: | ||
- application/json | ||
produces: | ||
- application/json | ||
securityDefinitions: | ||
$ref: definitions/security.yaml | ||
paths: | ||
"/keys/device_signing/upload": | ||
post: | ||
summary: Upload cross-signing keys. | ||
description: |- | ||
Publishes cross-signing keys for the user. | ||
This API endpoint uses the `User-Interactive Authentication API`_. | ||
operationId: uploadCrossSigningKeys | ||
security: | ||
- accessToken: [] | ||
parameters: | ||
- in: body | ||
name: keys | ||
description: |- | ||
The keys to be published. | ||
schema: | ||
type: object | ||
properties: | ||
master_key: | ||
description: |- | ||
Optional. The user\'s master key. | ||
allOf: | ||
- $ref: definitions/cross_signing_key.yaml | ||
self_signing_key: | ||
description: |- | ||
Optional. The user\'s self-signing key. Must be signed by | ||
the accompanying master key, or by the user\'s most recently | ||
uploaded master key if no master key is included in the | ||
request. | ||
allOf: | ||
- $ref: definitions/cross_signing_key.yaml | ||
user_signing_key: | ||
description: |- | ||
Optional. The user\'s user-signing key. Must be signed by | ||
the accompanying master key, or by the user\'s most recently | ||
uploaded master key if no master key is included in the | ||
request. | ||
allOf: | ||
- $ref: definitions/cross_signing_key.yaml | ||
example: { | ||
"master_key": { | ||
"user_id": "@alice:example.com", | ||
"usage": ["master"], | ||
"keys": { | ||
"ed25519:base64+master+public+key": "base64+master+public+key", | ||
} | ||
}, | ||
"self_signing_key": { | ||
"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" | ||
} | ||
} | ||
}, | ||
"user_signing_key": { | ||
"user_id": "@alice:example.com", | ||
"usage": ["user_signing"], | ||
"keys": { | ||
"ed25519:base64+user+signing+public+key": "base64+user+signing+master+public+key", | ||
}, | ||
"signatures": { | ||
"@alice:example.com": { | ||
"ed25519:base64+master+public+key": "signature+of+user+signing+key" | ||
} | ||
} | ||
} | ||
} | ||
responses: | ||
200: | ||
description: The provided keys were successfully uploaded. | ||
schema: | ||
type: object | ||
example: {} | ||
400: | ||
description: |- | ||
The input was invalid in some way. This can include one of the | ||
following error codes: | ||
* ``M_INVALID_SIGNATURE``: For example, the self-signing or | ||
user-signing key had an incorrect signature. | ||
* ``M_MISSING_PARAM``: No master key is available. | ||
schema: | ||
type: object | ||
example: { | ||
"errcode": "M_INVALID_SIGNATURE", | ||
"error": "Invalid signature" | ||
} | ||
403: | ||
description: |- | ||
The public key of one of the keys is the same as one of the user\'s | ||
device IDs, or the request is not authorized for any other reason. | ||
schema: | ||
type: object | ||
example: { | ||
"errcode": "M_FORBIDDEN", | ||
"error": "Key ID in use" | ||
} | ||
"/keys/signatures/upload": | ||
post: | ||
summary: Upload cross-signing signatures. | ||
description: |- | ||
Publishes cross-signing signatures for the user. The request body is a | ||
map from user ID to key ID to signed JSON object. | ||
operationId: uploadCrossSigningSignatures | ||
security: | ||
- accessToken: [] | ||
parameters: | ||
- in: body | ||
name: signatures | ||
description: |- | ||
The signatures to be published. | ||
schema: | ||
type: object | ||
title: Signatures | ||
additionalProperties: | ||
type: object | ||
additionalProperties: | ||
type: object | ||
example: { | ||
"@alice:example.com": { | ||
"HIJKLMN": { | ||
"user_id": "@alice:example.com", | ||
"device_id": "HIJKLMN", | ||
"algorithms": [ | ||
"m.olm.curve25519-aes-sha256", | ||
"m.megolm.v1.aes-sha" | ||
], | ||
"keys": { | ||
"curve25519:HIJKLMN": "base64+curve25519+key", | ||
"ed25519:HIJKLMN": "base64+ed25519+key" | ||
}, | ||
"signatures": { | ||
"@alice:example.com": { | ||
"ed25519:base64+self+signing+public+key": "base64+signature+of+HIJKLMN" | ||
} | ||
} | ||
}, | ||
"base64+master+public+key": { | ||
"user_id": "@alice:example.com", | ||
"usage": ["master"], | ||
"keys": { | ||
"ed25519:base64+master+public+key": "base64+master+public+key" | ||
}, | ||
"signatures": { | ||
"@alice:example.com": { | ||
"ed25519:HIJKLMN": "base64+signature+of+master+key" | ||
} | ||
} | ||
} | ||
}, | ||
"@bob:example.com": { | ||
"bobs+base64+master+public+key": { | ||
"user_id": "@bob:example.com", | ||
"keys": { | ||
"ed25519:bobs+base64+master+public+key": "bobs+base64+master+public+key" | ||
}, | ||
"usage": ["master"], | ||
"signatures": { | ||
"@alice:example.com": { | ||
"ed25519:base64+user+signing+public+key": "base64+signature+of+bobs+master+key" | ||
} | ||
} | ||
} | ||
} | ||
} | ||
responses: | ||
200: | ||
description: The provided signatures were processed. | ||
schema: | ||
type: object | ||
properties: | ||
failures: | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. nor this There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. This looks fine to me |
||
type: object | ||
description: |- | ||
A map from user ID to key ID to an error for any signatures | ||
that failed. If a signature was invalid, the ``errcode`` will | ||
be set to ``M_INVALID_SIGNATURE``. | ||
additionalProperties: | ||
type: object | ||
additionalProperties: | ||
type: object | ||
title: Error | ||
example: { | ||
"@alice:example.com": { | ||
"HIJKLMN": { | ||
"errcode": "M_INVALID_SIGNATURE", | ||
"error": "Invalid signature" | ||
} | ||
} | ||
} |
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,55 @@ | ||
# 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. | ||
type: object | ||
title: CrossSigningKey | ||
description: Cross signing key | ||
properties: | ||
user_id: | ||
type: string | ||
description: |- | ||
The ID of the user the key belongs to. | ||
example: "@alice:example.com" | ||
usage: | ||
type: array | ||
description: |- | ||
What the key is used for. | ||
items: | ||
type: string | ||
enum: ["master", "self_signing", "user_signing"] | ||
keys: | ||
type: object | ||
additionalProperties: | ||
type: string | ||
description: |- | ||
The public key. The object must have exactly one property, whose name is | ||
in the form ``<algorithm>:<unpadded_base64_public_key>``, and whose value | ||
is the unpadded base64 public key. | ||
example: | ||
"ed25519:alice+base64+public+key": "alice+base64+public+key" | ||
signatures: | ||
type: object | ||
title: Signatures | ||
description: |- | ||
Signatures of the key, calculated using the process described at `Signing | ||
JSON`_. Optional for the master key. Other keys must be signed by the | ||
user\'s master key. | ||
example: { | ||
"@alice:example.com": { | ||
"ed25519:alice+base64+master+key": "signature+of+key" | ||
} | ||
} | ||
required: | ||
- user_id | ||
- usage | ||
- keys |
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,5 +1,6 @@ | ||
# Copyright 2016 OpenMarket Ltd | ||
# 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. | ||
|
@@ -233,7 +234,76 @@ paths: | |
"device_display_name": "Alice's mobile phone" | ||
} | ||
} | ||
|
||
master_keys: | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Is there a way to only query the cross-signing keys? Is it sufficient to query only one device key of a user to them in the reply, or do you need to query all device keys of a user (empty list)? There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. No, there's no way to query just the cross-signing keys. Querying device is sufficient. The user's ID just needs to appear in the query. |
||
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 requesting user | ||
is allowed to see. | ||
additionalProperties: | ||
allOf: | ||
- $ref: 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: 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" | ||
} | ||
} | ||
} | ||
} | ||
user_signing_keys: | ||
type: object | ||
description: |- | ||
Information on the user-signing key of the user making the | ||
request, if they queried their own device information. A map | ||
from user ID, to user-signing key information. The | ||
information returned will be the same as uploaded via | ||
``/keys/device_signing/upload``. | ||
additionalProperties: | ||
allOf: | ||
- $ref: definitions/cross_signing_key.yaml | ||
example: { | ||
"@alice:example.com": { | ||
"user_id": "@alice:example.com", | ||
"usage": ["user_signing"], | ||
"keys": { | ||
"ed25519:base64+user+signing+public+key": "base64+user+signing+master+public+key", | ||
}, | ||
"signatures": { | ||
"@alice:example.com": { | ||
"ed25519:base64+master+public+key": "signature+of+user+signing+key" | ||
} | ||
} | ||
} | ||
} | ||
tags: | ||
- End-to-end encryption | ||
"/keys/claim": | ||
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
this isn't working in the rendered output, for some reason.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
It's because our generator wants the body to have a fixed set of properties, rather than being a mapping of IDs, so I don't think this can be fixed without making changes to the build system.