From 20b767f5f4ac616b10237c2fb23a1b4bfc8baa3f Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Thu, 23 Nov 2023 13:36:06 -0500 Subject: [PATCH] put the MAC in unsigned instead of signatures --- proposals/4048-signed-key-backup.md | 59 +++++++++++++---------------- 1 file changed, 26 insertions(+), 33 deletions(-) diff --git a/proposals/4048-signed-key-backup.md b/proposals/4048-signed-key-backup.md index ad7e63ac..b8f1f3af 100644 --- a/proposals/4048-signed-key-backup.md +++ b/proposals/4048-signed-key-backup.md @@ -75,21 +75,19 @@ The `session_data` is constructed as follows: 5. Encode the `session_data` as canonical JSON, as would be done when [signing JSON](https://spec.matrix.org/unstable/appendices/#signing-details), and calculate the HMAC-SHA-256 MAC using the backup MAC key. The MAC is - base64-encoded (unpadded), and becomes the - {user_id}.`hmac-sha-256:backup_mac_key` property of the `signatures` - property of `session_data`. That is, the MAC is added to the object as a - signature with `hmac-sha-256` as the signing algorithm and `backup_mac_key` - as the key identifier. - -Thus the `session_data` property has `ephemeral`, `ciphertext`, and -`signatures` properties, with the `signatures` property having a {user_id} -property with a `hmac-sha-256:backup_mac_key` property. Keys without a -`signatures`.{user_id}.`hmac-sha-256:backup_mac_key` property, or with an -incorrect MAC, must be ignored. + base64-encoded (unpadded), and becomes the `backup_mac` property of the + `unsigned` property of `session_data`. + +Thus the `session_data` property has `ephemeral`, `ciphertext`, and `unsigned` +properties, with the `unsigned` property having a `backup_mac` property. +Keys without an `unsigned`.`backup_mac` property, or with an incorrect MAC, +must be ignored. When verifying the MAC, the `session_data` is encoded as canonical JSON, following the procedure as when signing JSON. That is, any additional -properties, other than `signatures` and `unsigned`, are included. +properties, other than `signatures` and `unsigned`, are included. By putting +the MAC in `unsigned` this allows clients to reuse existing code used for +serializing JSON for signing. The `SessionDataV2` has algorithm-dependent and algorithm-independent properties. The algorithm-independent properties are: @@ -157,36 +155,32 @@ thus becomes: 6. Encode the `session_data` as canonical JSON, as would be done when [signing JSON](https://spec.matrix.org/unstable/appendices/#signing-details), and calculate the HMAC-SHA-256 MAC using the backup MAC key. The MAC is - base64-encoded (unpadded), and becomes the - {user_id}.`hmac-sha-256:backup_mac_key` property of the `signatures` - property of `session_data`. + base64-encoded (unpadded), and becomes the `backup_mac` property of the + `unsigned` property of `session_data`. -FIXME: should the server compare the -`signatures`.{user_id}.`hmac-sha-256:backup_mac_key` property when a client -uploads a key to the backup, when deciding whether to keep the existing key or -replace it with a new key? +FIXME: should the server compare the `unsigned`.`backup_mac` property when a +client uploads a key to the backup, when deciding whether to keep the existing +key or replace it with a new key? To simplify logic, clients may treat `m.backup.v2.curve25519-aes-sha2`-format keys with the same semantics as `m.megolm_backup.v1.curve25519-aes-sha2` keys when they are in a `m.megolm_backup.v1.curve25519-aes-sha2` backup. That is, clients may treat all keys in a `m.megolm_backup.v1.curve25519-aes-sha2` backup as being unauthenticated, regardless of the presence or absence of the -`signatures`.{user_id}.`hmac-sha-256:backup_mac_key` property in the cleartext -`session_data` property. +`unsigned`.`backup_mac` property in the cleartext `session_data` property. #### Migrating keys When migrating keys from a `m.megolm_backup.v1.curve25519-aes-sha2` backup to a `m.backup.v2.curve25519-aes-sha2` backup, keys without a -`signatures`.{user_id}.`hmac-sha-256:backup_mac_key` property in the cleartext -`session_data` property, or with an invalid MAC, must have the -`unauthenticated` property set to `m.legacy-v1` in the encrypted `SessionData`, -regardless of whether the key originally had an `unauthenticated` property, and -a `signatures`.{user_mac}.`hmac-sha-256:backup_mac_key` property added to the -cleartext `session_data`. If the same backup decryption key is used for the -old and new backups, keys that have an existing -`signatures`.{user_id}.`hmac-sha-256:backup_mac_key` property with a valid MAC -may be uploaded to the new backup unchanged, as they will be valid +`unsigned`.`backup_mac` property in the cleartext `session_data` property, or +with an invalid MAC, must have the `unauthenticated` property set to +`m.legacy-v1` in the encrypted `SessionData`, regardless of whether the key +originally had an `unauthenticated` property, and a `unsigned`.`backup_mac` +property added to the cleartext `session_data`. If the same backup decryption +key is used for the old and new backups, keys that have an existing +`unsigned`.`backup_mac` property with a valid MAC may be uploaded to the new +backup unchanged, as they will be valid `m.backup.v2.curve25519-aes-sha2`-format keys. ## Potential issues @@ -259,9 +253,8 @@ Until this MSC is accepted, the following unstable names should be used: be used in place of the name `m.backup.v2.curve25519-aes-sha2`. - the property name `org.matrix.msc4048.unauthenticated` should be used in place of `unauthenticated` in the `SessionData` object, -- the property name `org.matrix.msc4048.hmac-sha-256:backup_mac_key` should be - used in place of `hmac-sha-256:backup_mac_key` in the `signatures`.{user_id} - property, +- the property name `org.matrix.msc4048.backup_mac` should be used in place of + the `backup_mac` property in the `unsigned` property, - the SSSS identifier `org.matrix.msc4048.mac` should be used in place of `m.megolm_backup.v1.mac`.