archive
/
matrix-spec-proposals
mirror of https://github.com/matrix-org/matrix-spec-proposals
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Merge 20b767f5f4 into d6edcbd946

Browse Source
Hubert Chathi 3 weeks ago committed by GitHub
parent d6edcbd946 20b767f5f4
commit 91eae79b70
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
1 changed files with 275 additions and 0 deletions
Show Stats Download Patch File Download Diff File

275
proposals/4048-signed-key-backup.md
Unescape Escape View File

@ -0,0 +1,275 @@
# MSC4048: Authenticated 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 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 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
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 an asymmetric encryption algorithm in the backup,
but to ensure authenticity by producing a MAC using a key derived from the
backup's decryption key.
## Proposal
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 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 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 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 `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. 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:
- `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 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`,
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)
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. 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 `backup_mac` property of the
`unsigned` property of `session_data`.
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
`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
`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
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
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 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.
- 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
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
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
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
message.
## Unstable prefix
Until this MSC is accepted, the following unstable names should be used:
- 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.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`.
### 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
Write Preview
Loading…
Cancel
Save