Merge pull request #2083 from matrix-org/travis/1.0/key-object

Clarify the key object definition for the key management API

api/client-server/keys.yaml

@@ -56,25 +56,48 @@ paths:
                   One-time public keys for "pre-key" messages.  The names of
                   the properties should be in the format
                   ``<algorithm>:<key_id>``. The format of the key is determined
-                  by the key algorithm.
+                  by the `key algorithm <#key-algorithms>`_.
 
                   May be absent if no new one-time keys are required.
                 additionalProperties:
                   type:
                     - string
                     - object
-                example:
+                    # XXX: We can't define an actual object here, so we have to hope
-                  "curve25519:AAAAAQ": "/qyvZvwjiTxGdGU0RCguDCLeR+nmsb3FfNG3/Ve4vU8"
+                    # that people will look at the swagger source or can figure it out
-                  signed_curve25519:AAAAHg:
+                    # from the other endpoints/example.
-                    key: "zKbLg+NrIjpnagy+pIY6uPL4ZwEG2v+8F9lmgsnlZzs"
+                    # - type: object
-                    signatures:
+                    #   title: KeyObject
-                      "@alice:example.com":
+                    #   properties:
-                        ed25519:JLAFKJWSCS: "FLWxXqGbwrb8SM3Y795eB6OA8bwBcoMZFXBqnTn58AYWZSqiD45tlBVcDa2L7RwdKXebW/VzDlnfVJ+9jok1Bw"
+                    #     key:
-                  signed_curve25519:AAAAHQ:
+                    #       type: string
-                    key: "j3fR3HemM16M7CWhoI4Sk5ZsdmdfQHsKL1xuSft6MSw"
+                    #       description: The key, encoded using unpadded base64.
-                    signatures:
+                    #     signatures:
-                      "@alice:example.com":
+                    #       type: object
-                        ed25519:JLAFKJWSCS: "IQeCEPb9HFk217cU9kw9EOiusC6kMIkoIRnbnfOh5Oc63S1ghgyjShBGpu34blQomoalCyXWyhaaT3MrLZYQAA"
+                    #       description: |-
+                    #         Signature for the device. Mapped from user ID to signature object.
+                    #       additionalProperties:
+                    #         type: string
+                    #   required: ['key', 'signatures']
+                example: {
+                  "curve25519:AAAAAQ": "/qyvZvwjiTxGdGU0RCguDCLeR+nmsb3FfNG3/Ve4vU8",
+                  "signed_curve25519:AAAAHg": {
+                    "key": "zKbLg+NrIjpnagy+pIY6uPL4ZwEG2v+8F9lmgsnlZzs",
+                    "signatures": {
+                      "@alice:example.com": {
+                        "ed25519:JLAFKJWSCS": "FLWxXqGbwrb8SM3Y795eB6OA8bwBcoMZFXBqnTn58AYWZSqiD45tlBVcDa2L7RwdKXebW/VzDlnfVJ+9jok1Bw"
+                      }
+                    }
+                  },
+                  "signed_curve25519:AAAAHQ": {
+                    "key": "j3fR3HemM16M7CWhoI4Sk5ZsdmdfQHsKL1xuSft6MSw",
+                    "signatures": {
+                      "@alice:example.com": {
+                        "ed25519:JLAFKJWSCS": "IQeCEPb9HFk217cU9kw9EOiusC6kMIkoIRnbnfOh5Oc63S1ghgyjShBGpu34blQomoalCyXWyhaaT3MrLZYQAA"
+                      }
+                    }
+                  }
+                }
       responses:
         200:
           description:
@@ -246,8 +269,9 @@ paths:
                     type: string
                     description: algorithm
                     example: "signed_curve25519"
-                example:
+                example: {
                   "@alice:example.com": { "JLAFKJWSCS": "signed_curve25519" }
+                }
             required:
               - one_time_keys
       responses:
@@ -275,20 +299,46 @@ paths:
                 description: |-
                   One-time keys for the queried devices. A map from user ID, to a
                   map from devices to a map from ``<algorithm>:<key_id>`` to the key object.
+
+                  See the `key algorithms <#key-algorithms>`_ section for information
+                  on the Key Object format.
                 additionalProperties:
                   type: object
                   additionalProperties:
                     type:
                       - string
                       - object
-                example:
+                      # XXX: We can't define an actual object here, so we have to hope
-                  "@alice:example.com":
+                      # that people will look at the swagger source or can figure it out
-                    JLAFKJWSCS:
+                      # from the other endpoints/example.
-                      signed_curve25519:AAAAHg:
+                      # - type: object
-                        key: "zKbLg+NrIjpnagy+pIY6uPL4ZwEG2v+8F9lmgsnlZzs"
+                      #   title: KeyObject
-                        signatures:
+                      #   properties:
-                          "@alice:example.com":
+                      #     key:
-                            ed25519:JLAFKJWSCS: "FLWxXqGbwrb8SM3Y795eB6OA8bwBcoMZFXBqnTn58AYWZSqiD45tlBVcDa2L7RwdKXebW/VzDlnfVJ+9jok1Bw"
+                      #       type: string
+                      #       description: The key, encoded using unpadded base64.
+                      #     signatures:
+                      #       type: object
+                      #       description: |-
+                      #         Signature for the device. Mapped from user ID to signature object.
+                      #       additionalProperties:
+                      #         type: string
+                      #   required: ['key', 'signatures']
+                example: {
+                  "@alice:example.com": {
+                    "JLAFKJWSCS": {
+                      "signed_curve25519:AAAAHg": {
+                        "key": "zKbLg+NrIjpnagy+pIY6uPL4ZwEG2v+8F9lmgsnlZzs",
+                        "signatures": {
+                          "@alice:example.com": {
+                            "ed25519:JLAFKJWSCS": "FLWxXqGbwrb8SM3Y795eB6OA8bwBcoMZFXBqnTn58AYWZSqiD45tlBVcDa2L7RwdKXebW/VzDlnfVJ+9jok1Bw"
+                          }
+                        }
+                      }
+                    }
+                  }
+                }
+            required: ['one_time_keys']
       tags:
         - End-to-end encryption
   "/keys/changes":

api/server-server/user_keys.yaml

@@ -72,30 +72,42 @@ paths:
                 description: |-
                   One-time keys for the queried devices. A map from user ID, to a
                   map from devices to a map from ``<algorithm>:<key_id>`` to the key object.
+
+                  See the Client-Server Key Algorithms section for more information on
+                  the Key Object format.
                 additionalProperties:
                   type: object
                   additionalProperties:
                     type:
                       - string
-                      - object
+                      - type: object
-            required: ['one_time_keys']
+                        title: KeyObject
-          examples:
+                        properties:
-            application/json: {
+                          key:
-              "one_time_keys": {
+                            type: string
-                "@alice:example.com": {
+                            description: The key, encoded using unpadded base64.
-                  "JLAFKJWSCS": {
+                          signatures:
-                    "signed_curve25518:AAAAHg": {
+                            type: object
-                      "key": "zKbLg+NrIjpnagy+pIY6uPL4ZwEG2v+8F9lmgsnlZzs",
+                            description: |-
-                      "signatures": {
+                              Signature for the device. Mapped from user ID to signature object.
-                        "@alice:example.com": {
+                            additionalProperties:
-                          "ed25519:JLAFKJWSCS": "FLWxXqGbwrb8SM3Y795eB6OA8bwBcoMZFXBqnTn58AYWZSqiD45tlBVcDa2L7RwdKXebW/VzDlnfVJ+9jok1Bw"
+                              type: string
+                        required: ['key', 'signatures']
+                example: {
+                  "@alice:example.com": {
+                    "JLAFKJWSCS": {
+                      "signed_curve25519:AAAAHg": {
+                        "key": "zKbLg+NrIjpnagy+pIY6uPL4ZwEG2v+8F9lmgsnlZzs",
+                        "signatures": {
+                          "@alice:example.com": {
+                            "ed25519:JLAFKJWSCS": "FLWxXqGbwrb8SM3Y795eB6OA8bwBcoMZFXBqnTn58AYWZSqiD45tlBVcDa2L7RwdKXebW/VzDlnfVJ+9jok1Bw"
+                          }
                         }
                       }
                     }
                   }
                 }
-              }
+            required: ['one_time_keys']
-            }
   "/user/keys/query":
     post:
       summary: Download device identity keys.

changelogs/client_server/newsfragments/2083.clarification

@@ -0,0 +1 @@
+Clarify the key object definition for the key management API.

changelogs/server_server/newsfragments/2083.clarification

@@ -0,0 +1 @@
+Clarify the key object definition for the key management API.