initial spec for cross-signing

api/server-server/definitions/event-schemas/m.device_list_update.yaml

@@ -1,4 +1,5 @@
 # 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.
@@ -17,7 +18,8 @@ title: m.device_list_update
 description: |-
   An EDU that lets servers push details to each other when one of their users
   adds a new device to their account, required for E2E encryption to correctly
-  target the current set of devices for a given user.
+  target the current set of devices for a given user. This event will also be
+  sent when an existing device gets a new cross-signing signature.
 
 # FIXME: It's very unclear why we have this API surface for synchronising
 # device lists, rather than just using a room (which could also be used for

api/server-server/definitions/event-schemas/m.signing_key_update.yaml

@@ -0,0 +1,68 @@
+# 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
+            allOf:
+              - $ref: ../../../client-server/definitions/cross_signing_key.yaml
+              # FIXME: why isn't the doc generator picking up this example?
+              - 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"
+                    }
+                  }
+                }
+          self_signing_key:
+            type: object
+            allOf:
+              - $ref: ../../../client-server/definitions/cross_signing_key.yaml
+              # FIXME: why isn't the doc generator picking up this example?
+              - example: {
+                  "user_id": "@alice:example.com",
+                  "usage": ["master"],
+                  "keys": {
+                    "ed25519:base64+master+public+key": "base64+master+public+key",
+                  }
+                }
+        required:
+          - user_id

api/server-server/user_devices.yaml

@@ -1,4 +1,5 @@
 # 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.
@@ -81,4 +82,37 @@ paths:
                       description: Optional display name for the device.
                       example: "Alice's Mobile Phone"
                   required: ['device_id', 'keys']
+              master_key:
+                type: object
+                description: |-
+                  The user\'s master cross-signing key.
+                allOf:
+                  - $ref: ../client-server/definitions/cross_signing_key.yaml
+                  # FIXME: why isn't the doc generator picking up this example?
+                  - example: {
+                      "user_id": "@alice:example.com",
+                      "usage": ["master"],
+                      "keys": {
+                        "ed25519:base64+master+public+key": "base64+master+public+key",
+                      }
+                    }
+              self_signing_keys:
+                type: object
+                description: |-
+                  The user\'s self-signing key.
+                allOf:
+                  - $ref: ../client-server/definitions/cross_signing_key.yaml
+                  # FIXME: why isn't the doc generator picking up this example?
+                  - 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', 'stream_id', 'devices']

api/server-server/user_keys.yaml

@@ -1,4 +1,5 @@
 # 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.
@@ -171,6 +172,49 @@ paths:
                             type: string
                             description:
                               The display name which the user set on the device.
+              master_keys:
+                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``.
+                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:
+                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:
             application/json: {