|
|
|
|
|
### Secrets
|
|
|
|
|
|
{{% added-in v="1.1" %}}
|
|
|
|
|
|
Clients may have secret information that they wish to be made available
|
|
|
to other authorised clients, but that the server should not be able to
|
|
|
see, so the information must be encrypted as it passes through the
|
|
|
server. This can be done either asynchronously, by storing encrypted
|
|
|
data on the server for later retrieval, or synchronously, by sending
|
|
|
messages to each other.
|
|
|
|
|
|
Each secret has an identifier that is used by clients to refer to the
|
|
|
secret when storing, fetching, requesting, or sharing the secret.
|
|
|
Secrets are plain strings; structured data can be stored by encoding it
|
|
|
as a string.
|
|
|
|
|
|
#### Storage
|
|
|
|
|
|
When secrets are stored on the server, they are stored in the user's
|
|
|
[account-data](#client-config), using an event type equal to the
|
|
|
secret's identifier. The keys that secrets are encrypted with are
|
|
|
described by data that is also stored in the user's account-data. Users
|
|
|
can have multiple keys, allowing them to control what sets of secrets
|
|
|
clients can access, depending on what keys are given to them.
|
|
|
|
|
|
##### 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. Key descriptions may also have a `passphrase`
|
|
|
property for generating the key from a user-entered passphrase, as
|
|
|
described in [deriving keys from
|
|
|
passphrases](#deriving-keys-from-passphrases).
|
|
|
|
|
|
`KeyDescription`
|
|
|
|
|
|
| Parameter | Type | Description
|
|
|
|------------|-----------|-------------------------------------------------------------------------------------------------------------------------------------|
|
|
|
| name | string | Optional. The name of the key. If not given, the client may use a generic name such as "Unnamed key", or "Default key" if the key is marked as the default key (see below). |
|
|
|
| algorithm | string | **Required.** The encryption algorithm to be used for this key. Currently, only `m.secret_storage.v1.aes-hmac-sha2` is supported. |
|
|
|
| passphrase | string | See [deriving keys from passphrases](#deriving-keys-from-passphrases) section for a description of this property. |
|
|
|
|
|
|
Other properties depend on the encryption algorithm, and are described
|
|
|
below.
|
|
|
|
|
|
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.
|
|
|
|
|
|
Clients that want to present a simplified interface to users by not supporting
|
|
|
multiple keys should use the default key if one is specified. If not default
|
|
|
key is specified, the client may behave as if there is no key is present at
|
|
|
all. When such a client creates a key, it should mark that key as being the
|
|
|
default key.
|
|
|
|
|
|
`DefaultKey`
|
|
|
|
|
|
| Parameter | Type | Description
|
|
|
|------------|-----------|------------------------------------------|
|
|
|
| key | string | **Required.** The ID of the default key. |
|
|
|
|
|
|
|
|
|
###### `m.secret_storage.v1.aes-hmac-sha2`
|
|
|
|
|
|
For the purposes of allowing clients to check whether a user has correctly
|
|
|
entered the key, keys for use with the `m.secret_storage.v1.aes-hmac-sha2`
|
|
|
algorithm are stored with some additional data.
|
|
|
|
|
|
When storing a key, clients SHOULD:
|
|
|
|
|
|
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 the empty
|
|
|
string 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 (IV).
|
|
|
|
|
|
3. Encrypt a message consisting of 32 byutes of 0, using AES-CTR-256 using the
|
|
|
AES key and IV generated above.
|
|
|
|
|
|
4. Pass the raw encrypted data through HMAC-SHA-256 using the MAC key
|
|
|
generated above.
|
|
|
|
|
|
5. Encode the IV from step 2, and the MAC from step 4, using [unpadded
|
|
|
base64](/appendices/#unpadded-base64), and store the results in the `iv`
|
|
|
and `mac` properties respectively in the `m.secret_storage.key.[key ID]`
|
|
|
account-data. (The ciphertext from step 3 is discarded after passing
|
|
|
through the MAC calculation.)
|
|
|
|
|
|
This process can be repeated by a client checking if the key is correct: the
|
|
|
MAC should match if the key is correct. Note, however, that these properties
|
|
|
are **optional**. If they are not present, clients must assume that the key is
|
|
|
valid.
|
|
|
|
|
|
Note also, that although clients SHOULD use unpadded base64 as specified above,
|
|
|
some existing implementations use standard [RFC4648-compliant
|
|
|
base64](https://datatracker.ietf.org/doc/html/rfc4648#section-4) with padding,
|
|
|
so clients must accept either encoding.
|
|
|
|
|
|
The structure of a `m.secret_storage.key.[key ID]` account data object for use
|
|
|
with this algorithm is therefore as follows:
|
|
|
|
|
|
`AesHmacSha2KeyDescription`
|
|
|
|
|
|
| Parameter | Type | Description |
|
|
|
|-------------|--------|------------------------------------------------------------------------------------------------------|
|
|
|
| name | string | Optional. The name of the key. |
|
|
|
| algorithm | string | **Required.** The encryption algorithm to be used for this key: `m.secret_storage.v1.aes-hmac-sha2`. |
|
|
|
| passphrase | object | See [deriving keys from passphrases](#deriving-keys-from-passphrases) section for a description of this property. |
|
|
|
| iv | string | Optional. The 16-byte initialization vector for the validation check, encoded as base64. |
|
|
|
| mac | string | Optional. The MAC of the result of encrypting 32 bytes of 0, encoded as base64. |
|
|
|
|
|
|
For example, it could look like:
|
|
|
|
|
|
```json
|
|
|
{
|
|
|
"name": "m.default",
|
|
|
"algorithm": "m.secret_storage.v1.aes-hmac-sha2",
|
|
|
"iv": "random+data",
|
|
|
"mac": "mac+of+encrypted+zeros"
|
|
|
}
|
|
|
```
|
|
|
|
|
|
##### Secret storage
|
|
|
|
|
|
Encrypted data is stored in the user's account data using the event
|
|
|
type defined by the feature that uses the data. 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.
|
|
|
|
|
|
`Secret`
|
|
|
|
|
|
| Parameter | Type | Description |
|
|
|
|-----------|------------------|-------------|
|
|
|
| encrypted | {string: object} | **Required.** Map from key ID the encrypted data. The exact format for the encrypted data is dependent on the key algorithm. See the definition of `AesHmacSha2EncryptedData` in the [m.secret_storage.v1.aes-hmac-sha2](#msecret_storagev1aes-hmac-sha2-1) section. |
|
|
|
|
|
|
Example:
|
|
|
|
|
|
Some secret is encrypted using keys with ID `key_id_1` and `key_id_2`:
|
|
|
|
|
|
`org.example.some.secret`:
|
|
|
|
|
|
```
|
|
|
{
|
|
|
"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`:
|
|
|
|
|
|
```
|
|
|
{
|
|
|
"name": "Some key",
|
|
|
"algorithm": "m.secret_storage.v1.aes-hmac-sha2",
|
|
|
// ... other properties according to algorithm
|
|
|
}
|
|
|
```
|
|
|
|
|
|
`m.secret_storage.key.key_id_2`:
|
|
|
|
|
|
```
|
|
|
{
|
|
|
"name": "Some other key",
|
|
|
"algorithm": "m.secret_storage.v1.aes-hmac-sha2",
|
|
|
// ... other properties according to algorithm
|
|
|
}
|
|
|
```
|
|
|
|
|
|
If `key_id_1` is the default key, then we also have:
|
|
|
|
|
|
`m.secret_storage.default_key`:
|
|
|
|
|
|
```
|
|
|
{
|
|
|
"key": "key_id_1"
|
|
|
}
|
|
|
```
|
|
|
|
|
|
###### `m.secret_storage.v1.aes-hmac-sha2`
|
|
|
|
|
|
Secrets encrypted using the `m.secret_storage.v1.aes-hmac-sha2`
|
|
|
algorithm are encrypted using AES-CTR-256, and authenticated using
|
|
|
HMAC-SHA-256. The secret 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 (IV).
|
|
|
|
|
|
3. Encrypt the data using AES-CTR-256 using the AES key and IV generated
|
|
|
above.
|
|
|
|
|
|
4. Pass the raw encrypted data through HMAC-SHA-256 using the MAC key
|
|
|
generated above.
|
|
|
|
|
|
5. Encode the IV from step 2, the ciphertext from step 3, and MAC from step 4,
|
|
|
using [unpadded base64](/appendices/#unpadded-base64), and store them as
|
|
|
the `iv`, `ciphertext`, and `mac` properties respectively in the account
|
|
|
data object.
|
|
|
|
|
|
**Note**: some existing implementations encode these properties using
|
|
|
standard [RFC4648-compliant
|
|
|
base64](https://datatracker.ietf.org/doc/html/rfc4648#section-4) with
|
|
|
padding, so clients must accept either encoding.
|
|
|
|
|
|
The structure of the `encrypted` property of an account data object encrypted
|
|
|
with this algorithm is therefore as follows:
|
|
|
|
|
|
`AesHmacSha2EncryptedData`
|
|
|
|
|
|
| Parameter | Type | Description
|
|
|
|------------|---------|------------------------------------------------------------------------|
|
|
|
| iv | string | **Required.** The 16-byte initialization vector, encoded as base64. |
|
|
|
| ciphertext | string | **Required.** The AES-CTR-encrypted data, encoded as base64. |
|
|
|
| mac | string | **Required.** The MAC, encoded as base64. |
|
|
|
|
|
|
|
|
|
For example, 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"
|
|
|
}
|
|
|
}
|
|
|
}
|
|
|
```
|
|
|
|
|
|
##### Key representation
|
|
|
|
|
|
When a user is given a raw key for `m.secret_storage.v1.aes-hmac-sha2`,
|
|
|
it will be presented as a string constructed as follows:
|
|
|
|
|
|
1. The key is prepended by the two bytes `0x8b` and `0x01`
|
|
|
2. All the bytes in the string above, including the two header bytes,
|
|
|
are XORed together to form a parity byte. This parity byte is
|
|
|
appended to the byte string.
|
|
|
3. The byte string is encoded using base58, using the same [mapping as
|
|
|
is used for Bitcoin
|
|
|
addresses](https://en.bitcoin.it/wiki/Base58Check_encoding#Base58_symbol_chart),
|
|
|
that is, using the alphabet
|
|
|
`123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz`.
|
|
|
4. The string is formatted into groups of four 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 input.
|
|
|
|
|
|
##### Deriving keys from passphrases
|
|
|
|
|
|
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. The `passphrase` property
|
|
|
has an `algorithm` property that indicates how to generate the key from
|
|
|
the passphrase. Other properties of the `passphrase` property are
|
|
|
defined by the `algorithm` specified.
|
|
|
|
|
|
Currently, the only algorithm defined is `m.pbkdf2`. For the `m.pbkdf2` algorithm, the `passphrase` property has the
|
|
|
following properties:
|
|
|
|
|
|
| Parameter | Type | Description |
|
|
|
|------------|---------|------------------------------------------------------------------------|
|
|
|
| algorithm | string | **Required.** Must be `m.pbkdf2` |
|
|
|
| salt | string | **Required.** The salt used in PBKDF2. |
|
|
|
| iterations | integer | **Required.** The number of iterations to use in PBKDF2. |
|
|
|
| bits | integer | Optional. The number of bits to generate for the key. Defaults to 256. |
|
|
|
|
|
|
The key is generated using PBKDF2 with SHA-512 as the hash, using the
|
|
|
salt given in the `salt` parameter, and the number of iterations given
|
|
|
in the `iterations` parameter.
|
|
|
|
|
|
Example:
|
|
|
|
|
|
```
|
|
|
{
|
|
|
"passphrase": {
|
|
|
"algorithm": "m.pbkdf2",
|
|
|
"salt": "MmMsAlty",
|
|
|
"iterations": 100000,
|
|
|
"bits": 256
|
|
|
},
|
|
|
...
|
|
|
}
|
|
|
```
|
|
|
|
|
|
#### Sharing
|
|
|
|
|
|
To request a secret from other devices, a client sends an
|
|
|
`m.secret.request` device event with `action` set to `request` and
|
|
|
`name` set to the identifier of the secret. A device that wishes to
|
|
|
share the secret will reply with an `m.secret.send` event, encrypted
|
|
|
using olm. When the original client obtains the secret, it sends an
|
|
|
`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.
|
|
|
|
|
|
##### Event definitions
|
|
|
|
|
|
{{% event event="m.secret.request" %}}
|
|
|
|
|
|
{{% event event="m.secret.send" %}}
|