initial spec for cross-signing

api/client-server/cross_signing.yaml

@@ -0,0 +1,215 @@
+# 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 with
+                  the accompanied master, 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 with
+                  the accompanied master, 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``: The self-signing or user-signing key
+              had an incorrect signature
+            * ``M_FORBIDDEN``: The public key of one of the keys is the same as
+              one of the user\'s device IDs.
+          schema:
+            type: object
+            example: {
+              "errcode": "M_INVALID_SIGNATURE",
+              "error": "Invalid signature"
+            }
+  "/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"
+                    }
+                  }
+                }

api/client-server/definitions/cross_signing_key.yaml

@@ -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

api/client-server/keys.yaml

@@ -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:
+                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":

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