From 5b38c04e1921261dfe5eb7169068c1ef86a9cd33 Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Fri, 22 May 2020 15:50:32 -0400 Subject: [PATCH 1/5] make definition of signatures fields more consistent --- api/client-server/definitions/device_keys.yaml | 5 +---- api/server-server/definitions/keys.yaml | 18 ++++++------------ api/server-server/third_party_invite.yaml | 12 ++++++------ api/server-server/user_keys.yaml | 8 +++++--- 4 files changed, 18 insertions(+), 25 deletions(-) diff --git a/api/client-server/definitions/device_keys.yaml b/api/client-server/definitions/device_keys.yaml index 41504aba..ce770c09 100644 --- a/api/client-server/definitions/device_keys.yaml +++ b/api/client-server/definitions/device_keys.yaml @@ -47,16 +47,13 @@ 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 ``:`` to the signature. The signature is calculated using the process described at `Signing JSON`_. - additionalProperties: - type: object - additionalProperties: - type: string example: "@alice:example.com": "ed25519:JLAFKJWSCS": "dSO80A01XiigH3uBiDVx/EjzaoycHcjq9lfQX0uWsqxl2giMIiSPR8a4d291W1ihKJL/a+myXS367WT6NAIcBA" diff --git a/api/server-server/definitions/keys.yaml b/api/server-server/definitions/keys.yaml index 1e025a52..7e300402 100644 --- a/api/server-server/definitions/keys.yaml +++ b/api/server-server/definitions/keys.yaml @@ -75,18 +75,12 @@ properties: required: ["expired_ts", "key"] signatures: type: object - description: Digital signatures for this object signed using the ``verify_keys``. - additionalProperties: - type: object - title: Signed Server - example: { - "example.org": { - "ad25519:abc123": "VGhpcyBzaG91bGQgYWN0dWFsbHkgYmUgYSBzaWduYXR1cmU" - } - } - additionalProperties: - type: string - name: Encoded Signature Verification Key + description: |- + Digital signatures for this object signed using the ``verify_keys``. + + The signature is calculated using the process described at `Signing + JSON`_. + title: Signatures valid_until_ts: type: integer format: int64 diff --git a/api/server-server/third_party_invite.yaml b/api/server-server/third_party_invite.yaml index 0b7aac5b..8897bdcf 100644 --- a/api/server-server/third_party_invite.yaml +++ b/api/server-server/third_party_invite.yaml @@ -102,12 +102,12 @@ paths: properties: signatures: type: object - description: The server signatures for this event. - additionalProperties: - type: object - title: Server Signatures - additionalProperties: - type: string + title: Signatures + 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" diff --git a/api/server-server/user_keys.yaml b/api/server-server/user_keys.yaml index 93237d80..9224d508 100644 --- a/api/server-server/user_keys.yaml +++ b/api/server-server/user_keys.yaml @@ -88,10 +88,12 @@ paths: description: The key, encoded using unpadded base64. signatures: type: object + title: Signatures description: |- - Signature for the device. Mapped from user ID to signature object. - additionalProperties: - type: string + Signature of the key object. + + The signature is calculated using the process described at `Signing + JSON`_. required: ['key', 'signatures'] example: { "@alice:example.com": { From 6a8ba9b1d6372f9a71d6b8554947548556e84c8e Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Fri, 22 May 2020 16:10:16 -0400 Subject: [PATCH 2/5] improve description of key object in CS and include a link in Fed --- api/server-server/user_keys.yaml | 2 +- .../modules/end_to_end_encryption.rst | 20 ++++++++++++++++--- specification/server_server_api.rst | 1 + 3 files changed, 19 insertions(+), 4 deletions(-) diff --git a/api/server-server/user_keys.yaml b/api/server-server/user_keys.yaml index 9224d508..166f1ff0 100644 --- a/api/server-server/user_keys.yaml +++ b/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 ``:`` 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 diff --git a/specification/modules/end_to_end_encryption.rst b/specification/modules/end_to_end_encryption.rst index 7411abe4..8bc46de8 100644 --- a/specification/modules/end_to_end_encryption.rst +++ b/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 -the Base64-encoded 32-byte Curve25519 public key), and ``signatures`` (giving a -signature for the key object, as described in `Signing JSON`_). Example: +but a key using this algorithm is represented by an object with a the following +properties: + +``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 diff --git a/specification/server_server_api.rst b/specification/server_server_api.rst index b0a2bc1a..00ddeffc 100644 --- a/specification/server_server_api.rst +++ b/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 From 93f68866c5635078e84eaf8bcf55c8eb274c57f8 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 25 May 2020 08:06:57 -0600 Subject: [PATCH 3/5] Fix spec generation not using titles on pseudo objects --- scripts/templating/matrix_templates/units.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/scripts/templating/matrix_templates/units.py b/scripts/templating/matrix_templates/units.py index 9d2c69f2..5a7ff94e 100644 --- a/scripts/templating/matrix_templates/units.py +++ b/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, } From 36ed6e94a2bd2c5e591fdd87cb15acdae53ca03a Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 25 May 2020 08:08:10 -0600 Subject: [PATCH 4/5] Re-introduce signature schemas --- api/client-server/definitions/device_keys.yaml | 4 ++++ api/client-server/definitions/third_party_signed.yaml | 4 ++++ api/server-server/definitions/keys.yaml | 4 ++++ api/server-server/third_party_invite.yaml | 4 ++++ api/server-server/user_keys.yaml | 4 ++++ event-schemas/schema/m.room.member | 4 ++++ 6 files changed, 24 insertions(+) diff --git a/api/client-server/definitions/device_keys.yaml b/api/client-server/definitions/device_keys.yaml index ce770c09..4f7cffe7 100644 --- a/api/client-server/definitions/device_keys.yaml +++ b/api/client-server/definitions/device_keys.yaml @@ -54,6 +54,10 @@ properties: The signature is calculated using the process described at `Signing JSON`_. + additionalProperties: + type: object + additionalProperties: + type: string example: "@alice:example.com": "ed25519:JLAFKJWSCS": "dSO80A01XiigH3uBiDVx/EjzaoycHcjq9lfQX0uWsqxl2giMIiSPR8a4d291W1ihKJL/a+myXS367WT6NAIcBA" diff --git a/api/client-server/definitions/third_party_signed.yaml b/api/client-server/definitions/third_party_signed.yaml index c9c761a1..7ce1a1d1 100644 --- a/api/client-server/definitions/third_party_signed.yaml +++ b/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" diff --git a/api/server-server/definitions/keys.yaml b/api/server-server/definitions/keys.yaml index 7e300402..306d4d00 100644 --- a/api/server-server/definitions/keys.yaml +++ b/api/server-server/definitions/keys.yaml @@ -81,6 +81,10 @@ properties: The signature is calculated using the process described at `Signing JSON`_. title: Signatures + additionalProperties: + type: object + additionalProperties: + type: string valid_until_ts: type: integer format: int64 diff --git a/api/server-server/third_party_invite.yaml b/api/server-server/third_party_invite.yaml index 8897bdcf..fbd2a9d9 100644 --- a/api/server-server/third_party_invite.yaml +++ b/api/server-server/third_party_invite.yaml @@ -103,6 +103,10 @@ paths: signatures: type: object title: Signatures + additionalProperties: + type: object + additionalProperties: + type: string description: |- The server signatures for this event. diff --git a/api/server-server/user_keys.yaml b/api/server-server/user_keys.yaml index 166f1ff0..6ed51af0 100644 --- a/api/server-server/user_keys.yaml +++ b/api/server-server/user_keys.yaml @@ -89,6 +89,10 @@ paths: signatures: type: object title: Signatures + additionalProperties: + type: object + additionalProperties: + type: string description: |- Signature of the key object. diff --git a/event-schemas/schema/m.room.member b/event-schemas/schema/m.room.member index 1033c098..bff2002e 100644 --- a/event-schemas/schema/m.room.member +++ b/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 From 730d164df7fd23fb908f27bda4511f76b769cd36 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 25 May 2020 08:15:56 -0600 Subject: [PATCH 5/5] Add changelogs --- changelogs/client_server/newsfragments/2566.clarification | 1 + changelogs/server_server/newsfragments/2566.clarification | 1 + 2 files changed, 2 insertions(+) create mode 100644 changelogs/client_server/newsfragments/2566.clarification create mode 100644 changelogs/server_server/newsfragments/2566.clarification diff --git a/changelogs/client_server/newsfragments/2566.clarification b/changelogs/client_server/newsfragments/2566.clarification new file mode 100644 index 00000000..15e29b2f --- /dev/null +++ b/changelogs/client_server/newsfragments/2566.clarification @@ -0,0 +1 @@ +Clarify signature object structures for encryption. diff --git a/changelogs/server_server/newsfragments/2566.clarification b/changelogs/server_server/newsfragments/2566.clarification new file mode 100644 index 00000000..15e29b2f --- /dev/null +++ b/changelogs/server_server/newsfragments/2566.clarification @@ -0,0 +1 @@ +Clarify signature object structures for encryption.