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
+26 −4
Merged

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

Show file tree
Hide file tree
Changes from 2 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.feature
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
Document new key agreement method for SAS verification, and deprecate old method (MSC2630).
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Document new key agreement method for SAS verification, and deprecate old method (MSC2630).
Document `curve25519-hkdf-sha256` key agreement method for SAS verification, and deprecate old method (MSC2630).

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

technically speaking, this is a breaking change. An existing client implementing the current version of the spec will be incompatible with a client implementing (only) the new version of the spec.

r0.6.0, r0.5.0, r0.3.0 and r0.1.0 all included minor breaking changes, and I'd propose doing much the same here.

What do others think?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it's fine to remove the previous requirement of curve25519 always being present, but the same mistake should not be repeated by now requiring curve25519-hkdf-sha256 to always be present. Maybe the docs could say something like "for version r0.7.0, it is expected that client supports at least the curve25519-hkdf-sha256 key agreement protocol".

2 changes: 1 addition & 1 deletion 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 @@ -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:
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