294 lines
11 KiB
Markdown
294 lines
11 KiB
Markdown
# Secure Secret Storage and Sharing
|
||
|
||
Some features may require clients to store encrypted data on the server so that
|
||
it can be shared securely between clients. Clients may also wish to securely
|
||
send such data directly to each other. For example, key backups
|
||
([MSC1219](https://github.com/matrix-org/matrix-doc/issues/1219)) can store the
|
||
decryption key for the backups on the server, or cross-signing
|
||
([MSC1756](https://github.com/matrix-org/matrix-doc/pull/1756)) can store the
|
||
signing keys. This proposal presents a standardized way of storing such data.
|
||
|
||
## Changes
|
||
|
||
- [MSC2472](https://github.com/matrix-org/matrix-doc/pull/2472) changed the
|
||
encryption algorithm used from an asymmetric algorithm (Curve25519) to a
|
||
symmetric algorithm (AES).
|
||
|
||
## Proposal
|
||
|
||
Secrets are data that clients need to use and that are sent through or stored
|
||
on the server, but should not be visible to server operators. Secrets are
|
||
plain strings -- if clients need to use more complicated data, they must be
|
||
encoded as a string, such as by encoding as JSON.
|
||
|
||
### Storage
|
||
|
||
If secret data is stored on the server, it must be encrypted in order to
|
||
prevent homeserver administrators from being able to read it. A user can have
|
||
multiple keys used for encrypting data. This allows the user to selectively
|
||
decrypt data on clients. For example, the user could have one key that can
|
||
decrypt everything, and another key that can only decrypt their user-signing
|
||
key for cross-signing.
|
||
|
||
Key descriptions and secret data are both stored in the user's account_data.
|
||
|
||
#### Key storage
|
||
|
||
Each key has an ID, and the description of the key is stored in the user's
|
||
account_data using the event type `m.secret_storage.key.[key ID]`. The contents
|
||
of the account data for the key will include an `algorithm` property, which
|
||
indicates the encryption algorithm used, as well as a `name` property, which is
|
||
a human-readable name. Other properties depend on the encryption algorithm,
|
||
and are described below.
|
||
|
||
Example:
|
||
|
||
A key with ID `abcdefg` is stored in `m.secret_storage.key.abcdefg`
|
||
|
||
```json
|
||
{
|
||
"name": "Some key",
|
||
"algorithm": "m.secret_storage.v1.aes-hmac-sha2",
|
||
// ... other properties according to algorithm
|
||
}
|
||
```
|
||
|
||
A key can be marked as the "default" key by setting the user's account_data
|
||
with event type `m.secret_storage.default_key` to an object that has the ID of
|
||
the key as its `key` property. The default key will be used to encrypt all
|
||
secrets that the user would expect to be available on all their clients.
|
||
Unless the user specifies otherwise, clients will try to use the default key to
|
||
decrypt secrets.
|
||
|
||
#### Secret storage
|
||
|
||
Encrypted data is stored in the user's account_data using the event type
|
||
defined by the feature that uses the data. For example, decryption keys for
|
||
key backups could be stored under the type `m.megolm_backup.v1`,
|
||
or the self-signing key for cross-signing could be stored under the type
|
||
`m.cross_signing.self_signing`.
|
||
|
||
The account_data will have an `encrypted` property that is a map from key ID
|
||
to an object. The algorithm from the `m.secret_storage.key.[key ID]` data for
|
||
the given key defines how the other properties are interpreted, though it's
|
||
expected that most encryption schemes would have `ciphertext` and `mac`
|
||
properties, where the `ciphertext` property is the unpadded base64-encoded
|
||
ciphertext, and the `mac` is used to ensure the integrity of the data.
|
||
|
||
Example:
|
||
|
||
Some secret is encrypted using keys with ID `key_id_1` and `key_id_2`:
|
||
|
||
`org.example.some.secret`:
|
||
|
||
```json
|
||
{
|
||
"encrypted": {
|
||
"key_id_1": {
|
||
"ciphertext": "base64+encoded+encrypted+data",
|
||
"mac": "base64+encoded+mac",
|
||
// ... other properties according to algorithm property in
|
||
// m.secret_storage.key.key_id_1
|
||
},
|
||
"key_id_2": {
|
||
// ...
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
and the key descriptions for the keys would be:
|
||
|
||
`m.secret_storage.key.key_id_1`:
|
||
|
||
```json
|
||
{
|
||
"name": "Some key",
|
||
"algorithm": "m.secret_storage.v1.aes-hmac-sha2",
|
||
// ... other properties according to algorithm
|
||
}
|
||
```
|
||
|
||
`m.secret_storage.key.key_id_2`:
|
||
|
||
```json
|
||
{
|
||
"name": "Some other key",
|
||
"algorithm": "m.secret_storage.v1.aes-hmac-sha2",
|
||
// ... other properties according to algorithm
|
||
}
|
||
```
|
||
|
||
#### Encryption algorithms
|
||
|
||
##### `m.secret_storage.v1.aes-hmac-sha2`
|
||
|
||
Secrets are encrypted using AES-CTR-256 and MACed using HMAC-SHA-256. The data
|
||
is encrypted and MACed 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.)
|
||
|
||
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.
|
||
|
||
For example, the `m.secret_storage.key.key_id` for a key using this algorithm
|
||
could look like:
|
||
|
||
```json
|
||
{
|
||
"name": "m.default",
|
||
"algorithm": "m.secret_storage.v1.aes-hmac-sha2",
|
||
"iv": "random+data",
|
||
"mac": "mac+of+encrypted+zeros"
|
||
}
|
||
```
|
||
|
||
and data encrypted using this algorithm could look like this:
|
||
|
||
```json
|
||
{
|
||
"encrypted": {
|
||
"key_id": {
|
||
"iv": "16+bytes+base64",
|
||
"ciphertext": "base64+encoded+encrypted+data",
|
||
"mac": "base64+encoded+mac"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
###### Keys
|
||
|
||
When a user is given a raw key for `m.secret_storage.v1.aes-hmac-sha2`,
|
||
it will be encoded as follows (this is the same as what is proposed in MSC1703):
|
||
|
||
* prepend the two bytes 0x8b and 0x01 to the key
|
||
* compute a parity byte by XORing all bytes of the resulting string, and append
|
||
the parity byte to the string
|
||
* base58-encode the resulting byte string with the alphabet
|
||
'123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz'.
|
||
* format the resulting ASCII string into groups of 4 characters separated by
|
||
spaces.
|
||
|
||
When decoding a raw key, the process should be reversed, with the exception
|
||
that whitespace is insignificant in the user's ASCII input.
|
||
|
||
###### Passphrase
|
||
|
||
A user may wish to use a chosen passphrase rather than a randomly generated
|
||
key. In this case, information on how to generate the key from a passphrase
|
||
will be stored in the `passphrase` property of the `m.secret_storage.key.[key
|
||
ID]` account-data:
|
||
|
||
```json
|
||
{
|
||
"passphrase": {
|
||
"algorithm": "m.pbkdf2",
|
||
"salt": "MmMsAlty",
|
||
"iterations": 100000,
|
||
"bits": 256
|
||
},
|
||
...
|
||
}
|
||
```
|
||
|
||
**`m.pbkdf2`**
|
||
|
||
The key is generated using PBKDF2 using the salt given in the `salt` parameter,
|
||
and the number of iterations given in the `iterations` parameter. The key size
|
||
that is generated is given by the `bits` parameter, or 256 bits if no `bits`
|
||
parameter is given.
|
||
|
||
### Sharing
|
||
|
||
Rather than (or in addition to) storing secrets on the server encrypted by a
|
||
shared key, devices can send secrets to each other, encrypted using olm.
|
||
|
||
To request a secret, a client sends a `m.secret.request` device event with `action`
|
||
set to `request` to other devices, and `name` set to the name of the secret
|
||
that it wishes to retrieve. A device that wishes to share the secret will
|
||
reply with a `m.secret.send` event, encrypted using olm. When the original
|
||
client obtains the secret, it sends a `m.secret.request` event with `action`
|
||
set to `request_cancellation` to all devices other than the one that it received the
|
||
secret from. Clients should ignore `m.secret.send` events received from
|
||
devices that it did not send an `m.secret.request` event to.
|
||
|
||
Clients MUST ensure that they only share secrets with other devices that are
|
||
allowed to see them. For example, clients SHOULD only share secrets with
|
||
the user’s own devices that are verified and MAY prompt the user to confirm sharing the
|
||
secret.
|
||
|
||
If a feature allows secrets to be stored or shared, then for consistency it
|
||
SHOULD use the same name for both the account_data event type and the `name` in
|
||
the `m.secret.request`.
|
||
|
||
#### Event definitions
|
||
|
||
##### `m.secret.request`
|
||
|
||
Sent by a client to request a secret from another device. It is sent as an
|
||
unencrypted to-device event.
|
||
|
||
- `name`: (string) Required if `action` is `request`. The name of the secret
|
||
that is being requested.
|
||
- `action`: (enum) Required. One of ["request", "request_cancellation"].
|
||
- `requesting_device_id`: (string) Required. ID of the device requesting the
|
||
secret.
|
||
- `request_id`: (string) Required. A random string uniquely identifying the
|
||
request for a secret. If the secret is requested multiple times, it should be
|
||
reused. It should also reused in order to cancel a request.
|
||
|
||
##### `m.secret.send`
|
||
|
||
Sent by a client to share a secret with another device, in response to an
|
||
`m.secret.request` event. It MUST be encrypted as an `m.room.encrypted` event,
|
||
then sent as a to-device event.
|
||
|
||
- `request_id`: (string) Required. The ID of the request that this a response to.
|
||
- `secret`: (string) Required. The contents of the secret.
|
||
|
||
## Tradeoffs
|
||
|
||
Currently, only a public/private key mechanism is defined. It may be useful to
|
||
also define a secret key mechanism.
|
||
|
||
## Potential issues
|
||
|
||
Keeping all the data and keys in account data means that it may clutter up
|
||
`/sync` requests. However, clients can filter out the data that they are not interested
|
||
in. One possibility for addressing this would be to add a flag to the account
|
||
data to indicate whether it should come down the `/sync` or not.
|
||
|
||
## Security considerations
|
||
|
||
By storing information encrypted on the server, this allows the server operator
|
||
to read the information if they manage to get hold of the decryption keys.
|
||
In particular, if the key is based on a passphrase and the passphrase can be
|
||
guessed, then the secrets could be compromised. In order to help protect the
|
||
secrets, clients should provide feedback to the user when their chosen
|
||
passphrase is considered weak, and may also wish to prevent the user from
|
||
reusing their login password.
|
||
|
||
## Conclusion
|
||
|
||
This proposal presents a common way for bits of encrypted data to be stored on
|
||
a user's homeserver for use by various features.
|