|
|
@ -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
|
|
|
|
5. Encode the `session_data` as canonical JSON, as would be done when [signing
|
|
|
|
JSON](https://spec.matrix.org/unstable/appendices/#signing-details), and
|
|
|
|
JSON](https://spec.matrix.org/unstable/appendices/#signing-details), and
|
|
|
|
calculate the HMAC-SHA-256 MAC using the backup MAC key. The MAC is
|
|
|
|
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,
|
|
|
|
When verifying the MAC, the `session_data` is encoded as canonical JSON,
|
|
|
|
following the procedure as when signing JSON. That is, any additional
|
|
|
|
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
|
|
|
|
The `SessionDataV2` has algorithm-dependent and algorithm-independent
|
|
|
|
properties. The algorithm-independent properties are:
|
|
|
|
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
|
|
|
|
6. Encode the `session_data` as canonical JSON, as would be done when [signing
|
|
|
|
JSON](https://spec.matrix.org/unstable/appendices/#signing-details), and
|
|
|
|
JSON](https://spec.matrix.org/unstable/appendices/#signing-details), and
|
|
|
|
calculate the HMAC-SHA-256 MAC using the backup MAC key. The MAC is
|
|
|
|
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
|
|
|
|
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
|
|
|
|
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,
|
|
|
|
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
|
|
|
|
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
|
|
|
|
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
|
|
|
|
#### Migrating keys
|
|
|
|
|
|
|
|
|
|
|
|
When migrating keys from a `m.megolm_backup.v1.curve25519-aes-sha2` backup to a
|
|
|
|
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
|
|
|
|
`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.
|
|
|
|
`m.backup.v2.curve25519-aes-sha2`-format keys.
|
|
|
|
|
|
|
|
|
|
|
|
## Potential issues
|
|
|
|
## 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`.
|
|
|
|
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
|
|
|
|
- the property name `org.matrix.msc4048.unauthenticated` should be used in place
|
|
|
|
of `unauthenticated` in the `SessionData` object,
|
|
|
|
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
|
|
|
|
- the SSSS identifier `org.matrix.msc4048.mac` should be used in place of
|
|
|
|
`m.megolm_backup.v1.mac`.
|
|
|
|
`m.megolm_backup.v1.mac`.
|
|
|
|
|
|
|
|
|
|
|
|