From bc71dacaf4f65e2a27705a658fc4b303ecba16c9 Mon Sep 17 00:00:00 2001 From: Jimmy Cuadra Date: Fri, 14 Jun 2019 16:05:25 -0700 Subject: [PATCH 1/4] Clarify the distinction between *m.key.verification.start* and its *m.sas.v1* variant. Currently the *m.key.verification.start* event appears twice with the exact same title, in the "Key verification framework" section and the "Short Authentication (SAS) verification" section. It's not immediately clear that the first occurrence describes the format of the event in general terms and that the second occurrence describes the fields when the *m.sas.v1* verification method is being used. This is a similar relationship to the *m.room.message* event and its various *msgtype* variants. This commit does three things: * It tweaks the generation of the documentation to change the title of the second occurrence of *m.key.verification.start* to distinguish it from the first. * It updates the language in the description of the two versions of the event to better describe the relationship between the two. * It adds the optional `next_method` field to the schema of the *m.sas.v1* variant, as specified in the general form of *m.key.verification.start*. Signed-off-by: Jimmy Cuadra --- .../client_server/newsfragments/2132.clarification | 1 + event-schemas/schema/m.key.verification.start | 2 +- event-schemas/schema/m.key.verification.start$m.sas.v1 | 8 ++++++-- scripts/templating/matrix_templates/units.py | 9 +++++++++ 4 files changed, 17 insertions(+), 3 deletions(-) create mode 100644 changelogs/client_server/newsfragments/2132.clarification diff --git a/changelogs/client_server/newsfragments/2132.clarification b/changelogs/client_server/newsfragments/2132.clarification new file mode 100644 index 00000000..53063400 --- /dev/null +++ b/changelogs/client_server/newsfragments/2132.clarification @@ -0,0 +1 @@ +Clarify the distinction between *m.key.verification.start* and its *m.sas.v1* variant. diff --git a/event-schemas/schema/m.key.verification.start b/event-schemas/schema/m.key.verification.start index ad59d6c7..99b4998e 100644 --- a/event-schemas/schema/m.key.verification.start +++ b/event-schemas/schema/m.key.verification.start @@ -3,7 +3,7 @@ allOf: - $ref: core-event-schema/event.yaml description: |- - Begins a key verification process. Typically sent as a `to-device`_ event. + Begins a key verification process. Typically sent as a `to-device`_ event. The ``method`` field determines the type of verification. The fields in the event will differ depending on the ``method``. This definition includes fields that are in common among all variants. properties: content: properties: diff --git a/event-schemas/schema/m.key.verification.start$m.sas.v1 b/event-schemas/schema/m.key.verification.start$m.sas.v1 index 867ca820..a42f20e7 100644 --- a/event-schemas/schema/m.key.verification.start$m.sas.v1 +++ b/event-schemas/schema/m.key.verification.start$m.sas.v1 @@ -3,7 +3,7 @@ allOf: - $ref: core-event-schema/event.yaml description: |- - Begins a SAS key verification process. Typically sent as a `to-device`_ event. + Begins an SAS key verification process using the ``m.sas.v1`` method. Typically sent as a `to-device`_ event. properties: content: properties: @@ -22,7 +22,11 @@ properties: type: string enum: ["m.sas.v1"] description: |- - The verification method to use. Must be ``m.sas.v1``. + The verification method to use. + next_method: + type: string + description: |- + Optional method to use to verify the other user's key with. key_agreement_protocols: type: array description: |- diff --git a/scripts/templating/matrix_templates/units.py b/scripts/templating/matrix_templates/units.py index 157fa5a1..8538de2d 100644 --- a/scripts/templating/matrix_templates/units.py +++ b/scripts/templating/matrix_templates/units.py @@ -902,6 +902,15 @@ class MatrixUnits(Units): "`m.room.message msgtypes`_." ) + # method types for m.key.verification.start + if schema["type"] == "m.key.verification.start": + methods = Units.prop( + json_schema, "properties/content/properties/method/enum" + ) + if methods: + schema["type_with_msgtype"] = schema["type"] + " (" + methods[0] + ")" + + # Assign state key info if it has some if schema["typeof"] == "State Event": skey_desc = Units.prop( From 5384b61d95c82dcde6e924ce40f037f7f659d70f Mon Sep 17 00:00:00 2001 From: Jimmy Cuadra Date: Fri, 14 Jun 2019 17:35:39 -0700 Subject: [PATCH 2/4] Fix style issues brought up during code review. Signed-off-by: Jimmy Cuadra --- changelogs/client_server/newsfragments/2132.clarification | 2 +- event-schemas/schema/m.key.verification.start | 4 +++- scripts/templating/matrix_templates/units.py | 1 - 3 files changed, 4 insertions(+), 3 deletions(-) diff --git a/changelogs/client_server/newsfragments/2132.clarification b/changelogs/client_server/newsfragments/2132.clarification index 53063400..1c458340 100644 --- a/changelogs/client_server/newsfragments/2132.clarification +++ b/changelogs/client_server/newsfragments/2132.clarification @@ -1 +1 @@ -Clarify the distinction between *m.key.verification.start* and its *m.sas.v1* variant. +Clarify the distinction between ``m`.key.verification.start` and its `m`.`sas.v1` variant. diff --git a/event-schemas/schema/m.key.verification.start b/event-schemas/schema/m.key.verification.start index 99b4998e..28926f4f 100644 --- a/event-schemas/schema/m.key.verification.start +++ b/event-schemas/schema/m.key.verification.start @@ -3,7 +3,9 @@ allOf: - $ref: core-event-schema/event.yaml description: |- - Begins a key verification process. Typically sent as a `to-device`_ event. The ``method`` field determines the type of verification. The fields in the event will differ depending on the ``method``. This definition includes fields that are in common among all variants. + Begins a key verification process. Typically sent as a `to-device`_ event. The ``method`` + field determines the type of verification. The fields in the event will differ depending + on the ``method``. This definition includes fields that are in common among all variants. properties: content: properties: diff --git a/scripts/templating/matrix_templates/units.py b/scripts/templating/matrix_templates/units.py index 8538de2d..04e6f8a9 100644 --- a/scripts/templating/matrix_templates/units.py +++ b/scripts/templating/matrix_templates/units.py @@ -910,7 +910,6 @@ class MatrixUnits(Units): if methods: schema["type_with_msgtype"] = schema["type"] + " (" + methods[0] + ")" - # Assign state key info if it has some if schema["typeof"] == "State Event": skey_desc = Units.prop( From 8affb23e5ef62e01ba5c43d3d91f633748580994 Mon Sep 17 00:00:00 2001 From: Jimmy Cuadra Date: Sat, 15 Jun 2019 13:44:58 -0700 Subject: [PATCH 3/4] Address feedback from code review. * Switch "an SAS" back to "a SAS" * Remove the `next_method` field from m.key.verification.start$m.sas.v1 but add additional clarification to its description on m.key.verification.start that it is never present for methods that verify keys both ways. --- event-schemas/schema/m.key.verification.start | 3 ++- event-schemas/schema/m.key.verification.start$m.sas.v1 | 6 +----- 2 files changed, 3 insertions(+), 6 deletions(-) diff --git a/event-schemas/schema/m.key.verification.start b/event-schemas/schema/m.key.verification.start index 28926f4f..faa7a96a 100644 --- a/event-schemas/schema/m.key.verification.start +++ b/event-schemas/schema/m.key.verification.start @@ -28,7 +28,8 @@ properties: type: string description: |- Optional method to use to verify the other user's key with. Applicable - when the ``method`` chosen only verifies one user's key. + when the ``method`` chosen only verifies one user's key. This field will + never be present if the ``method`` verifies keys both ways. required: - from_device - transaction_id diff --git a/event-schemas/schema/m.key.verification.start$m.sas.v1 b/event-schemas/schema/m.key.verification.start$m.sas.v1 index a42f20e7..daf6fa39 100644 --- a/event-schemas/schema/m.key.verification.start$m.sas.v1 +++ b/event-schemas/schema/m.key.verification.start$m.sas.v1 @@ -3,7 +3,7 @@ allOf: - $ref: core-event-schema/event.yaml description: |- - Begins an SAS key verification process using the ``m.sas.v1`` method. Typically sent as a `to-device`_ event. + Begins a SAS key verification process using the ``m.sas.v1`` method. Typically sent as a `to-device`_ event. properties: content: properties: @@ -23,10 +23,6 @@ properties: enum: ["m.sas.v1"] description: |- The verification method to use. - next_method: - type: string - description: |- - Optional method to use to verify the other user's key with. key_agreement_protocols: type: array description: |- From 82463833300121a2ddc5b2676e5e8fd64f4263d3 Mon Sep 17 00:00:00 2001 From: Jimmy Cuadra Date: Tue, 18 Jun 2019 16:37:37 -0700 Subject: [PATCH 4/4] Fix typos in changelog entry. --- changelogs/client_server/newsfragments/2132.clarification | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/changelogs/client_server/newsfragments/2132.clarification b/changelogs/client_server/newsfragments/2132.clarification index 1c458340..b8a4cc8a 100644 --- a/changelogs/client_server/newsfragments/2132.clarification +++ b/changelogs/client_server/newsfragments/2132.clarification @@ -1 +1 @@ -Clarify the distinction between ``m`.key.verification.start` and its `m`.`sas.v1` variant. +Clarify the distinction between ``m.key.verification.start`` and its ``m.sas.v1`` variant.