Filip/matrix-spec
1
0
Fork 0
mirror of https://github.com/matrix-org/matrix-spec synced 2026-03-26 21:14:09 +01:00
Code Issues Actions 3 Packages Projects Releases Wiki Activity

apply changes from review

Browse source
This commit is contained in:
Hubert Chathi 2023-02-07 16:17:22 -05:00
parent 9f4e2f2de5
commit 2190080ad1
4 changed files with 27 additions and 15 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
changelogs/client_server/newsfragments/1412.feature
View file

@ -1 +1 @@
Define `hkdf-hmac-sha256.v2` MAC method for SAS verification, as per [MSC 3783](Define hkdf-hmac-sha256.v2 MAC method for SAS verification).
Define `hkdf-hmac-sha256.v2` MAC method for SAS verification, as per [MSC 3783](https://github.com/matrix-org/matrix-spec-proposals/pull/3783).

36
content/client-server-api/modules/end_to_end_encryption.md
View file

@ -668,17 +668,20 @@ The process between Alice and Bob verifying each other would be:
the users to select a method.
14. Alice and Bob compare the strings shown by their devices, and tell
their devices if they match or not.
15. Assuming they match, Alice and Bob's devices calculate the HMAC of
their own device keys and a comma-separated sorted list of the key
IDs that they wish the other user to verify, using SHA-256 as the
hash function. The HMAC calculation is defined [below](#mac-calculation).
15. Assuming they match, Alice and Bob's devices each calculate Message
Authentication Codes (MACs) for:
* the keys that they wish to verify (usually their device ed25519 key and
their master cross-signing key)
* the list of key IDs that they wish the other user to verify.
The MAC calculation is defined [below](#mac-calculation).
16. Alice's device sends Bob's device an `m.key.verification.mac`
message containing the MAC of Alice's device keys and the MAC of her
key IDs to be verified. Bob's device does the same for Bob's device
keys and key IDs concurrently with Alice.
17. When the other device receives the `m.key.verification.mac` message,
the device calculates the HMAC of its copies of the other device's
keys given in the message, as well as the HMAC of the
the device calculates the MAC of its copies of the other device's
keys given in the message, as well as the MAC of the
comma-separated, sorted, list of key IDs in the message. The device
compares these with the HMAC values given in the message, and if
everything matches then the device keys are verified.
@ -766,11 +769,15 @@ following error codes are used in addition to those already specified:
###### 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
During the verification process, Message Authentication Codes (MACs) are calculated
for keys and lists of key IDs.
The method used to calculate these MACs depends upon the value of the
`message_authentication_code` property in the [`m.key.verification.accept`](#mkeyverificationaccept)
message. All current implementations should use the `hkdf-hmac-sha256.v2` method which is
defined as follows:
The MAC used is HMAC 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:
@ -785,10 +792,15 @@ is used, and in the info parameter is the concatenation of:
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
comma-separated with no extra whitespace added, with each key written in the
form `{algorithm}:{keyId}`. For example, the key list could look like:
`ed25519:Cross+Signing+Key,ed25519:DEVICEID`. 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.
The MAC values are base64-encoded and sent in a
[`m.key.verification.mac`](#mkeyverificationmac) message.
{{% 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,

2
data/event-schemas/schema/m.key.verification.accept.yaml
View file

@ -26,7 +26,7 @@ properties:
message_authentication_code:
type: string
description: |-
The message authentication code the device is choosing to use, out of
The message authentication code method the device is choosing to use, out of
the options in the `m.key.verification.start` message.
short_authentication_string:
type: array

2
data/event-schemas/schema/m.key.verification.start$m.sas.v1.yaml
View file

@ -41,7 +41,7 @@ properties:
message_authentication_codes:
type: array
description: |-
The message authentication codes that the sending device understands.
The message authentication code methods that the sending device understands.
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