Merge pull request #2536 from uhoreg/cross-signing-spec
initial spec for cross-signingpull/2951/head
Hubert Chathi
3 years ago
committed by
GitHub
commit
f352de90c3
@ -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:
|
||||
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"
|
||||
}
|
||||
}
|
||||
}
|
||||
@ -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
|
||||
@ -0,0 +1,64 @@
|
||||
# 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: m.signing_key_update
|
||||
description: |-
|
||||
An EDU that lets servers push details to each other when one of their users
|
||||
updates their cross-signing keys.
|
||||
allOf:
|
||||
- $ref: ../edu.yaml
|
||||
- type: object
|
||||
properties:
|
||||
edu_type:
|
||||
type: enum
|
||||
enum: ['m.signing_key_update']
|
||||
description: The string ``m.signing_update``.
|
||||
example: "m.signing_key_update"
|
||||
content:
|
||||
type: object
|
||||
description: The updated signing keys.
|
||||
title: Signing Key Update
|
||||
properties:
|
||||
user_id:
|
||||
type: string
|
||||
description: The user ID whose cross-signing keys have changed.
|
||||
example: "@alice:example.com"
|
||||
master_key:
|
||||
type: object
|
||||
$ref: ../../../client-server/definitions/cross_signing_key.yaml
|
||||
example: {
|
||||
"user_id": "@alice:example.com",
|
||||
"usage": ["master"],
|
||||
"keys": {
|
||||
"ed25519:base64+master+public+key": "base64+master+public+key",
|
||||
}
|
||||
}
|
||||
self_signing_key:
|
||||
type: object
|
||||
$ref: ../../../client-server/definitions/cross_signing_key.yaml
|
||||
example: {
|
||||
"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:
|
||||
- user_id
|
||||
@ -0,0 +1 @@
|
||||
Add cross-signing properties to the response of ``POST /keys/query`` per [MSC1756](https://github.com/matrix-org/matrix-doc/pull/1756).
|
||||
@ -0,0 +1 @@
|
||||
Add ``POST /keys/device_signing/upload`` and ``POST /keys/signatures/upload`` per [MSC1756](https://github.com/matrix-org/matrix-doc/pull/1756).
|
||||
@ -0,0 +1,9 @@
|
||||
Add cross-signing:
|
||||
|
||||
- Add properties to the response of ``GET /user/keys`` and ``GET
|
||||
/user/devices/{userId}``.
|
||||
- The ``m.device_list_update`` EDU is sent when a device gets a new signature.
|
||||
- A new ``m.signing_key_update`` EDU is sent when a user's cross-signing keys
|
||||
are changed.
|
||||
|
||||
per [MSC1756](https://github.com/matrix-org/matrix-doc/pull/1756).
|
||||
Loading…
Reference in New Issue