diff --git a/changelogs/client_server/newsfragments/1712.clarification b/changelogs/client_server/newsfragments/1712.clarification new file mode 100644 index 00000000..9e1523c5 --- /dev/null +++ b/changelogs/client_server/newsfragments/1712.clarification @@ -0,0 +1 @@ +Clarify that the key backup MAC is implemented incorrectly and does not pass the ciphertext through HMAC-SHA-256. 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 cdeed706..a4131d05 100644 --- a/content/client-server-api/modules/end_to_end_encryption.md +++ b/content/client-server-api/modules/end_to_end_encryption.md @@ -1364,10 +1364,18 @@ The `session_data` field in the backups is constructed as follows: PKCS\#7 padding. This encrypted data, encoded using unpadded base64, becomes the `ciphertext` property of the `session_data`. -5. Pass the raw encrypted data (prior to base64 encoding) through - HMAC-SHA-256 using the MAC key generated above. The first 8 bytes of - the resulting MAC are base64-encoded, and become the `mac` property - of the `session_data`. +5. Pass an empty string through HMAC-SHA-256 using the MAC key generated above. + The first 8 bytes of the resulting MAC are base64-encoded, and become the + `mac` property of the `session_data`. + +{{% boxes/warning %}} +Step 5 was intended to pass the raw encrypted data, but due to a bug in libolm, +all implementations have since passed an empty string instead. + +Future versions of the spec will fix this problem. See +[MSC4048](https://github.com/matrix-org/matrix-spec-proposals/pull/4048) for a +potential new key backup algorithm version that would fix this issue. +{{% /boxes/warning %}} {{% definition path="api/client-server/definitions/key_backup_session_data" %}}