From 6d0d9e27cf2a8bced350e2c0a786fcdabac6d986 Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Wed, 23 Aug 2023 15:53:07 -0400 Subject: [PATCH 01/13] initial version of signed key backup proposal --- proposals/xxxx-signed-key-backup.md | 108 ++++++++++++++++++++++++++++ 1 file changed, 108 insertions(+) create mode 100644 proposals/xxxx-signed-key-backup.md diff --git a/proposals/xxxx-signed-key-backup.md b/proposals/xxxx-signed-key-backup.md new file mode 100644 index 00000000000..9d7001ebd9c --- /dev/null +++ b/proposals/xxxx-signed-key-backup.md @@ -0,0 +1,108 @@ +# MSCxxxx: Signed key backup + +The [server-side key +backups](https://spec.matrix.org/unstable/client-server-api/#server-side-key-backups) +allows clients to store event decryption keys so that when the user logs in to +a new device, they can decrypt old messages. The current algorithm encrypts +the event keys using a symmetric algorithm, allowing clients to upload keys to +the backup without necessarily giving them the ability to read from the +backup. For example, this allows for a partially-trusted client to be able to +read (and save the keys for) current messages, but not read old messages. + +However, since the event decryption keys are encrypted using a symmetric +algorithm, this allows anyone who knows the public key to write to the backup. +As a result, keys loaded from the backup must be marked as unauthenticated, +leading to [usability +issues](https://github.com/vector-im/element-web/issues/14323). + +[MSC3270](https://github.com/matrix-org/matrix-spec-proposals/pull/3270) tries +to fix this issue by using a symmetric, authenticated encryption algorithm, +which ensures that only someone who knows the secret key can write to the +backup. However this removes the ability for a client to be able to write to +the backup without being able to read from it. + +We propose to continue using a symmetric encryption algorithm in the backup, +but to ensure authenticity by signing the backup data. + +## Proposal + +A user has a new signing key, referred to as the "backup signing key", used to +sign key backups using the ed25519 signature algorithm. The private key can be +shared/stored using [the Secrets +module](https://spec.matrix.org/unstable/client-server-api/#secrets) using the +name `m.key_backup.signing`. + +The `AuthData` object for the [`m.megolm_backup.v1.curve25519-aes-sha2` key +backup +algorithm](https://spec.matrix.org/unstable/client-server-api/#backup-algorithm-mmegolm_backupv1curve25519-aes-sha2) +has a new optional property called `signing_public_key`, contains the public +key of the backup signing key, encoded in unpadded base64. If the `AuthData` +is not signed by the user's master signing key or by a verified device +belonging to the same user, the backup signing key must be ignored, and all +keys in the backup must be treated as being unsigned. + +The `SessionData` object for the `m.megolm_backup.v1.curve25519-aes-sha2` key +backup algorithm has two new optional properties: + +- a `signatures` property: the `SessionData` is a [signed JSON + object](https://spec.matrix.org/unstable/appendices/#signing-json), signed + using the backup signing key, using the public key (encoded in unpadded + base64) as the key ID +- a boolean `authenticated` property, defaulting to `false`: indicates whether + the device that uploaded the key to the backup believes that the key belongs + to the given `sender_key`. This is true if: a) the key was received via an + Olm-encrypted `m.room_key` event from the `sender_key`, b) the key was + received via a trusted key forward + ([MSC3879](https://github.com/matrix-org/matrix-spec-proposals/pull/3879)), + or c) the key was downloaded from the key backup, with the `authenticated` + property set to `true` and signed by a trusted key. If the `SessionData` is + not signed by the backup signing key, then this flag must be treated as being + `false`. + +The `mac` property in the cleartext `session_data` property of the +`KeyBackupData` is deprecated. Clients should continue to produce it for +compatibility with older clients, but should no longer use it to verify the +contents of the backup if the `SessionData` object is signed. + +## Potential issues + +As the `AuthData` is changed, a new backup version will need to be created. A +client will need to download all existing keys and re-upload them. + +In order to store a new secret in the Secret Storage, clients may need to +prompt the user for the Secret Storage key. Clients may need to do so already +to download all the current keys from the backup. + +## Alternatives + +As mentioned above, we could switch to using a symmetric encryption algorithm +for the key backup. However, this is not backwards-compatible, and does not +allow for clients that can write to the backup without reading. + +## Security considerations + +Being able to prove authenticity of keys may affect the deniability of +messages: if a user has a Megolm session in their key backup that is signed by their +backup signing key, and the session data indicates that it originated from one +of their devices, this could be used as evidence that the Megolm session did in +fact come from them. + +This is somewhat mitigated by the fact that obtaining the Megolm session +requires the decryption key for the backup. In addition, the deniability +property is mainly refers to the fact that a recipient cannot prove the +authenticity of the message to a third party, and usually is not concerned with +preventing self-incrimination. And in fact, a confiscated device may already +have enough information to sufficiently prove that the device's owner sent a +message. + +## Unstable prefix + +Until this MSC is accepted, the property name +`org.matrix.mscxxxx.signing_public_key` should be used in place of +`signing_public_key`, and `org.matrix.mscxxxx.authenticated` should be used in +place of `authenticated`. No unstable prefix is used for the `signatures` +property since it uses the existing definition of JSON signing. + +## Dependencies + +None From a3751f579f235212bd46d02c967ed403ac3f2b2e Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Wed, 23 Aug 2023 16:33:49 -0400 Subject: [PATCH 02/13] use MSC number --- ...{xxxx-signed-key-backup.md => 4048-signed-key-backup.md} | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) rename proposals/{xxxx-signed-key-backup.md => 4048-signed-key-backup.md} (97%) diff --git a/proposals/xxxx-signed-key-backup.md b/proposals/4048-signed-key-backup.md similarity index 97% rename from proposals/xxxx-signed-key-backup.md rename to proposals/4048-signed-key-backup.md index 9d7001ebd9c..6e5b79c41f8 100644 --- a/proposals/xxxx-signed-key-backup.md +++ b/proposals/4048-signed-key-backup.md @@ -1,4 +1,4 @@ -# MSCxxxx: Signed key backup +# MSC4048: Signed key backup The [server-side key backups](https://spec.matrix.org/unstable/client-server-api/#server-side-key-backups) @@ -98,8 +98,8 @@ message. ## Unstable prefix Until this MSC is accepted, the property name -`org.matrix.mscxxxx.signing_public_key` should be used in place of -`signing_public_key`, and `org.matrix.mscxxxx.authenticated` should be used in +`org.matrix.msc4048.signing_public_key` should be used in place of +`signing_public_key`, and `org.matrix.msc4048.authenticated` should be used in place of `authenticated`. No unstable prefix is used for the `signatures` property since it uses the existing definition of JSON signing. From 97c371146a824a8d1f2ed5d02628a5c0ee4fc1f3 Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Thu, 31 Aug 2023 09:14:00 -0400 Subject: [PATCH 03/13] Apply suggestions from code review Co-authored-by: Andrew Ferrazzutti --- proposals/4048-signed-key-backup.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/proposals/4048-signed-key-backup.md b/proposals/4048-signed-key-backup.md index 6e5b79c41f8..f39127524a0 100644 --- a/proposals/4048-signed-key-backup.md +++ b/proposals/4048-signed-key-backup.md @@ -4,12 +4,12 @@ The [server-side key backups](https://spec.matrix.org/unstable/client-server-api/#server-side-key-backups) allows clients to store event decryption keys so that when the user logs in to a new device, they can decrypt old messages. The current algorithm encrypts -the event keys using a symmetric algorithm, allowing clients to upload keys to +the event keys using an asymmetric algorithm, allowing clients to upload keys to the backup without necessarily giving them the ability to read from the backup. For example, this allows for a partially-trusted client to be able to read (and save the keys for) current messages, but not read old messages. -However, since the event decryption keys are encrypted using a symmetric +However, since the event decryption keys are encrypted using an asymmetric algorithm, this allows anyone who knows the public key to write to the backup. As a result, keys loaded from the backup must be marked as unauthenticated, leading to [usability @@ -21,7 +21,7 @@ which ensures that only someone who knows the secret key can write to the backup. However this removes the ability for a client to be able to write to the backup without being able to read from it. -We propose to continue using a symmetric encryption algorithm in the backup, +We propose to continue using an asymmetric encryption algorithm in the backup, but to ensure authenticity by signing the backup data. ## Proposal @@ -89,7 +89,7 @@ fact come from them. This is somewhat mitigated by the fact that obtaining the Megolm session requires the decryption key for the backup. In addition, the deniability -property is mainly refers to the fact that a recipient cannot prove the +property mainly refers to the fact that a recipient cannot prove the authenticity of the message to a third party, and usually is not concerned with preventing self-incrimination. And in fact, a confiscated device may already have enough information to sufficiently prove that the device's owner sent a From af43417bd262a43ff652ed3d0e1d541e90c6f011 Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Thu, 31 Aug 2023 21:56:07 -0400 Subject: [PATCH 04/13] add comment about signing key --- proposals/4048-signed-key-backup.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/proposals/4048-signed-key-backup.md b/proposals/4048-signed-key-backup.md index f39127524a0..e52945fa7c0 100644 --- a/proposals/4048-signed-key-backup.md +++ b/proposals/4048-signed-key-backup.md @@ -79,6 +79,14 @@ As mentioned above, we could switch to using a symmetric encryption algorithm for the key backup. However, this is not backwards-compatible, and does not allow for clients that can write to the backup without reading. +Rather than using a new signing key, we could use an existing signing key, such +as one of the cross-signing keys. This would remove the need for users to +enter their Secret Storage key to add the new signing key. However, this means +that a user cannot create a key backup without also using cross-signing. Using +a separate key also allows the user to give someone else (such as a bot) +permission to write to their backups without allowing them to perform any +cross-signing operations. + ## Security considerations Being able to prove authenticity of keys may affect the deniability of From 1757284f4c23f65506d8ba6e699f36822a10e4e3 Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Mon, 25 Sep 2023 18:54:18 -0400 Subject: [PATCH 05/13] switch to using MAC --- proposals/4048-signed-key-backup.md | 112 ++++++++++++++++------------ 1 file changed, 63 insertions(+), 49 deletions(-) diff --git a/proposals/4048-signed-key-backup.md b/proposals/4048-signed-key-backup.md index e52945fa7c0..e1924742390 100644 --- a/proposals/4048-signed-key-backup.md +++ b/proposals/4048-signed-key-backup.md @@ -1,4 +1,4 @@ -# MSC4048: Signed key backup +# MSC4048: Authenticated key backup The [server-side key backups](https://spec.matrix.org/unstable/client-server-api/#server-side-key-backups) @@ -22,56 +22,52 @@ backup. However this removes the ability for a client to be able to write to the backup without being able to read from it. We propose to continue using an asymmetric encryption algorithm in the backup, -but to ensure authenticity by signing the backup data. +but to ensure authenticity by producing a MAC using a key derived from the +backup's decryption key. ## Proposal -A user has a new signing key, referred to as the "backup signing key", used to -sign key backups using the ed25519 signature algorithm. The private key can be -shared/stored using [the Secrets +A user who has a key backup derives a new backup MAC key by performing HKDF on +the backup decryption key (as raw unencoded bytes) with no salt and an info +parameter if `"MATRIX_BACKUP_MAC_KEY"` and generating 32 bytes (256 bits): + + mac_key = HKDF("", decryption_key, "MATRIX_BACKUP_MAC_KEY", 32) + +The signing key can be shared/stored using [the Secrets module](https://spec.matrix.org/unstable/client-server-api/#secrets) using the -name `m.key_backup.signing`. +name `m.key_backup.mac`. -The `AuthData` object for the [`m.megolm_backup.v1.curve25519-aes-sha2` key +The `SessionData` object for the [`m.megolm_backup.v1.curve25519-aes-sha2` key backup algorithm](https://spec.matrix.org/unstable/client-server-api/#backup-algorithm-mmegolm_backupv1curve25519-aes-sha2) -has a new optional property called `signing_public_key`, contains the public -key of the backup signing key, encoded in unpadded base64. If the `AuthData` -is not signed by the user's master signing key or by a verified device -belonging to the same user, the backup signing key must be ignored, and all -keys in the backup must be treated as being unsigned. - -The `SessionData` object for the `m.megolm_backup.v1.curve25519-aes-sha2` key -backup algorithm has two new optional properties: - -- a `signatures` property: the `SessionData` is a [signed JSON - object](https://spec.matrix.org/unstable/appendices/#signing-json), signed - using the backup signing key, using the public key (encoded in unpadded - base64) as the key ID -- a boolean `authenticated` property, defaulting to `false`: indicates whether - the device that uploaded the key to the backup believes that the key belongs - to the given `sender_key`. This is true if: a) the key was received via an - Olm-encrypted `m.room_key` event from the `sender_key`, b) the key was - received via a trusted key forward - ([MSC3879](https://github.com/matrix-org/matrix-spec-proposals/pull/3879)), - or c) the key was downloaded from the key backup, with the `authenticated` - property set to `true` and signed by a trusted key. If the `SessionData` is - not signed by the backup signing key, then this flag must be treated as being - `false`. - -The `mac` property in the cleartext `session_data` property of the -`KeyBackupData` is deprecated. Clients should continue to produce it for -compatibility with older clients, but should no longer use it to verify the -contents of the backup if the `SessionData` object is signed. +key backup algorithm has a new optional `authenticated` property, defaulting to +`false`. This property indicates whether the device that uploaded the key to +the backup believes that the key belongs to the given `sender_key`. This is +true if: a) the key was received via an Olm-encrypted `m.room_key` event from +the `sender_key`, b) the key was received via a trusted key forward +([MSC3879](https://github.com/matrix-org/matrix-spec-proposals/pull/3879)), or +c) the key was downloaded from the key backup, with the `authenticated` +property set to `true` and signed by a trusted key. If the `session_data` does +not have a `mac2` property (see below), then this flag must be treated as being +`false`. + +No changes are made to the `AuthData` for the +`m.megolm_backup.v1.curve25519-aes-sha2` key backup algorithm. + +The following changes are made to the cleartext `session_data` property of the +`KeyBackupData` object is deprecated: + +- a new `mac2` [FIXME: get a better name. suggestions?] property is added, + which is a MAC of the `SessionData` ciphertext (priory to base64-encoding), + using HMAC-SHA-256 with the backup MAC key derived above. +- the current `mac` property is deprecated. Clients should continue to produce + it for compatibility with older clients, but should no longer use it to + verify the contents of the backup if the `mac2` property is present. ## Potential issues -As the `AuthData` is changed, a new backup version will need to be created. A -client will need to download all existing keys and re-upload them. - In order to store a new secret in the Secret Storage, clients may need to -prompt the user for the Secret Storage key. Clients may need to do so already -to download all the current keys from the backup. +prompt the user for the Secret Storage key. ## Alternatives @@ -79,14 +75,33 @@ As mentioned above, we could switch to using a symmetric encryption algorithm for the key backup. However, this is not backwards-compatible, and does not allow for clients that can write to the backup without reading. -Rather than using a new signing key, we could use an existing signing key, such -as one of the cross-signing keys. This would remove the need for users to -enter their Secret Storage key to add the new signing key. However, this means -that a user cannot create a key backup without also using cross-signing. Using -a separate key also allows the user to give someone else (such as a bot) +Rather than using a new MAC key, we could use an existing signing key, such as +one of the cross-signing keys. This would remove the need for users to enter +their Secret Storage key to add the new signing key. However, this means that +a user cannot create a key backup without also using cross-signing. Using a +separate key also allows the user to give someone else (such as a bot) permission to write to their backups without allowing them to perform any cross-signing operations. +A previous version of this MSC used a signing key that was generated randomly. +The method presented in the current version has the following advantages: + +- no changes to `AuthData` are necessary, so a new backup version is not + required +- a MAC is faster to calculate. The main advantage of a signature is that it + allows one to verify the signature without knowing the private key, but in + this case, reading is a more privileged action than writing, and writers + already need to know the private/secret key. +- since the MAC key is derived from the decryption key, two clients can be + upgraded at the same time without interfering with each other, as they will + derive the same MAC key + +A disadvantage of the currently-proposed method versus the previous proposal is +that migration requires that the user gives the client access to the backup +decryption key in order to derive the MAC key. However, in both proposals, +most clients would require that the user enter their default SSSS key, which +would give them access to the decryption key anyways. + ## Security considerations Being able to prove authenticity of keys may affect the deniability of @@ -106,10 +121,9 @@ message. ## Unstable prefix Until this MSC is accepted, the property name -`org.matrix.msc4048.signing_public_key` should be used in place of -`signing_public_key`, and `org.matrix.msc4048.authenticated` should be used in -place of `authenticated`. No unstable prefix is used for the `signatures` -property since it uses the existing definition of JSON signing. +`org.matrix.msc4048.authenticated` should be used in place of `authenticated` +in the `SessionData` object, and the property name `org.matrix.msc4048.mac2` +should be used in place of `mac2` in the `session_data` property. ## Dependencies From 428b53dcb19437ce6efa7f942d8d7ddc6bc9160f Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Mon, 25 Sep 2023 19:08:03 -0400 Subject: [PATCH 06/13] add explicit construction instructions --- proposals/4048-signed-key-backup.md | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/proposals/4048-signed-key-backup.md b/proposals/4048-signed-key-backup.md index e1924742390..44575ecf9e7 100644 --- a/proposals/4048-signed-key-backup.md +++ b/proposals/4048-signed-key-backup.md @@ -64,6 +64,31 @@ The following changes are made to the cleartext `session_data` property of the it for compatibility with older clients, but should no longer use it to verify the contents of the backup if the `mac2` property is present. +The [construction of the `session_data` +property](https://spec.matrix.org/unstable/client-server-api/#backup-algorithm-mmegolm_backupv1curve25519-aes-sha2) +thus becomes: + +1. Encode the session key to be backed up as a JSON object using the + SessionData. +2. Generate an ephemeral curve25519 key, and perform an ECDH with the ephemeral + key and the backup’s public key to generate a shared secret. The public half + of the ephemeral key, encoded using unpadded base64, becomes the `ephemeral` + property of the `session_data`. +3. Using the shared secret, generate 80 bytes by performing an HKDF using + SHA-256 as the hash, with a salt of 32 bytes of 0, and with the empty string + as the info. The first 32 bytes are used as the AES key, the next 32 bytes + are used as the MAC key, and the last 16 bytes are used as the AES + initialization vector. +4. Stringify the JSON object, and encrypt it using AES-CBC-256 with 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`. +6. Pass the raw encrypted data (prior to base64 encoding) through HMAC-SHA-256 + using the backup MAC key. The MAC is base64-encoded (unpadded), and becomes + the `mac2` property of the `session_data`. + ## Potential issues In order to store a new secret in the Secret Storage, clients may need to From 6ed48ef97bf6f3257a3f46eea69396b734dbaaa0 Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Thu, 28 Sep 2023 21:03:26 -0400 Subject: [PATCH 07/13] Apply suggestions from code review Co-authored-by: Denis Kasak --- proposals/4048-signed-key-backup.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/proposals/4048-signed-key-backup.md b/proposals/4048-signed-key-backup.md index 44575ecf9e7..f6949d198af 100644 --- a/proposals/4048-signed-key-backup.md +++ b/proposals/4048-signed-key-backup.md @@ -29,11 +29,11 @@ backup's decryption key. A user who has a key backup derives a new backup MAC key by performing HKDF on the backup decryption key (as raw unencoded bytes) with no salt and an info -parameter if `"MATRIX_BACKUP_MAC_KEY"` and generating 32 bytes (256 bits): +parameter of `"MATRIX_BACKUP_MAC_KEY"` and generating 32 bytes (256 bits): - mac_key = HKDF("", decryption_key, "MATRIX_BACKUP_MAC_KEY", 32) + backup_mac_key = HKDF("", decryption_key, "MATRIX_BACKUP_MAC_KEY", 32) -The signing key can be shared/stored using [the Secrets +The backup MAC key can be shared/stored using [the Secrets module](https://spec.matrix.org/unstable/client-server-api/#secrets) using the name `m.key_backup.mac`. From 3b34542a0753a2b1c93e06f2cd814ec1376b1398 Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Thu, 28 Sep 2023 21:33:42 -0400 Subject: [PATCH 08/13] more clarifications and tweaks --- proposals/4048-signed-key-backup.md | 52 ++++++++++++++++++++--------- 1 file changed, 37 insertions(+), 15 deletions(-) diff --git a/proposals/4048-signed-key-backup.md b/proposals/4048-signed-key-backup.md index f6949d198af..c98bb46740a 100644 --- a/proposals/4048-signed-key-backup.md +++ b/proposals/4048-signed-key-backup.md @@ -35,7 +35,10 @@ parameter of `"MATRIX_BACKUP_MAC_KEY"` and generating 32 bytes (256 bits): The backup MAC key can be shared/stored using [the Secrets module](https://spec.matrix.org/unstable/client-server-api/#secrets) using the -name `m.key_backup.mac`. +name `m.megolm_backup.v1.mac`. Note that if the backup decryption key (the +secret using the name `m.megolm_backup.v1`) is stored/shared, then the backup +MAC key does not need to be stored/shared as it can be derived from the backup +decryption key. The `SessionData` object for the [`m.megolm_backup.v1.curve25519-aes-sha2` key backup @@ -47,9 +50,9 @@ true if: a) the key was received via an Olm-encrypted `m.room_key` event from the `sender_key`, b) the key was received via a trusted key forward ([MSC3879](https://github.com/matrix-org/matrix-spec-proposals/pull/3879)), or c) the key was downloaded from the key backup, with the `authenticated` -property set to `true` and signed by a trusted key. If the `session_data` does -not have a `mac2` property (see below), then this flag must be treated as being -`false`. +property set to `true` and was authenticated (for example using the method from +this proposal). If the `session_data` does not have a `mac2` property (see +below), then this flag must be treated as being `false`. No changes are made to the `AuthData` for the `m.megolm_backup.v1.curve25519-aes-sha2` key backup algorithm. @@ -62,7 +65,10 @@ The following changes are made to the cleartext `session_data` property of the using HMAC-SHA-256 with the backup MAC key derived above. - the current `mac` property is deprecated. Clients should continue to produce it for compatibility with older clients, but should no longer use it to - verify the contents of the backup if the `mac2` property is present. + verify the contents of the backup if the `mac2` property is present. Clients + should also accept `session_data` that does not have the `mac` property if + the `mac2` property is present, as the `mac` property may become optional in + the future. The [construction of the `session_data` property](https://spec.matrix.org/unstable/client-server-api/#backup-algorithm-mmegolm_backupv1curve25519-aes-sha2) @@ -89,10 +95,19 @@ thus becomes: using the backup MAC key. The MAC is base64-encoded (unpadded), and becomes the `mac2` property of the `session_data`. +FIXME: should the server compare the `mac2` when a client uploads a key to the +backup, when deciding whether to keep the existing key or replace it with a new +key? + ## Potential issues -In order to store a new secret in the Secret Storage, clients may need to -prompt the user for the Secret Storage key. +For users with existing backups, in order to start storing backup keys using +this format, the user may need to enter their Secret Storage key so that the +client can obtain the backup decryption key, if it does not already have it +cached, in order to derive the backup MAC key. If a user has multiple clients, +one client may try to obtain the backup MAC key from other clients using Secret +Sharing, but it does not have a way of knowing which clients, if any, have the +backup MAC key. ## Alternatives @@ -120,6 +135,9 @@ The method presented in the current version has the following advantages: - since the MAC key is derived from the decryption key, two clients can be upgraded at the same time without interfering with each other, as they will derive the same MAC key +- the MAC is calculated after encryption, and hence is verified before + decryption, so we know that it is authenticated before we do any processing + on it A disadvantage of the currently-proposed method versus the previous proposal is that migration requires that the user gives the client access to the backup @@ -130,10 +148,10 @@ would give them access to the decryption key anyways. ## Security considerations Being able to prove authenticity of keys may affect the deniability of -messages: if a user has a Megolm session in their key backup that is signed by their -backup signing key, and the session data indicates that it originated from one -of their devices, this could be used as evidence that the Megolm session did in -fact come from them. +messages: if a user has a Megolm session in their key backup that is MAC'ed by +their backup MAC key, and the session data indicates that it originated from +one of their devices, this could be used as evidence that the Megolm session +did in fact come from them. This is somewhat mitigated by the fact that obtaining the Megolm session requires the decryption key for the backup. In addition, the deniability @@ -145,10 +163,14 @@ message. ## Unstable prefix -Until this MSC is accepted, the property name -`org.matrix.msc4048.authenticated` should be used in place of `authenticated` -in the `SessionData` object, and the property name `org.matrix.msc4048.mac2` -should be used in place of `mac2` in the `session_data` property. +Until this MSC is accepted, the following unstable names should be used: + +- the property name `org.matrix.msc4048.authenticated` should be used in place + of `authenticated` in the `SessionData` object, +- the property name `org.matrix.msc4048.mac2` should be used in place of `mac2` + in the `session_data` property, +- the SSSS identifier `org.matrix.msc4048.mac` should be used in place of + `m.megolm_backup.v1.mac`. ## Dependencies From 2bf49b4b7ef49bf0afc4fed2de838173139ec7ff Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Fri, 29 Sep 2023 10:47:00 -0400 Subject: [PATCH 09/13] Apply suggestions from code review Co-authored-by: Denis Kasak --- proposals/4048-signed-key-backup.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/proposals/4048-signed-key-backup.md b/proposals/4048-signed-key-backup.md index c98bb46740a..36643628881 100644 --- a/proposals/4048-signed-key-backup.md +++ b/proposals/4048-signed-key-backup.md @@ -58,7 +58,7 @@ No changes are made to the `AuthData` for the `m.megolm_backup.v1.curve25519-aes-sha2` key backup algorithm. The following changes are made to the cleartext `session_data` property of the -`KeyBackupData` object is deprecated: +`KeyBackupData` object: - a new `mac2` [FIXME: get a better name. suggestions?] property is added, which is a MAC of the `SessionData` ciphertext (priory to base64-encoding), @@ -75,8 +75,8 @@ property](https://spec.matrix.org/unstable/client-server-api/#backup-algorithm-m thus becomes: 1. Encode the session key to be backed up as a JSON object using the - SessionData. -2. Generate an ephemeral curve25519 key, and perform an ECDH with the ephemeral + `SessionData`. +2. Generate an ephemeral Curve25519 key, and perform an ECDH with the ephemeral key and the backup’s public key to generate a shared secret. The public half of the ephemeral key, encoded using unpadded base64, becomes the `ephemeral` property of the `session_data`. @@ -126,18 +126,18 @@ cross-signing operations. A previous version of this MSC used a signing key that was generated randomly. The method presented in the current version has the following advantages: -- no changes to `AuthData` are necessary, so a new backup version is not - required -- a MAC is faster to calculate. The main advantage of a signature is that it +- No changes to `AuthData` are necessary, so a new backup version is not + required. +- A MAC is faster to calculate. The main advantage of a signature is that it allows one to verify the signature without knowing the private key, but in this case, reading is a more privileged action than writing, and writers already need to know the private/secret key. -- since the MAC key is derived from the decryption key, two clients can be +- Since the MAC key is derived from the decryption key, two clients can be upgraded at the same time without interfering with each other, as they will - derive the same MAC key -- the MAC is calculated after encryption, and hence is verified before + derive the same MAC key. +- The MAC is calculated after encryption, and hence is verified before decryption, so we know that it is authenticated before we do any processing - on it + on it. A disadvantage of the currently-proposed method versus the previous proposal is that migration requires that the user gives the client access to the backup From 1403cb44606b1f3426ecad318a9673f20375b40b Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Fri, 29 Sep 2023 20:13:15 -0400 Subject: [PATCH 10/13] fix typo --- proposals/4048-signed-key-backup.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/4048-signed-key-backup.md b/proposals/4048-signed-key-backup.md index 36643628881..bf64693891e 100644 --- a/proposals/4048-signed-key-backup.md +++ b/proposals/4048-signed-key-backup.md @@ -61,7 +61,7 @@ The following changes are made to the cleartext `session_data` property of the `KeyBackupData` object: - a new `mac2` [FIXME: get a better name. suggestions?] property is added, - which is a MAC of the `SessionData` ciphertext (priory to base64-encoding), + which is a MAC of the `SessionData` ciphertext (prior to base64-encoding), using HMAC-SHA-256 with the backup MAC key derived above. - the current `mac` property is deprecated. Clients should continue to produce it for compatibility with older clients, but should no longer use it to From 77401a0d944f0196b63d98ac8a8c40bd5b145ec9 Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Thu, 9 Nov 2023 14:35:36 -0500 Subject: [PATCH 11/13] Define new backup algorithm, and other improvements - define new HMAC method that covers other fields - indicate key source for unauthenticated keys - define migration --- proposals/4048-signed-key-backup.md | 183 +++++++++++++++++++++------- 1 file changed, 139 insertions(+), 44 deletions(-) diff --git a/proposals/4048-signed-key-backup.md b/proposals/4048-signed-key-backup.md index bf64693891e..e8524bcbecd 100644 --- a/proposals/4048-signed-key-backup.md +++ b/proposals/4048-signed-key-backup.md @@ -33,42 +33,99 @@ parameter of `"MATRIX_BACKUP_MAC_KEY"` and generating 32 bytes (256 bits): backup_mac_key = HKDF("", decryption_key, "MATRIX_BACKUP_MAC_KEY", 32) -The backup MAC key can be shared/stored using [the Secrets +The backup MAC key can be shared using [the Secrets module](https://spec.matrix.org/unstable/client-server-api/#secrets) using the name `m.megolm_backup.v1.mac`. Note that if the backup decryption key (the -secret using the name `m.megolm_backup.v1`) is stored/shared, then the backup -MAC key does not need to be stored/shared as it can be derived from the backup -decryption key. - -The `SessionData` object for the [`m.megolm_backup.v1.curve25519-aes-sha2` key -backup -algorithm](https://spec.matrix.org/unstable/client-server-api/#backup-algorithm-mmegolm_backupv1curve25519-aes-sha2) -key backup algorithm has a new optional `authenticated` property, defaulting to -`false`. This property indicates whether the device that uploaded the key to -the backup believes that the key belongs to the given `sender_key`. This is -true if: a) the key was received via an Olm-encrypted `m.room_key` event from -the `sender_key`, b) the key was received via a trusted key forward -([MSC3879](https://github.com/matrix-org/matrix-spec-proposals/pull/3879)), or -c) the key was downloaded from the key backup, with the `authenticated` -property set to `true` and was authenticated (for example using the method from -this proposal). If the `session_data` does not have a `mac2` property (see -below), then this flag must be treated as being `false`. - -No changes are made to the `AuthData` for the -`m.megolm_backup.v1.curve25519-aes-sha2` key backup algorithm. - -The following changes are made to the cleartext `session_data` property of the -`KeyBackupData` object: - -- a new `mac2` [FIXME: get a better name. suggestions?] property is added, - which is a MAC of the `SessionData` ciphertext (prior to base64-encoding), - using HMAC-SHA-256 with the backup MAC key derived above. -- the current `mac` property is deprecated. Clients should continue to produce - it for compatibility with older clients, but should no longer use it to - verify the contents of the backup if the `mac2` property is present. Clients - should also accept `session_data` that does not have the `mac` property if - the `mac2` property is present, as the `mac` property may become optional in - the future. +secret using the name `m.megolm_backup.v1`) is shared, then the backup MAC key +does not need to be shared as it can be derived from the backup decryption +key. Since the backup decryption key is usually stored in Secret Storage, the +backup MAC key does not need to be stored. + +### `m.backup.v2.curve25519-aes-sha2` + +A new backup algorithm is defined, identified by the name +"`m.backup.v2.curve25519-aes-sha2`". In addition to incrementing the version +number, this name drops the "megolm", as it is expected that other types of +keys may be stored in it, for example [MLS +groups](https://github.com/matrix-org/matrix-spec-proposals/pull/4038). + +The intention of creating a new backup algorithm is to prevent an attacker from +uploading additional keys that cannot be authenticated. + +The `auth_data` is the same as with `m.megolm_backup.v1.curve25519-aes-sha2`. + +The `session_data` is constructed as follows: + +1. Encode the session key to be backed up as a JSON object using the + `SessionDataV2` format defined below. +2. Generate an ephemeral curve25519 key, and perform an ECDH with the ephemeral + key and the backup’s public key to generate a shared secret. The public half + of the ephemeral key, encoded using unpadded base64, becomes the `ephemeral` + property of the `session_data`. +3. Using the shared secret, generate 80 bytes by performing an HKDF using + SHA-256 as the hash, with a salt of 32 bytes of 0, and with the empty string + as the info. The first 32 bytes are used as the AES key, the next 32 bytes + are discarded, and the last 16 bytes are used as the AES initialization + vector. (This is the same as the key generation for + `m.megolm_backup.v1.curve25519-aes-sha2`, except that the generated MAC key + is discarded since it is unused.) +4. Stringify the JSON object, and encrypt it using AES-CBC-256 with PKCS#7 + padding. This encrypted data, encoded using unpadded base64, becomes the + `ciphertext` property of the `session_data`. +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 `hmac-sha-256:1` property of the + `signatures` property of `session_data`. + +Thus the `session_data` property has `ephemeral`, `ciphertext`, and +`signatures` properties, with the `signatures` property having a +`hmac-sha-256:1` property. Keys without a `signatures`.`hmac-sha-256:1` +property 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. + +The `SessionDataV2` has algorithm-dependent and algorithm-independent +properties. The algorithm-independent properties are: + +- `algorithm`: (required string) the end-to-end message encryption algorithm that the + key is for. The values are the same as for the `algorithm` property in the + `m.room_key` event. For example, for Megolm keys, this is + `m.megolm.v1.aes-sha2`. +- `unauthenticated`: (optional string) if not present, the key is considered to + be authenticated, that is, the device that uploaded the key to the backup + believes that the key belongs to the recorded sender, as defined by the key + algorithm (with `m.megolm.v1.aes-sha2`, the sender is given in the + `sender_key` property). A key is considered to be authenticated if: a) the + key was received via an Olm-encrypted `m.room_key` event from the + `sender_key`, b) the key was received via a trusted key forward + ([MSC3879](https://github.com/matrix-org/matrix-spec-proposals/pull/3879)), + or c) the key was downloaded from the key backup where it is marked as + authenticated, and the data can be authenticated (for example using the + method from this proposal). If the key is not considered to be + authenticated, this property indicates the source of the key. Currently + defined values are: `m.undefined`, which indicates that the source is not + specified; `m.legacy-v1`, which indicates that the key was an unauthenticated + key from a `m.megolm_backup.v1.curve25519-aes-sha2` backup ([see + below](#migrating-keys)); and `m.forwarded_room_key`, which indicates that + the key came from an untrusted key forward. (FIXME: do we also want to + encode the source of the key forward?) Clients may create other values to + specify other sources, using the Java package naming convention; clients + should consider unknown values to be `m.undefined`. + +For the `m.megolm.v1.aes-sha2` algorithm, the algorithm-dependent properties +are the `forwarding_curve25519_key_chain`, `sender_claimed_keys`, `sender_key`, +and `session_key` properties defined for +`m.megolm_backup.v1.curve25519-aes-sha2`. + +### `m.megolm_backup.v1.curve25519-aes-sha2` + +Megolm keys may be uploaded to a `m.megolm_backup.v1.curve25519-aes-sha2` +backup using the `m.backup.v2.curve25519-aes-sha2` format, provided the +`session_data` also contains the `mac` property as required for the +`m.megolm_backup.v1.curve25519-aes-sha2` algorithm. The [construction of the `session_data` property](https://spec.matrix.org/unstable/client-server-api/#backup-algorithm-mmegolm_backupv1curve25519-aes-sha2) @@ -91,13 +148,37 @@ thus becomes: 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`. -6. Pass the raw encrypted data (prior to base64 encoding) through HMAC-SHA-256 - using the backup MAC key. The MAC is base64-encoded (unpadded), and becomes - the `mac2` property of the `session_data`. +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 `hmac-sha-256:1` property of the + `signatures` property of `session_data`. + +FIXME: should the server compare the `signatures`.`hmac-sha-256:1` 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`.`hmac-sha-256:1` property in the cleartext `session_data` +property. + +#### Migrating keys -FIXME: should the server compare the `mac2` when a client uploads a key to the -backup, when deciding whether to keep the existing key or replace it with a new -key? +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`.`hmac-sha-256:1` property in the cleartext `session_data` property +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`.`hmac-sha-256:1` 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`.`hmac-sha-256:1` property may be uploaded to the new backup +unchanged, as they will be valid `m.backup.v2.curve25519-aes-sha2`-format +keys. ## Potential issues @@ -165,13 +246,27 @@ message. Until this MSC is accepted, the following unstable names should be used: -- the property name `org.matrix.msc4048.authenticated` should be used in place - of `authenticated` in the `SessionData` object, -- the property name `org.matrix.msc4048.mac2` should be used in place of `mac2` - in the `session_data` property, +- the algorithm name `org.matrix.msc4048.curve25519-aes-sha2` should + 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:1` should be used in place + of `hmac-sha-256:1` in the `signatures` property, - the SSSS identifier `org.matrix.msc4048.mac` should be used in place of `m.megolm_backup.v1.mac`. +### Migration to stable names + +After this MSC is accepted, clients that understand the +`org.matrix.msc4048.curve25519-aes-sha2` algorithm name should +migrate the user to a backup using the accepted version of the +`m.backup.v2.curve25519-aes-sha2` algorithm. Keys that use the unstable +property names should be re-uploaded using the stable names. + +This includes migrating +`org.matrix.msc4048.curve25519-aes-sha2`-format keys uploaded to +`m.megolm_backup.v1.curve25519-aes-sha2` backups. + ## Dependencies None From 05f1fee21b64f871cc903080f17da885eed19d1f Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Fri, 17 Nov 2023 16:50:25 -0500 Subject: [PATCH 12/13] fix naming --- proposals/4048-signed-key-backup.md | 68 +++++++++++++++++------------ 1 file changed, 39 insertions(+), 29 deletions(-) diff --git a/proposals/4048-signed-key-backup.md b/proposals/4048-signed-key-backup.md index e8524bcbecd..ad7e63ac4b1 100644 --- a/proposals/4048-signed-key-backup.md +++ b/proposals/4048-signed-key-backup.md @@ -75,13 +75,17 @@ 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 `hmac-sha-256:1` property of the - `signatures` property of `session_data`. + 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 -`hmac-sha-256:1` property. Keys without a `signatures`.`hmac-sha-256:1` -property 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 @@ -104,16 +108,18 @@ properties. The algorithm-independent properties are: ([MSC3879](https://github.com/matrix-org/matrix-spec-proposals/pull/3879)), or c) the key was downloaded from the key backup where it is marked as authenticated, and the data can be authenticated (for example using the - method from this proposal). If the key is not considered to be - authenticated, this property indicates the source of the key. Currently - defined values are: `m.undefined`, which indicates that the source is not - specified; `m.legacy-v1`, which indicates that the key was an unauthenticated - key from a `m.megolm_backup.v1.curve25519-aes-sha2` backup ([see + method from this proposal). + + If the key is not considered to be authenticated, this property indicates the + source of the key. Currently defined values are: `m.undefined`, which + indicates that the source is not specified; `m.legacy-v1`, which indicates + that the key was an unauthenticated key from a + `m.megolm_backup.v1.curve25519-aes-sha2` backup ([see below](#migrating-keys)); and `m.forwarded_room_key`, which indicates that the key came from an untrusted key forward. (FIXME: do we also want to encode the source of the key forward?) Clients may create other values to specify other sources, using the Java package naming convention; clients - should consider unknown values to be `m.undefined`. + should treat unknown values as `m.undefined`. For the `m.megolm.v1.aes-sha2` algorithm, the algorithm-dependent properties are the `forwarding_curve25519_key_chain`, `sender_claimed_keys`, `sender_key`, @@ -151,34 +157,37 @@ 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 `hmac-sha-256:1` property of the - `signatures` property of `session_data`. + base64-encoded (unpadded), and becomes the + {user_id}.`hmac-sha-256:backup_mac_key` property of the `signatures` + property of `session_data`. -FIXME: should the server compare the `signatures`.`hmac-sha-256:1` 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 +`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? 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`.`hmac-sha-256:1` property in the cleartext `session_data` -property. +`signatures`.{user_id}.`hmac-sha-256:backup_mac_key` 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`.`hmac-sha-256:1` property in the cleartext `session_data` property -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`.`hmac-sha-256:1` 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`.`hmac-sha-256:1` property may be uploaded to the new backup -unchanged, as they will be valid `m.backup.v2.curve25519-aes-sha2`-format -keys. +`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 +`m.backup.v2.curve25519-aes-sha2`-format keys. ## Potential issues @@ -250,8 +259,9 @@ 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:1` should be used in place - of `hmac-sha-256:1` in the `signatures` property, +- 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 SSSS identifier `org.matrix.msc4048.mac` should be used in place of `m.megolm_backup.v1.mac`. From 20b767f5f4ac616b10237c2fb23a1b4bfc8baa3f Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Thu, 23 Nov 2023 13:36:06 -0500 Subject: [PATCH 13/13] 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 ad7e63ac4b1..b8f1f3af583 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`.