Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[WIP] MSC3814: Dehydrated devices with SSSS #3814

Draft
wants to merge 25 commits into
base: main
Choose a base branch
from
Draft
Changes from 1 commit
Commits
Show all changes
25 commits
Select commit Hold shift + click to select a range
80243a4
Initial proposal for dehydrated devices with SSSS
uhoreg May 12, 2022
ed2c5eb
use MSC number
uhoreg May 12, 2022
703281e
wording improvements and clarifications
uhoreg Sep 5, 2022
0a149c5
Uploading a dehydrated device now uploads the public keys as well
poljar Aug 9, 2023
a4e87a6
Make the next_batch token non-optional in the response
poljar Aug 9, 2023
3827bc0
Let's not delete to-device events when a client receives them
poljar Aug 9, 2023
12acd43
Introduce the DELETE endpoint
poljar Aug 9, 2023
f756db3
Attempt to define the dehydration format
poljar Aug 10, 2023
6223db4
Don't use operatorname, try to unwedge the Latex
poljar Aug 10, 2023
e3c9ac8
More Latex tweaks
poljar Aug 10, 2023
7f24f0d
Remove the bytes unit from every single row, put it in the header
poljar Sep 5, 2023
f85c18d
Attempt to fix the math rendering
poljar Sep 5, 2023
4954c27
Align the table headers for the pickle format
poljar Sep 5, 2023
087154a
Fix JSON example
uhoreg Feb 8, 2024
e7c8266
link to fallback key spec
uhoreg Feb 12, 2024
cf5ae99
add dehydrated flag
uhoreg Feb 23, 2024
d751d33
Apply suggestions from code review
uhoreg Nov 19, 2024
11149e4
define new format and add more security notes
uhoreg Nov 22, 2024
1500897
suggest dropping to-device messages sent from a dehydrated device
uhoreg Dec 16, 2024
5742c52
link to the base64 format that we use
uhoreg Dec 16, 2024
a58288a
we need the ed25519 key after all
uhoreg Dec 16, 2024
21a3d67
add note about URL-safe base64
uhoreg Dec 16, 2024
6be9078
update dehydration format
uhoreg Dec 28, 2024
ec17903
fix typo
uhoreg Jan 10, 2025
9d6d059
fix typo
uhoreg Jan 15, 2025
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
Attempt to fix the math rendering
  • Loading branch information
poljar committed Sep 5, 2023
commit f85c18db89e454d539958e152c6202f36d5736fd
29 changes: 6 additions & 23 deletions proposals/3814-dehydrated-devices-with-ssss.md
Original file line number Diff line number Diff line change
Expand Up @@ -244,48 +244,30 @@ public key from the private one.

#### Encryption key

TODO: Decide if the Latex format or the pseudocode format is preferred, or maybe
both.

TODO: Explain why the double derivation is necessary.

The encryption key used for the dehydrated device will be randomly generated
and stored/shared via SSSS using the name `m.dehydrated_device`.
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

if I'm reading the iOS implementation correctly, the key is encoded with unpadded base64 (as is done with the other keys in secret storage)


The randomly generated encryption key *must* be expanded using the HMAC-based
Key Derivation function defined in [RFC5869]. The notation in this document are
to be interpreted as described in [RFC5869].
Key Derivation function defined in [RFC5869].

$$
```math
\begin{aligned}
DEVICE\_KEY
&= \text{HKDF} \left(\text{``Device ID``}, RANDOM\_KEY, \text{``dehydrated-device-pickle-key"}, 32\right)
uhoreg marked this conversation as resolved.
Show resolved Hide resolved
\end{aligned}
$$

```text
PRK = HKDF-Extract("Device ID", random_encryption_key)
device_key = HKDF-Expand(PRK, "dehydrated-device-pickle-key", 32)
```

The `device_key` is then further expanded into a AES256 key, HMAC key and
initialization vector.


$$
```math
\begin{aligned}
AES\_KEY \parallel HMAC\_KEY \parallel AES\_IV
&= \text{HKDF}\left(0,DEVICE\_KEY,\text{``Pickle"},80\right)
uhoreg marked this conversation as resolved.
Show resolved Hide resolved
\end{aligned}
$$

```text
PRK = HKDF-Extract("", DeviceKey)
output = HKDF-Expand(PRK, "Pickle", 80)

aes_key = output[0..32]
mac_key = output[32..64]
initialization_vector = output[64..80]
```

The plain-text is encrypted with [AES-256] in [CBC] mode with [PKCS#7] padding,
Expand All @@ -297,12 +279,12 @@ MAC are appended to the cipher-text.
The cipher-text, including the appended MAC tag, are encoded using unpadded
Base64 to give the device pickle.
uhoreg marked this conversation as resolved.
Show resolved Hide resolved

The device pickle can be inserted into the `device_pickle` field of the
The device pickle is then inserted into the `device_pickle` field of the
`device_data` JSON message.

```json
{
"device_data": {
"device_data": {
"algorithm": "m.dehydration.v1.olm",
"device_pickle": "encrypted dehydrated device"
}
Expand Down Expand Up @@ -407,3 +389,4 @@ None
[MSC2697]: https://github.com/matrix-org/matrix-doc/pull/2697
[`/keys/upload`]: https://spec.matrix.org/v1.7/client-server-api/#post_matrixclientv3keysupload
[device keys]: https://spec.matrix.org/v1.7/client-server-api/#device-keys
[HMAC-SHA-256]: https://datatracker.ietf.org/doc/html/rfc2104