put the MAC in unsigned instead of signatures

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
+   base64-encoded (unpadded), and becomes the `backup_mac` property of the
-   {user_id}.`hmac-sha-256:backup_mac_key` property of the `signatures`
+   `unsigned` property of `session_data`.
-   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`
+Thus the `session_data` property has `ephemeral`, `ciphertext`, and `unsigned`
-   as the key identifier.
+properties, with the `unsigned` property having a `backup_mac` property.
-
+Keys without an `unsigned`.`backup_mac` property, or with an incorrect MAC,
-Thus the `session_data` property has `ephemeral`, `ciphertext`, and
+must be ignored.
-`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.
 
 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
+   base64-encoded (unpadded), and becomes the `backup_mac` property of the
-   {user_id}.`hmac-sha-256:backup_mac_key` property of the `signatures`
+   `unsigned` property of `session_data`.
-   property of `session_data`.
 
-FIXME: should the server compare the
+FIXME: should the server compare the `unsigned`.`backup_mac` property when a
-`signatures`.{user_id}.`hmac-sha-256:backup_mac_key` property when a client
+client uploads a key to the backup, when deciding whether to keep the existing
-uploads a key to the backup, when deciding whether to keep the existing key or
+key or replace it with a new key?
-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
+`unsigned`.`backup_mac` property in the cleartext `session_data` property.
-`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
+`unsigned`.`backup_mac` property in the cleartext `session_data` property, or
-`session_data` property, or with an invalid MAC, must have the
+with an invalid MAC, must have the `unauthenticated` property set to
-`unauthenticated` property set to `m.legacy-v1` in the encrypted `SessionData`,
+`m.legacy-v1` in the encrypted `SessionData`, regardless of whether the key
-regardless of whether the key originally had an `unauthenticated` property, and
+originally had an `unauthenticated` property, and a `unsigned`.`backup_mac`
-a `signatures`.{user_mac}.`hmac-sha-256:backup_mac_key` property added to the
+property added to the cleartext `session_data`.  If the same backup decryption
-cleartext `session_data`.  If the same backup decryption key is used for the
+key is used for the old and new backups, keys that have an existing
-old and new backups, keys that have an existing
+`unsigned`.`backup_mac` property with a valid MAC may be uploaded to the new
-`signatures`.{user_id}.`hmac-sha-256:backup_mac_key` property with a valid MAC
+backup unchanged, as they will be valid
-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
+- the property name `org.matrix.msc4048.backup_mac` should be used in place of
-  used in place of `hmac-sha-256:backup_mac_key` in the `signatures`.{user_id}
+  the `backup_mac` property in the `unsigned` property,
-  property,
 - the SSSS identifier `org.matrix.msc4048.mac` should be used in place of
   `m.megolm_backup.v1.mac`.