Merge pull request #2566 from uhoreg/remove_string_string_string

E2E clarifications/improvements

api/client-server/definitions/device_keys.yaml

@@ -47,6 +47,7 @@ properties:
       "ed25519:JLAFKJWSCS": "lEuiRJBit0IG6nUf5pUzWTUEsRVVe/HJkoKuEww9ULI"
   signatures:
     type: object
+    title: Signatures
     description: |-
        Signatures for the device key object. A map from user ID, to a map from
        ``<algorithm>:<device_id>`` to the signature.

api/client-server/definitions/third_party_signed.yaml

@@ -33,6 +33,10 @@ properties:
     type: object
     description: A signatures object containing a signature of the entire signed object.
     title: Signatures
+    additionalProperties:
+      type: object
+      additionalProperties:
+        type: string
     example: {
       "example.org": {
         "ed25519:0": "some9signature"

api/server-server/definitions/keys.yaml

@@ -75,18 +75,16 @@ properties:
       required: ["expired_ts", "key"]
   signatures:
     type: object
-    description: Digital signatures for this object signed using the ``verify_keys``.
+    description: |-
+      Digital signatures for this object signed using the ``verify_keys``.
+
+      The signature is calculated using the process described at `Signing
+      JSON`_.
+    title: Signatures
     additionalProperties:
       type: object
-      title: Signed Server
-      example: {
-        "example.org": {
-          "ad25519:abc123": "VGhpcyBzaG91bGQgYWN0dWFsbHkgYmUgYSBzaWduYXR1cmU"
-        }
-      }
       additionalProperties:
         type: string
-        name: Encoded Signature Verification Key
   valid_until_ts:
     type: integer
     format: int64

api/server-server/third_party_invite.yaml

@@ -102,12 +102,16 @@ paths:
                         properties:
                           signatures:
                             type: object
-                            description: The server signatures for this event.
+                            title: Signatures
                             additionalProperties:
                               type: object
-                              title: Server Signatures
                               additionalProperties:
                                 type: string
+                            description: |-
+                              The server signatures for this event.
+
+                              The signature is calculated using the process
+                              described at `Signing JSON`_.
                             example: {
                               "magic.forest": {
                                 "ed25519:3": "fQpGIW1Snz+pwLZu6sTy2aHy/DYWWTspTJRPyNp0PKkymfIsNffysMl6ObMMFdIJhk6g6pwlIqZ54rxo8SLmAg"

api/server-server/user_keys.yaml

@@ -73,7 +73,7 @@ paths:
                   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
+                  See the `Client-Server Key Algorithms`_ section for more information on
                   the Key Object format.
                 additionalProperties:
                   type: object
@@ -88,10 +88,16 @@ paths:
                             description: The key, encoded using unpadded base64.
                           signatures:
                             type: object
-                            description: |-
+                            title: Signatures
-                              Signature for the device. Mapped from user ID to signature object.
                             additionalProperties:
-                              type: string
+                              type: object
+                              additionalProperties:
+                                type: string
+                            description: |-
+                              Signature of the key object.
+
+                              The signature is calculated using the process described at `Signing
+                              JSON`_.
                         required: ['key', 'signatures']
                 example: {
                   "@alice:example.com": {

changelogs/client_server/newsfragments/2566.clarification

@@ -0,0 +1 @@
+Clarify signature object structures for encryption.

changelogs/server_server/newsfragments/2566.clarification

@@ -0,0 +1 @@
+Clarify signature object structures for encryption.

event-schemas/schema/m.room.member

@@ -82,6 +82,10 @@ properties:
                 description: 'A single signature from the verifying server, in the format specified by the Signing Events section of the server-server API.'
                 title: Signatures
                 type: object
+                additionalProperties:
+                  type: object
+                  additionalProperties:
+                    type: string
               token:
                 description: The token property of the containing third_party_invite object.
                 type: string

scripts/templating/matrix_templates/units.py

@@ -213,6 +213,7 @@ def get_json_schema_object_fields(obj, enforce_title=False):
         res = process_data_type(additionalProps)
         tables = res["tables"]
         val_title = res["title"]
+        gen_title = "{%s: %s}" % (key_type, val_title)
         if res.get("enum_desc") and val_title != "enum":
             # A map to enum needs another table with enum description
             tables.append(TypeTable(
@@ -220,7 +221,7 @@ def get_json_schema_object_fields(obj, enforce_title=False):
                 rows=[TypeTableRow(key="(mapped value)", title="enum", desc=res["desc"])]
             ))
         return {
-            "title": "{%s: %s}" % (key_type, val_title),
+            "title": obj_title if obj_title else gen_title,
             "tables": tables,
         }
 

specification/modules/end_to_end_encryption.rst

@@ -83,9 +83,23 @@ Base64`_. Example:
   "JGLn/yafz74HB2AbPLYJWIVGnKAtqECOBf11yyXac2Y"
 
 The name ``signed_curve25519`` also corresponds to the Curve25519 algorithm,
-but keys using this algorithm are objects with the properties ``key`` (giving
+but a key using this algorithm is represented by an object with a the following
-the Base64-encoded 32-byte Curve25519 public key), and ``signatures`` (giving a
+properties:
-signature for the key object, as described in `Signing JSON`_). Example:
+
+``KeyObject``
+
+========== ================ =====================================================
+Parameter  Type             Description
+========== ================ =====================================================
+key        string           **Required.** The unpadded Base64-encoded 32-byte
+                            Curve25519 public key.
+signatures Signatures       **Required.** Signatures of the key object.
+
+                            The signature is calculated using the process described
+                            at `Signing JSON`_.
+========== ================ =====================================================
+
+Example:
 
 .. code:: json
 

specification/server_server_api.rst

@@ -1257,3 +1257,4 @@ issue.
 .. _`Device Management module`: ../client_server/%CLIENT_RELEASE_LABEL%.html#device-management
 .. _`End-to-End Encryption module`: ../client_server/%CLIENT_RELEASE_LABEL%.html#end-to-end-encryption
 .. _`room version specification`: ../index.html#room-versions
+.. _`Client-Server Key Algorithms`: ../client_server/%CLIENT_RELEASE_LABEL%.html#key-algorithms