Merge pull request #2536 from uhoreg/cross-signing-spec
initial spec for cross-signingpull/977/head
Hubert Chathi
4 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