Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

document new key agreement method for SAS verification and deprecate old method #2687

Merged
merged 3 commits into from
Jul 23, 2020
Merged

document new key agreement method for SAS verification and deprecate old method #2687

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
0f13ebe
document new key agreement method and deprecate old method
uhoreg Jul 13, 2020
793dae1
add changelog
uhoreg Jul 13, 2020
33ed9fc
apply changes from review
uhoreg Jul 21, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions changelogs/client_server/newsfragments/2687.breaking
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
Document `curve25519-hkdf-sha256` key agreement method for SAS verification, and deprecate old method (MSC2630).
4 changes: 2 additions & 2 deletions event-schemas/schema/m.key.verification.start$m.sas.v1
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
25 changes: 23 additions & 2 deletions specification/modules/end_to_end_encryption.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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
Expand Down