diff --git a/changelogs/client_server/newsfragments/2413.clarification b/changelogs/client_server/newsfragments/2413.clarification new file mode 100644 index 00000000..14d4138b --- /dev/null +++ b/changelogs/client_server/newsfragments/2413.clarification @@ -0,0 +1 @@ +Improve the format description of `m.room.encrypted` (Olm/Megolm) events. \ No newline at end of file diff --git a/content/client-server-api/modules/end_to_end_encryption.md b/content/client-server-api/modules/end_to_end_encryption.md index 242f1c7c..627caac8 100644 --- a/content/client-server-api/modules/end_to_end_encryption.md +++ b/content/client-server-api/modules/end_to_end_encryption.md @@ -1723,28 +1723,30 @@ Devices that support Olm must include "m.olm.v1.curve25519-aes-sha2" in their list of supported messaging algorithms, must list a Curve25519 device key, and must publish Curve25519 one-time keys. -An event encrypted using Olm has the following format: +The content of an [`m.room.encrypted`](#mroomencrypted) event using Olm has the following format: ```json { - "type": "m.room.encrypted", "content": { "algorithm": "m.olm.v1.curve25519-aes-sha2", "sender_key": "", "ciphertext": { "": { "type": 0, - "body": "" + "body": "" } } } } ``` - -`ciphertext` is a mapping from device Curve25519 key to an encrypted -payload for that device. `body` is a Base64-encoded [Olm message body](/olm-megolm/olm/#the-olm-message-format). -`type` is an integer indicating the type of the message body: 0 for the -initial [pre-key message](/olm-megolm/olm/#pre-key-messages), 1 for [normal messages](/olm-megolm/olm/#normal-messages). +Note that when the event is received from the server, it will have a `type` +(with a value of `m.room.encrypted`) and `sender` property alongside the +`content` property. In `content`, `ciphertext` is a mapping from a device +Curve25519 key to an object with a `type` and a `body`. Here, `body` is a +Base64-encoded [Olm message](/olm-megolm/olm/#the-olm-message-format), and +`type` is an integer indicating the type of the message: +0 for the initial [pre-key messages](/olm-megolm/olm/#pre-key-messages), +1 for [normal messages](/olm-megolm/olm/#normal-messages). Olm sessions will generate messages with a type of 0 until they receive a message. Once a session has decrypted a message it will produce @@ -1893,23 +1895,26 @@ This uses: Devices that support Megolm must support Olm, and include "m.megolm.v1.aes-sha2" in their list of supported messaging algorithms. -An event encrypted using Megolm has the following format: +The content of an [`m.room.encrypted`](#mroomencrypted) event using Megolm has the following format: ```json { - "type": "m.room.encrypted", "content": { "algorithm": "m.megolm.v1.aes-sha2", "sender_key": "", "device_id": "", "session_id": "", - "ciphertext": "" + "ciphertext": "" } } ``` +Note that when the event is received from the server, it will have additional +properties alongside the `content` property, including a `type` (with a value +of `m.room.encrypted`) and a `sender` property. (See [Room event format](#room-event-format).) -The encrypted payload can contain any message event. The plaintext is of -the form: +Within `content`, `ciphertext` +is a Base64-encoded [Megolm message](/olm-megolm/megolm/#message-format), +whose plaintext body is of the form: ```json { @@ -1919,7 +1924,7 @@ the form: } ``` -We include the room ID in the payload, because otherwise the homeserver +We include the room ID in the encrypted message, because otherwise the homeserver would be able to change the room a message was sent in. Clients must guard against replay attacks by keeping track of the diff --git a/content/client-server-api/modules/event_replacements.md b/content/client-server-api/modules/event_replacements.md index e42dacf8..d4dd5e9b 100644 --- a/content/client-server-api/modules/event_replacements.md +++ b/content/client-server-api/modules/event_replacements.md @@ -91,13 +91,13 @@ For example, a replacement for an encrypted event might look like this: "sender_key": "", "device_id": "", "session_id": "", - "ciphertext": "" + "ciphertext": "" } // irrelevant fields not shown } ``` -... and, once decrypted, the payload might look like this: +... and the plaintext body of the Megolm message might look like this: ```json {