You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
matrix-spec-proposals/proposals/2472-symmetric-ssss.md

89 lines
4.5 KiB
Markdown

# Symmetric SSSS
[MSC1946 (Secure Secret Storage and
Sharing)](https://github.com/matrix-org/matrix-doc/pull/1946) proposed a way of
storing encrypted secrets on the server. In the proposal, secrets were
encrypted using a Curve25519 key, which was chosen to allow easier migration
from key backups that we created before the backup key was stored using it.
However this does not provide any guarantees that data stored using the
proposal came from a trusted source. To remedy this, we propose to change the
encryption to use AES with a MAC to ensure that only someone who knows the key
is able to store data.
## Proposal
* The `m.secret_storage.v1.curve25519-aes-sha2` method proposed in MSC1946 is
removed.
* A new method, `m.secret_storage.v1.aes-hmac-sha2`, is added. With this
method, the Secret Storage key may be any size (though 256 bits is
recommended), and data is encrypted as follows:
1. Given the secret storage key, generate 64 bytes by performing an HKDF with
SHA-256 as the hash, a salt of 32 bytes of 0, and with the secret name as
the info. The first 32 bytes are used as the AES key, and the next 32 bytes
are used as the MAC key
2. Generate 16 random bytes, set bit 63 to 0 (in order to work around
differences in AES-CTR implementations), and use this as the AES
initialization vector. This becomes the `iv` property, encoded using base64.
3. Encrypt the data using AES-CTR-256 using the AES key generated above. This
encrypted data, encoded using base64, becomes the `ciphertext` property.
4. Pass the raw encrypted data (prior to base64 encoding) through HMAC-SHA-256
using the MAC key generated above. The resulting MAC is base64-encoded and
becomes the `mac` property.
(We use AES-CTR to match file encryption and key exports.)
If the key Secret Storage key is generated from a passphrase, information
about how to generate the key is stored in the `passphrase` property of the
key's account-data in a similar manner to what was done with the original
`m.secret_storage.v1.curve25519-aes-sha2` method, except that there is an
optional `bits` parameter that defaults to 256, and indicates the number of
bits that should be generated from PBKDF2 (in other words, the size of the
key).
* For the purposes of allowing clients to check whether a user has correctly
entered the key, clients should:
1. encrypt and MAC a message consisting of 32 bytes of 0 as described above,
using the empty string as the info parameter to the HKDF in step 1.
2. store the `iv` and `mac` in the `m.secret_storage.key.[key ID]`
account-data.
* The `passthrough` property specified in the "Encoding the recovery key for
server-side storage via MSC1946" section of MSC1219 is removed. The primary
purpose of that property was to allow easy migration of pre-MSC1946 backups,
so that users could reuse the backup recovery key as the Secret Storage key
without needing to re-enter the recovery key. However, since we are now
using a symmetric encryption algorithm, the client needs to know the key that
is used to encrypt, so the purpose of the field cannot be fulfilled.
* Signing the Secret Storage key with the user's master cross-signing key is no
longer required. The key is trusted on the basis of the user entering the
key/passphrase.
## Potential issues
Users who have data stored using the old encryption algorithm will need their
data migrated. Clients that support the old algorithm but not the new
algorithm will not be able to use the migrated secrets until they are updated
with the new algorithms. This should not be a major problem because the only
clients that are known to have implemented the old algorithm are Riot
Web/Android/iOS, and they have been upgraded to implement the new algorithm.
## Alternatives
Rather than switching to a symmetric encryption algorithm, we could stay with
an asymmetric encryption algorithm, and add on a method to authenticate the
data. However, it is much safer to use well-known cryptographic methods rather
than trying to invent something new. Since the main reason for using an
asymmetric scheme was to ease migration from older key backups without
requiring the user to re-enter the key, but this is no longer possible due to
the need to authenticate the data using the Secret Storage key, there is no
reason to stay with an asymmetric algorithm. It is also better to use
cryptographic methods already used in Matrix where possible, rather than
introducing something new.