From 0f13ebe3ed173064ecb33b8f4fea5d7296dee74b Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Mon, 13 Jul 2020 15:59:09 -0400 Subject: [PATCH 1/3] document new key agreement method and deprecate old method --- .../schema/m.key.verification.start$m.sas.v1 | 2 +- .../modules/end_to_end_encryption.rst | 25 +++++++++++++++++-- 2 files changed, 24 insertions(+), 3 deletions(-) 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 daf6fa39..06f22d40 100644 --- a/event-schemas/schema/m.key.verification.start$m.sas.v1 +++ b/event-schemas/schema/m.key.verification.start$m.sas.v1 @@ -27,7 +27,7 @@ properties: type: array description: |- The key agreement protocols the sending device understands. Must - include at least ``curve25519``. + include at least ``curve25519-hkdf-sha256``. items: type: string hashes: diff --git a/specification/modules/end_to_end_encryption.rst b/specification/modules/end_to_end_encryption.rst index d3b6070d..53ce2775 100644 --- a/specification/modules/end_to_end_encryption.rst +++ b/specification/modules/end_to_end_encryption.rst @@ -674,8 +674,27 @@ HKDF calculation In all of the SAS methods, HKDF is as defined in `RFC 5869 `_ and uses the previously agreed-upon hash function for the hash function. The shared -secret is supplied as the input keying material. No salt is used, and the info -parameter is the concatenation of: +secret is supplied as the input keying material. No salt is used. When the +``key_agreement_protocol`` is ``curve25519-hkdf-sha256``, the info parameter is +the concatenation of: + + * The string ``MATRIX_KEY_VERIFICATION_SAS|``. + * The Matrix ID of the user who sent the ``m.key.verification.start`` message, + followed by ``|``. + * The Device ID of the device which sent the ``m.key.verification.start`` + message, followed by ``|``. + * The public key from the ``m.key.verification.key`` message sent by the device + which sent the ``m.key.verification.start`` message, followed by ``|``. + * The Matrix ID of the user who sent the ``m.key.verification.accept`` message, + followed by ``|``. + * The Device ID of the device which sent the ``m.key.verification.accept`` + message, followed by ``|``. + * The public key from the ``m.key.verification.key`` message sent by the device + which sent the ``m.key.verification.accept`` message, followed by ``|``. + * The ``transaction_id`` being used. + +When the ``key_agreement_protocol`` is the deprecated method ``curve25519``, +the info parameter is the concatenation of: * The string ``MATRIX_KEY_VERIFICATION_SAS``. * The Matrix ID of the user who sent the ``m.key.verification.start`` message. @@ -684,6 +703,8 @@ parameter is the concatenation of: * The Device ID of the device which sent the ``m.key.verification.accept`` message. * The ``transaction_id`` being used. +New implementations are discouraged from implementing the ``curve25519`` method. + .. admonition:: Rationale HKDF is used over the plain shared secret as it results in a harder attack From 793dae1ecee7695a3bcb0e01558bdd2726cc58ec Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Mon, 13 Jul 2020 16:03:12 -0400 Subject: [PATCH 2/3] add changelog --- changelogs/client_server/newsfragments/2687.feature | 1 + 1 file changed, 1 insertion(+) create mode 100644 changelogs/client_server/newsfragments/2687.feature diff --git a/changelogs/client_server/newsfragments/2687.feature b/changelogs/client_server/newsfragments/2687.feature new file mode 100644 index 00000000..f70cfdee --- /dev/null +++ b/changelogs/client_server/newsfragments/2687.feature @@ -0,0 +1 @@ +Document new key agreement method for SAS verification, and deprecate old method (MSC2630). From 33ed9fc2dd0a3ce790bc485c19a1aaf8b4d54c57 Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Tue, 21 Jul 2020 16:19:53 -0400 Subject: [PATCH 3/3] apply changes from review --- changelogs/client_server/newsfragments/2687.breaking | 1 + changelogs/client_server/newsfragments/2687.feature | 1 - event-schemas/schema/m.key.verification.start$m.sas.v1 | 2 +- 3 files changed, 2 insertions(+), 2 deletions(-) create mode 100644 changelogs/client_server/newsfragments/2687.breaking delete mode 100644 changelogs/client_server/newsfragments/2687.feature diff --git a/changelogs/client_server/newsfragments/2687.breaking b/changelogs/client_server/newsfragments/2687.breaking new file mode 100644 index 00000000..c40f7625 --- /dev/null +++ b/changelogs/client_server/newsfragments/2687.breaking @@ -0,0 +1 @@ +Document `curve25519-hkdf-sha256` key agreement method for SAS verification, and deprecate old method (MSC2630). diff --git a/changelogs/client_server/newsfragments/2687.feature b/changelogs/client_server/newsfragments/2687.feature deleted file mode 100644 index f70cfdee..00000000 --- a/changelogs/client_server/newsfragments/2687.feature +++ /dev/null @@ -1 +0,0 @@ -Document new key agreement method for SAS verification, and deprecate old method (MSC2630). 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 06f22d40..f4deb3c8 100644 --- a/event-schemas/schema/m.key.verification.start$m.sas.v1 +++ b/event-schemas/schema/m.key.verification.start$m.sas.v1 @@ -26,7 +26,7 @@ properties: key_agreement_protocols: type: array description: |- - The key agreement protocols the sending device understands. Must + The key agreement protocols the sending device understands. Should include at least ``curve25519-hkdf-sha256``. items: type: string