From 05f1fee21b64f871cc903080f17da885eed19d1f Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Fri, 17 Nov 2023 16:50:25 -0500 Subject: [PATCH] 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 e8524bcbe..ad7e63ac4 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`.