wholetrans/docs-matrix-spec
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Merge pull request #2687 from uhoreg/sas2_spec

Browse source 
document new key agreement method for SAS verification and deprecate old method
This commit is contained in:
Hubert Chathi 2020-07-23 10:24:57 -04:00 • committed by GitHub
commit 53e2b999b9
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
3 changed files with 26 additions and 4 deletions
Download patch file Download diff file Expand all files Collapse all files

1
changelogs/client_server/newsfragments/2687.breaking Normal file
View file

@ -0,0 +1 @@
Document `curve25519-hkdf-sha256` key agreement method for SAS verification, and deprecate old method (MSC2630).

4
event-schemas/schema/m.key.verification.start$m.sas.v1
View file

@ -26,8 +26,8 @@ properties:
key_agreement_protocols:
type: array
description: |-
The key agreement protocols the sending device understands. Must
include at least ``curve25519``.
The key agreement protocols the sending device understands. Should
include at least ``curve25519-hkdf-sha256``.
items:
type: string
hashes:

25
specification/modules/end_to_end_encryption.rst
View file

@ -674,8 +674,27 @@ HKDF calculation
In all of the SAS methods, HKDF is as defined in `RFC 5869 <https://tools.ietf.org/html/rfc5869>`_
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