apply suggestions from review

api/client-server/cross_signing.yaml

@@ -110,16 +110,25 @@ paths:
             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.
+            * ``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 unauthorized.
+          schema:
+            type: object
+            example: {
+              "errcode": "M_FORBIDDEN",
+              "error": "Key ID in use"
+            }
   "/keys/signatures/upload":
     post:
       summary: Upload cross-signing signatures.

api/client-server/login.yaml

@@ -123,8 +123,10 @@ paths:
                 type: string
                 description: |-
                   ID of the client device. If this does not correspond to a
-                  known client device, a new device will be created. The server
-                  will auto-generate a device_id if this is not specified.
+                  known client device, a new device will be created. The given
+                  device ID must not be the same as a `cross-signing key ID
+                  <#cross-signing>`_. The server will auto-generate a device_id
+                  if this is not specified.
               initial_device_display_name:
                 type: string
                 description: |-
@@ -195,7 +197,9 @@ paths:
         403:
           description: |-
             The login attempt failed. This can include one of the following error codes:
-              * ``M_FORBIDDEN``: The provided authentication data was incorrect.
+              * ``M_FORBIDDEN``: The provided authentication data was incorrect
+                or the requested device ID is the same as a cross-signing key
+                ID.
               * ``M_USER_DEACTIVATED``: The user has been deactivated.
           examples:
             application/json: {

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

@@ -37,10 +37,18 @@ allOf:
             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: {
+            $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": {
@@ -52,17 +60,5 @@ allOf:
                 }
               }
             }
-          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

specification/modules/end_to_end_encryption.rst

@@ -848,13 +848,13 @@ that she cannot see:
    | +------+       |                                         |       +----+ |
    +----------------+                                         +--------------+
 
-Verification methods can be used to verify a user's master key by using the
-master public key, encoded using unpadded base64, as the device ID, and
-treating it as a normal device. For example, if Alice and Bob verify each other
-using SAS, Alice's ``m.key.verification.mac`` message to Bob may include
-``"ed25519:alices+master+public+key": "alices+master+public+key"`` in the ``mac``
-property. Servers therefore must ensure that device IDs will not collide with
-cross-signing public keys.
+`Verification methods <#device-verification>`_ can be used to verify a user's
+master key by using the master public key, encoded using unpadded base64, as
+the device ID, and treating it as a normal device. For example, if Alice and
+Bob verify each other using SAS, Alice's ``m.key.verification.mac`` message to
+Bob may include ``"ed25519:alices+master+public+key":
+"alices+master+public+key"`` in the ``mac`` property. Servers therefore must
+ensure that device IDs will not collide with cross-signing public keys.
 
 Key and signature security
 <<<<<<<<<<<<<<<<<<<<<<<<<<