From 0f13ebe3ed173064ecb33b8f4fea5d7296dee74b Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Mon, 13 Jul 2020 15:59:09 -0400 Subject: [PATCH] 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