From 565672106af3e2b26613529dfeb522effe76ca9f Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Tue, 24 Jan 2023 18:24:27 -0500 Subject: [PATCH] define hkdf-hmac-sha256.v2 MAC method for SAS verification --- .../modules/end_to_end_encryption.md | 51 +++++++++++++------ .../examples/m.key.verification.accept.yaml | 2 +- .../m.key.verification.start$m.sas.v1.yaml | 2 +- .../schema/m.key.verification.mac.yaml | 4 +- .../m.key.verification.start$m.sas.v1.yaml | 5 +- 5 files changed, 45 insertions(+), 19 deletions(-) diff --git a/content/client-server-api/modules/end_to_end_encryption.md b/content/client-server-api/modules/end_to_end_encryption.md index ad10a633..29f312dc 100644 --- a/content/client-server-api/modules/end_to_end_encryption.md +++ b/content/client-server-api/modules/end_to_end_encryption.md @@ -767,7 +767,42 @@ following error codes are used in addition to those already specified: {{% event event="m.key.verification.mac" %}} -###### HKDF calculation +###### MAC calculation + +For verification of each party's device keys, a MAC is calculated individually +for each the keys that are to be verified. As well, a MAC is calculated for a +list of the keys IDs. The MAC used is HMAC as defined in [RFC +2104](https://tools.ietf.org/html/rfc2104), using SHA-256 as the hash function. +The HMAC key is calculated using HKDF as defined in [RFC +5869](https://tools.ietf.org/html/rfc5869), using SHA-256 as the hash +function. The shared secret is supplied as the input keying material. No salt +is used, and in the info parameter is the concatenation of: + +- The string `MATRIX_KEY_VERIFICATION_MAC`. +- The Matrix ID of the user whose key is being MAC-ed. +- The Device ID of the device sending the MAC. +- The Matrix ID of the other user. +- The Device ID of the device receiving the MAC. +- The `transaction_id` being used. +- The Key ID of the key being MAC-ed, or the string `KEY_IDS` if the + item being MAC-ed is the list of key IDs. + +If the key list is being MACed, the list is sorted lexicographically and +comma-separated with no extra whitespace added. In this way, the recipient can +reconstruct the list from the names in the `mac` property of the +`m.key.verification.mac` message and ensure that no keys were added or removed. + +{{% boxes/note %}} +The MAC method `hkdf-hmac-sha256` used an incorrect base64 encoding, due to a +bug in the original implementation in libolm. To remedy this, +`hkdf-hmac-sha256.v2` was introduced, which calculates the MAC in the same way, +but uses a correct base64 encoding. `hkdf-hmac-sha256` is deprecated and will +be removed in a future version of the spec. Use of `hkdf-hmac-sha256` should +be avoided whenever possible: if both parties support `hkdf-hmac-sha256.v2`, +then `hkdf-hmac-sha256` MUST not be used. +{{% /boxes/note %}} + +###### SAS calculation In all of the SAS methods, HKDF is as defined in [RFC 5869](https://tools.ietf.org/html/rfc5869) and uses the previously @@ -815,20 +850,6 @@ HKDF is used over the plain shared secret as it results in a harder attack as well as more uniform data to work with. {{% /boxes/rationale %}} -For verification of each party's device keys, HKDF is as defined in RFC -5869 and uses SHA-256 as the hash function. The shared secret is -supplied as the input keying material. No salt is used, and in the info -parameter is the concatenation of: - -- The string `MATRIX_KEY_VERIFICATION_MAC`. -- The Matrix ID of the user whose key is being MAC-ed. -- The Device ID of the device sending the MAC. -- The Matrix ID of the other user. -- The Device ID of the device receiving the MAC. -- The `transaction_id` being used. -- The Key ID of the key being MAC-ed, or the string `KEY_IDS` if the - item being MAC-ed is the list of key IDs. - ###### SAS method: `decimal` Generate 5 bytes using [HKDF](#hkdf-calculation) then take sequences of 13 bits diff --git a/data/event-schemas/examples/m.key.verification.accept.yaml b/data/event-schemas/examples/m.key.verification.accept.yaml index 98e89c06..2cda7994 100644 --- a/data/event-schemas/examples/m.key.verification.accept.yaml +++ b/data/event-schemas/examples/m.key.verification.accept.yaml @@ -5,7 +5,7 @@ "method": "m.sas.v1", "key_agreement_protocol": "curve25519", "hash": "sha256", - "message_authentication_code": "hkdf-hmac-sha256", + "message_authentication_code": "hkdf-hmac-sha256.v2", "short_authentication_string": ["decimal", "emoji"], "commitment": "fQpGIW1Snz+pwLZu6sTy2aHy/DYWWTspTJRPyNp0PKkymfIsNffysMl6ObMMFdIJhk6g6pwlIqZ54rxo8SLmAg" } diff --git a/data/event-schemas/examples/m.key.verification.start$m.sas.v1.yaml b/data/event-schemas/examples/m.key.verification.start$m.sas.v1.yaml index dae1d405..080606c8 100644 --- a/data/event-schemas/examples/m.key.verification.start$m.sas.v1.yaml +++ b/data/event-schemas/examples/m.key.verification.start$m.sas.v1.yaml @@ -6,7 +6,7 @@ "method": "m.sas.v1", "key_agreement_protocols": ["curve25519"], "hashes": ["sha256"], - "message_authentication_codes": ["hkdf-hmac-sha256"], + "message_authentication_codes": ["hkdf-hmac-sha256.v2", "hkdf-hmac-sha256"], "short_authentication_string": ["decimal", "emoji"] } } diff --git a/data/event-schemas/schema/m.key.verification.mac.yaml b/data/event-schemas/schema/m.key.verification.mac.yaml index 9f7f5f4f..7f404fa0 100644 --- a/data/event-schemas/schema/m.key.verification.mac.yaml +++ b/data/event-schemas/schema/m.key.verification.mac.yaml @@ -3,7 +3,9 @@ allOf: - $ref: core-event-schema/event.yaml description: |- - Sends the MAC of a device's key to the partner device. + Sends the MAC of a device's key to the partner device. The MAC is calculated + using the method given in `message_authentication_code` property of the + `m.key.verification.accept` message. properties: content: properties: diff --git a/data/event-schemas/schema/m.key.verification.start$m.sas.v1.yaml b/data/event-schemas/schema/m.key.verification.start$m.sas.v1.yaml index 515a72a1..edc1116a 100644 --- a/data/event-schemas/schema/m.key.verification.start$m.sas.v1.yaml +++ b/data/event-schemas/schema/m.key.verification.start$m.sas.v1.yaml @@ -42,7 +42,10 @@ properties: type: array description: |- The message authentication codes that the sending device understands. - Must include at least `hkdf-hmac-sha256`. + Must include at least `hkdf-hmac-sha256.v2`. Should also include + `hkdf-hmac-sha256` for compatibility with older clients, though this + identifier is deprecated and will be removed in a future version of + the spec. items: type: string short_authentication_string: