From ab3272045e43679d42e05120ea251db7c7dda62c Mon Sep 17 00:00:00 2001 From: Valentin Deniaud Date: Tue, 5 Jun 2018 15:12:25 +0200 Subject: [PATCH 01/27] add missing v1 to m.olm in /keys/upload --- api/client-server/keys.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api/client-server/keys.yaml b/api/client-server/keys.yaml index 6e995c2c..457311cf 100644 --- a/api/client-server/keys.yaml +++ b/api/client-server/keys.yaml @@ -194,7 +194,7 @@ paths: "user_id": "@alice:example.com", "device_id": "JLAFKJWSCS", "algorithms": [ - "m.olm.curve25519-aes-sha256", + "m.olm.v1.curve25519-aes-sha256", "m.megolm.v1.aes-sha" ], "keys": { From e210f8b05005f17dfe957d9bae01a2c0dd1e84cf Mon Sep 17 00:00:00 2001 From: Valentin Deniaud Date: Wed, 6 Jun 2018 16:08:00 +0200 Subject: [PATCH 02/27] add e2e messaging algorithms section intro This was written by Richard van der Hoff. --- .../modules/end_to_end_encryption.rst | 22 +++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/specification/modules/end_to_end_encryption.rst b/specification/modules/end_to_end_encryption.rst index 1f778bc2..08138270 100644 --- a/specification/modules/end_to_end_encryption.rst +++ b/specification/modules/end_to_end_encryption.rst @@ -228,6 +228,28 @@ A homeserver should rate-limit the number of one-time keys that a given user or remote server can claim. A homeserver should discard the public part of a one time key once it has given that key to another user. +Messaging Algorithms +-------------------- + +Messaging Algorithm Names +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Messaging algorithm names use the extensible naming scheme used throughout this +specification. Algorithm names that start with ``m.`` are reserved for +algorithms defined by this specification. Implementations wanting to experiment +with new algorithms are encouraged to pick algorithm names that start with +their domain to reduce the risk of collisions. + +Algorithm names should be short and meaningful, and should list the primitives +used by the algorithm so that it is easier to see if the algorithm is using a +broken primitive. + +A name of ``m.olm.v1`` is too short: it gives no information about the primitives +in use, and is difficult to extend for different primitives. However a name of +``m.olm.v1.ecdh-curve25519-hdkfsha256.hmacsha256.hkdfsha256-aes256-cbc-hmac64sha256`` +is too long despite giving a more precise description of the algorithm: it adds +to the data transfer overhead and sacrifices clarity for human readers without +adding any useful extra information. Protocol definitions -------------------- From 33802dbbafd0be45ad5abb1e4eb5285fd57a1a04 Mon Sep 17 00:00:00 2001 From: Valentin Deniaud Date: Wed, 6 Jun 2018 16:10:36 +0200 Subject: [PATCH 03/27] add olm messaging algorithm subsection This was written by Richard van der Hoff. --- .../modules/end_to_end_encryption.rst | 71 +++++++++++++++++++ 1 file changed, 71 insertions(+) diff --git a/specification/modules/end_to_end_encryption.rst b/specification/modules/end_to_end_encryption.rst index 08138270..1a58ee31 100644 --- a/specification/modules/end_to_end_encryption.rst +++ b/specification/modules/end_to_end_encryption.rst @@ -251,6 +251,76 @@ is too long despite giving a more precise description of the algorithm: it adds to the data transfer overhead and sacrifices clarity for human readers without adding any useful extra information. +``m.olm.v1.curve25519-aes-sha2`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The name ``m.olm.v1.curve25519-aes-sha2`` corresponds to version 1 of the Olm +ratchet, as defined by the `Olm specification`_. This uses: + +* Curve25519 for the initial key agreement. +* HKDF-SHA-256 for ratchet key derivation. +* Curve25519 for the root key ratchet. +* HMAC-SHA-256 for the chain key ratchet. +* HKDF-SHA-256, AES-256 in CBC mode, and 8 byte truncated HMAC-SHA-256 for authenticated encryption. + +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: + +.. code:: json + + { + "type": "m.room.encrypted", + "content": { + "algorithm": "m.olm.v1.curve25519-aes-sha2", + "sender_key": "", + "ciphertext": { + "": { + "type": 0, + "body": "" + } } } } + +``ciphertext`` is a mapping from device Curve25519 key to an encrypted payload +for that device. ``body`` is a Base64-encoded Olm message body. ``type`` is an +integer indicating the type of the message body: 0 for the initial pre-key +message, 1 for ordinary 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 messages with +a type of 1. + +When a client receives a message with a type of 0 it must first check if it +already has a matching session. If it does then it will use that session to +try to decrypt the message. If there is no existing session then the client +must create a new session and use the new session to decrypt the message. A +client must not persist a session or remove one-time keys used by a session +until it has successfully decrypted a message using that session. + +Messages with type 1 can only be decrypted with an existing session. If there +is no matching session, the client should show this as an invalid message. + +The plaintext payload is of the form: + +.. code:: json + + { + "type": "", + "content": "", + "room_id": "", + } + +The type and content of the plaintext message event are given in the payload. + +We include the room ID in the payload, because otherwise the homeserver would +be able to change the room a message was sent in. + +.. TODO: claimed_keys + +Clients must confirm that the ``sender_key`` belongs to the user that sent the +message. TODO: how? + Protocol definitions -------------------- @@ -310,6 +380,7 @@ Example response: .. _ed25519: http://ed25519.cr.yp.to/ .. _curve25519: https://cr.yp.to/ecdh.html +.. _`Olm specification`: http://matrix.org/docs/spec/olm.html .. _`Signing JSON`: ../appendices.html#signing-json From 07e3de3c61cbb5b379477de5856829a449e33ff1 Mon Sep 17 00:00:00 2001 From: Valentin Deniaud Date: Wed, 6 Jun 2018 16:12:31 +0200 Subject: [PATCH 04/27] add megolm messaging algorithm subsection This was written by Richard van der Hoff. --- specification/modules/end_to_end_encryption.rst | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/specification/modules/end_to_end_encryption.rst b/specification/modules/end_to_end_encryption.rst index 1a58ee31..e2cb54e5 100644 --- a/specification/modules/end_to_end_encryption.rst +++ b/specification/modules/end_to_end_encryption.rst @@ -321,6 +321,17 @@ be able to change the room a message was sent in. Clients must confirm that the ``sender_key`` belongs to the user that sent the message. TODO: how? +``m.megolm.v1.aes-sha2`` +~~~~~~~~~~~~~~~~~~~~~~~~ + +The name ``m.megolm.v1.aes-sha2`` corresponds to version 1 of the Megolm +ratchet, as defined by the `Megolm specification`_. This uses: + +* HMAC-SHA-256 for the hash ratchet. +* HKDF-SHA-256, AES-256 in CBC mode, and 8 byte truncated HMAC-SHA-256 for authenticated encryption. +* Ed25519 for message authenticity. + + Protocol definitions -------------------- @@ -381,6 +392,7 @@ Example response: .. _ed25519: http://ed25519.cr.yp.to/ .. _curve25519: https://cr.yp.to/ecdh.html .. _`Olm specification`: http://matrix.org/docs/spec/olm.html +.. _`Megolm specification`: http://matrix.org/docs/spec/megolm.html .. _`Signing JSON`: ../appendices.html#signing-json From 2686b990806e59cce7cad07fcc4d03ea7eba13d5 Mon Sep 17 00:00:00 2001 From: Valentin Deniaud Date: Wed, 6 Jun 2018 16:23:32 +0200 Subject: [PATCH 05/27] fix json indent --- specification/modules/end_to_end_encryption.rst | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/specification/modules/end_to_end_encryption.rst b/specification/modules/end_to_end_encryption.rst index e2cb54e5..68e030e1 100644 --- a/specification/modules/end_to_end_encryption.rst +++ b/specification/modules/end_to_end_encryption.rst @@ -274,13 +274,16 @@ An event encrypted using Olm has the following format: { "type": "m.room.encrypted", "content": { - "algorithm": "m.olm.v1.curve25519-aes-sha2", + "algorithm": "m.olm.v1.curve25519-aes-sha2", "sender_key": "", "ciphertext": { "": { "type": 0, "body": "" - } } } } + } + } + } + } ``ciphertext`` is a mapping from device Curve25519 key to an encrypted payload for that device. ``body`` is a Base64-encoded Olm message body. ``type`` is an From 8afc82c14b70d23f7133470ed9304b2031e3a55b Mon Sep 17 00:00:00 2001 From: Valentin Deniaud Date: Mon, 11 Jun 2018 11:48:20 +0200 Subject: [PATCH 06/27] fix /keys/claim request example It didn't correspond to the example response. --- api/client-server/keys.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api/client-server/keys.yaml b/api/client-server/keys.yaml index 457311cf..55f8a5a5 100644 --- a/api/client-server/keys.yaml +++ b/api/client-server/keys.yaml @@ -247,7 +247,7 @@ paths: description: algorithm example: "signed_curve25519" example: - "@alice:example.com": { "JLAFKJWSCS": "curve25519" } + "@alice:example.com": { "JLAFKJWSCS": "signed_curve25519" } required: - one_time_keys responses: From 10c3307427808da03aed24165b17c4911486b3b0 Mon Sep 17 00:00:00 2001 From: Valentin Deniaud Date: Mon, 11 Jun 2018 15:18:59 +0200 Subject: [PATCH 07/27] document device_one_time_keys_count in /sync/ response fix #1157 --- api/client-server/sync.yaml | 8 ++++++++ specification/modules/end_to_end_encryption.rst | 11 +++++++++++ 2 files changed, 19 insertions(+) diff --git a/api/client-server/sync.yaml b/api/client-server/sync.yaml index 34659dd0..4b44c20e 100644 --- a/api/client-server/sync.yaml +++ b/api/client-server/sync.yaml @@ -253,6 +253,14 @@ paths: description: |- Information on end-to-end device updates, as specified in |device_lists_sync|_. + device_one_time_keys_count: + title: One-time keys count + type: object + additionalProperties: + type: integer + description: |- + Information on end-to-end encryption keys, as specified + in |device_lists_sync|_. examples: application/json: { "next_batch": "s72595_4483_1934", diff --git a/specification/modules/end_to_end_encryption.rst b/specification/modules/end_to_end_encryption.rst index 68e030e1..b030ab64 100644 --- a/specification/modules/end_to_end_encryption.rst +++ b/specification/modules/end_to_end_encryption.rst @@ -355,6 +355,9 @@ specified). The client is expected to use |/keys/query|_ or |/keys/changes|_ for the equivalent functionality after an initial sync, as documented in `Tracking the device list for a user`_. +It also adds a ``one_time_keys_count`` property. Note the spelling difference +with the ``one_time_key_counts`` property in the |/keys/upload|_ response. + .. todo: generate this from a swagger definition? .. device_lists: { changed: ["@user:server", ... ]}, @@ -364,6 +367,9 @@ Parameter Type Description ============ =========== ===================================================== device_lists DeviceLists Optional. Information on e2e device updates. Note: only present on an incremental sync. +|device_otk| {string: Optional. For each key algorithm, the number of + integer} unclaimed one-time keys currently held on the server + for this device. ============ =========== ===================================================== ``DeviceLists`` @@ -388,6 +394,10 @@ Example response: "@alice:example.com", ], }, + "device_one_time_keys_count": { + "curve25519": 10, + "signed_curve25519": 20 + } } .. References @@ -400,6 +410,7 @@ Example response: .. _`Signing JSON`: ../appendices.html#signing-json .. |m.olm.v1.curve25519-aes-sha2| replace:: ``m.olm.v1.curve25519-aes-sha2`` +.. |device_otk| replace:: device_one_time_keys_count .. |/keys/upload| replace:: ``/keys/upload`` .. _/keys/upload: #post-matrix-client-%CLIENT_MAJOR_VERSION%-keys-upload From a28f243ed7fe9b4677fc5d970ff4ae494bdc2ba8 Mon Sep 17 00:00:00 2001 From: Valentin Deniaud Date: Mon, 11 Jun 2018 15:44:17 +0200 Subject: [PATCH 08/27] document left parameter of device_lists in sync response fix #1171 --- specification/modules/end_to_end_encryption.rst | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/specification/modules/end_to_end_encryption.rst b/specification/modules/end_to_end_encryption.rst index b030ab64..3bcfbd2d 100644 --- a/specification/modules/end_to_end_encryption.rst +++ b/specification/modules/end_to_end_encryption.rst @@ -379,6 +379,8 @@ Parameter Type Description ========= ========= ============================================= changed [string] List of users who have updated their device identity keys since the previous sync response. +left [string] List of users with whom we do not share any encrypted rooms + anymore since the previous sync response. ========= ========= ============================================= @@ -393,6 +395,9 @@ Example response: "changed": [ "@alice:example.com", ], + "left": [ + "@bob:example.com", + ], }, "device_one_time_keys_count": { "curve25519": 10, From 8274f91b0b121205584bbf53878720ea9b365cc3 Mon Sep 17 00:00:00 2001 From: Valentin Deniaud Date: Tue, 17 Jul 2018 17:35:38 +0200 Subject: [PATCH 09/27] document device verification This was written by Richard van der Hoff. --- .../modules/end_to_end_encryption.rst | 48 +++++++++++++++++++ 1 file changed, 48 insertions(+) diff --git a/specification/modules/end_to_end_encryption.rst b/specification/modules/end_to_end_encryption.rst index 3bcfbd2d..dbd6cb43 100644 --- a/specification/modules/end_to_end_encryption.rst +++ b/specification/modules/end_to_end_encryption.rst @@ -228,6 +228,54 @@ A homeserver should rate-limit the number of one-time keys that a given user or remote server can claim. A homeserver should discard the public part of a one time key once it has given that key to another user. +Device verification +------------------- + +Before Alice sends Bob encrypted data, or trusts data received from him, she +may want to verify that she is actually communicating with him, rather than a +man-in-the-middle. This verification process requires an out-of-band channel: +there is no way to do it within Matrix without trusting the administrators of +the homeservers. + +In Matrix, the basic process for device verification is for Alice to verify +that the public Ed25519 signing key she received via ``/keys/query`` for Bob's +device corresponds to the private key in use by Bob's device. For now, it is +recommended that clients provide mechanisms by which the user can see: + +1. The public part of their device's Ed25519 signing key, encoded using + `unpadded Base64`_. + +2. The list of devices in use for each user in a room, along with the public + Ed25519 signing key for each device, again encoded using unpadded Base64. + +Alice can then meet Bob in person, or contact him via some other trusted +medium, and ask him to read out the Ed25519 key shown on his device. She +compares this with the value shown for his device on her client. + +Device verification may reach one of several conclusions. For example: + +* Alice may "accept" the device. This means that she is satisfied that the + device belongs to Bob. She can then encrypt sensitive material for that + device, and knows that messages received were sent from that device. + +* Alice may "reject" the device. She will do this if she knows or suspects + that Bob does not control that device (or equivalently, does not trust + Bob). She will not send sensitive material to that device, and cannot trust + messages apparently received from it. + +* Alice may choose to skip the device verification process. She is not able + to verify that the device actually belongs to Bob, but has no reason to + suspect otherwise. The encryption protocol continues to protect against + passive eavesdroppers. + +.. NOTE:: + + Once the signing key has been verified, it is then up to the encryption + protocol to verify that a given message was sent from a device holding that + Ed25519 private key, or to encrypt a message so that it may only be + decrypted by such a device. For the Olm protocol, this is documented at + https://matrix.org/git/olm/about/docs/signing.rst. + Messaging Algorithms -------------------- From 76071bae988ff3f3dea5c7b6e7b6210f84ebe3c1 Mon Sep 17 00:00:00 2001 From: Valentin Deniaud Date: Tue, 17 Jul 2018 17:55:54 +0200 Subject: [PATCH 10/27] explain how to verify sender_key ownership --- specification/modules/end_to_end_encryption.rst | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) diff --git a/specification/modules/end_to_end_encryption.rst b/specification/modules/end_to_end_encryption.rst index dbd6cb43..078b3f99 100644 --- a/specification/modules/end_to_end_encryption.rst +++ b/specification/modules/end_to_end_encryption.rst @@ -360,6 +360,9 @@ The plaintext payload is of the form: "type": "", "content": "", "room_id": "", + "keys": { + "ed25519": "" + } } The type and content of the plaintext message event are given in the payload. @@ -367,10 +370,12 @@ The type and content of the plaintext message event are given in the payload. We include the room ID in the payload, because otherwise the homeserver would be able to change the room a message was sent in. -.. TODO: claimed_keys - -Clients must confirm that the ``sender_key`` belongs to the user that sent the -message. TODO: how? +Clients must confirm that the ``sender_key`` and the ``ed25519`` field value +under the ``keys`` property match the keys returned by |/keys/query|_ for +the given user, and must also verify the signature of the payload. Without +this check, a client cannot be sure that the sender device owns the private +part of the ed25519 key it claims to have in the Olm payload. +This is crucial when the ed25519 key corresponds to a verified device. ``m.megolm.v1.aes-sha2`` ~~~~~~~~~~~~~~~~~~~~~~~~ From 669605b24a2e09066ffaafc82ecb701737cfe508 Mon Sep 17 00:00:00 2001 From: Valentin Deniaud Date: Tue, 17 Jul 2018 19:53:05 +0200 Subject: [PATCH 11/27] add Olm missing properties --- specification/modules/end_to_end_encryption.rst | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/specification/modules/end_to_end_encryption.rst b/specification/modules/end_to_end_encryption.rst index 078b3f99..50a14f72 100644 --- a/specification/modules/end_to_end_encryption.rst +++ b/specification/modules/end_to_end_encryption.rst @@ -360,6 +360,11 @@ The plaintext payload is of the form: "type": "", "content": "", "room_id": "", + "sender": "", + "recipient": "", + "recipient_keys": { + "ed25519": "" + }, "keys": { "ed25519": "" } @@ -370,6 +375,12 @@ The type and content of the plaintext message event are given in the payload. We include the room ID in the payload, because otherwise the homeserver would be able to change the room a message was sent in. +Other properties are included in order to prevent an attacker from publishing +someone else's curve25519 keys as their own and subsequently claiming to have +sent messages which they didn't. +``sender`` must correspond to the user who sent the event, ``recipient`` to +the local user, and ``recipient_keys`` to the local ed25519 key. + Clients must confirm that the ``sender_key`` and the ``ed25519`` field value under the ``keys`` property match the keys returned by |/keys/query|_ for the given user, and must also verify the signature of the payload. Without From 68b78dc5d8dd11233a8230dd1d34c5f4cd26b17f Mon Sep 17 00:00:00 2001 From: Valentin Deniaud Date: Tue, 17 Jul 2018 20:56:37 +0200 Subject: [PATCH 12/27] complete Megolm documentation --- .../modules/end_to_end_encryption.rst | 49 ++++++++++++++++++- 1 file changed, 48 insertions(+), 1 deletion(-) diff --git a/specification/modules/end_to_end_encryption.rst b/specification/modules/end_to_end_encryption.rst index 50a14f72..5ea84a3f 100644 --- a/specification/modules/end_to_end_encryption.rst +++ b/specification/modules/end_to_end_encryption.rst @@ -327,7 +327,7 @@ An event encrypted using Olm has the following format: "ciphertext": { "": { "type": 0, - "body": "" + "body": "" } } } @@ -398,6 +398,53 @@ ratchet, as defined by the `Megolm specification`_. This uses: * HKDF-SHA-256, AES-256 in CBC mode, and 8 byte truncated HMAC-SHA-256 for authenticated encryption. * Ed25519 for message authenticity. +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: + +.. code:: json + + { + "type": "m.room.encrypted", + "content": { + "algorithm": "m.megolm.v1.aes-sha2", + "sender_key": "", + "device_id": "", + "session_id": "", + "ciphertext": "" + } + } + +The encrypted payload can contain any message event. The plaintext is of the form: + +.. code:: json + + { + "type": "", + "content": "", + "room_id": "" + } + +Clients must guard against replay attacks by keeping track of the ratchet indices +of Megolm sessions. They should reject messages with a ratchet index that they +have already decrypted. Care should be taken in order to avoid false positives, as a +client may decrypt the same event twice as part of its normal processing. + +As with Olm events, clients must confirm that the ``sender_key`` belongs to the user +who sent the message. The same reasoning applies, but the sender ed25519 key has to be +inferred from the ``keys.ed25519`` property of the event which established the Megolm +session. + +In order to enable end-to-end encryption in a room, clients can send a +``m.room.encryption`` state event specifying ``m.megolm.v1.aes-sha2`` as its +``algorithm`` property. + +When creating a Megolm session in a room, clients must share the corresponding session +key using Olm with the intended recipients, so that they can decrypt future messages +encrypted using this session. A ``m.room_key`` event is used to do this. Clients +must also handle ``m.room_key`` events sent by other devices in order to decrypt their +messages. Protocol definitions -------------------- From e5005b2d0f6ee756dab5e80df448ce6de9afcc6a Mon Sep 17 00:00:00 2001 From: Valentin Deniaud Date: Tue, 17 Jul 2018 20:58:18 +0200 Subject: [PATCH 13/27] document E2E events This was written by Richard van der Hoff. --- event-schemas/examples/m.room.encrypted | 17 ++++++++++ event-schemas/examples/m.room.encryption | 10 ++++++ event-schemas/examples/m.room_key | 9 +++++ event-schemas/schema/m.room.encrypted | 34 +++++++++++++++++++ event-schemas/schema/m.room.encryption | 24 +++++++++++++ event-schemas/schema/m.room_key | 24 +++++++++++++ .../modules/end_to_end_encryption.rst | 12 +++++++ 7 files changed, 130 insertions(+) create mode 100644 event-schemas/examples/m.room.encrypted create mode 100644 event-schemas/examples/m.room.encryption create mode 100644 event-schemas/examples/m.room_key create mode 100644 event-schemas/schema/m.room.encrypted create mode 100644 event-schemas/schema/m.room.encryption create mode 100644 event-schemas/schema/m.room_key diff --git a/event-schemas/examples/m.room.encrypted b/event-schemas/examples/m.room.encrypted new file mode 100644 index 00000000..a0360963 --- /dev/null +++ b/event-schemas/examples/m.room.encrypted @@ -0,0 +1,17 @@ +{ + "content": { + "algorithm": "m.megolm.v1.aes-sha2", + "ciphertext": "AwgAEnACgAkLmt6qF84IK++J7UDH2Za1YVchHyprqTqsg2yyOwAtHaZTwyNg37afzg8f3r9IsN9rH4RNFg7MaZencUJe4qvELiDiopUjy5wYVDAtqdBzer5bWRD9ldxp1FLgbQvBcjkkywYjCsmsq6+hArILd9oAQZnGKn/qLsK+5uNX3PaWzDRC9wZPQvWYYPCTov3jCwXKTPsLKIiTrcCXDqMvnn8m+T3zF1/I2zqxg158tnUwWWIw51UO", + "device_id": "RJYKSTBOIE", + "sender_key": "IlRMeOPX2e0MurIyfWEucYBRVOEEUMrOHqn/8mLqMjA", + "session_id": "X3lUlvLELLYxeTx4yOVu6UDpasGEVO0Jbu+QFnm0cKQ" + }, + "event_id": "$WLGTSEFSEF:localhost", + "origin_server_ts": 1476648761524, + "sender": "@example:localhost", + "type": "m.room.encrypted", + "unsigned": { + "age": 158, + "transaction_id": "m1476648745605.19" + } +} diff --git a/event-schemas/examples/m.room.encryption b/event-schemas/examples/m.room.encryption new file mode 100644 index 00000000..25b1271f --- /dev/null +++ b/event-schemas/examples/m.room.encryption @@ -0,0 +1,10 @@ +{ + "content": { + "algorithm": "m.megolm.v1.aes-sha2" + }, + "event_id": "$WLGTSEFJJKJ:localhost", + "origin_server_ts": 1476648761524, + "sender": "@example:localhost", + "state_key": "", + "type": "m.room.encryption" +} diff --git a/event-schemas/examples/m.room_key b/event-schemas/examples/m.room_key new file mode 100644 index 00000000..2348e47d --- /dev/null +++ b/event-schemas/examples/m.room_key @@ -0,0 +1,9 @@ +{ + "content": { + "algorithm": "m.megolm.v1.aes-sha2", + "room_id": "!UCnwUWwIKhcpaPTHtR:sw1v.org", + "session_id": "X3lUlvLELLYxeTx4yOVu6UDpasGEVO0Jbu+QFnm0cKQ", + "session_key": "AgAAAADxKHa9uFxcXzwYoNueL5Xqi69IkD4sni8LlfJL7qNBEYbf8q5V1G7D/0GHj81JbEFsaE8JOHXJCyIqUGU9svVEi52SAGiC4lpID43TAeGfYc64rUsBx5ovhZl8WrdszLxld29I+7H9e8GZt/NVd/ZQEBBfOv3vrgoODT3WpJiWZ7VEIjL6gspKkkRTDcmwYU6Eff+A11iJ2tEC9njtCeNfTrK7XUIPoXkHWmEjPwqdSQi9pqVb1OYRKT7un7WFJzo0WEw8xjo6wyEolSikaBr3/o8FhoIMIA9KvbjR4y1WDg" + }, + "type": "m.room_key" +} diff --git a/event-schemas/schema/m.room.encrypted b/event-schemas/schema/m.room.encrypted new file mode 100644 index 00000000..cf3e4b4a --- /dev/null +++ b/event-schemas/schema/m.room.encrypted @@ -0,0 +1,34 @@ +--- +allOf: + # this is a bit of a lie; if the event is sent as a to-device event it won't + # have the room event fields. We really ought to use different event types :/ + - $ref: core-event-schema/room_event.yaml + +description: |- + This event type is used when sending encrypted events. It can be used either + within a room (in which case it will have all of the `Room Event fields`_), or + as a `to-device`_ event. + +properties: + content: + properties: + algorithm: + type: string + description: |- + The encryption algorithm used to encrypt this event. The + value of this field determines which other properties will be + present. + ciphertext: + type: + - object + - string + description: |- + Normally required. The encrypted content of the event. + required: + - algorithm + type: object + type: + enum: + - m.room.encrypted + type: string +type: object diff --git a/event-schemas/schema/m.room.encryption b/event-schemas/schema/m.room.encryption new file mode 100644 index 00000000..14778efa --- /dev/null +++ b/event-schemas/schema/m.room.encryption @@ -0,0 +1,24 @@ +--- +allOf: + - $ref: core-event-schema/state_event.yaml +description: Defines how messages sent in this room should be encrypted. +properties: + content: + properties: + algorithm: + type: string + description: |- + The encryption algorithm to be used to encrypt messages sent in this + room. For example, ``m.megolm.v1.aes-sha2``. + required: + - algorithm + type: object + state_key: + description: A zero-length string. + pattern: '^$' + type: string + type: + enum: + - m.room.encryption + type: string +type: object diff --git a/event-schemas/schema/m.room_key b/event-schemas/schema/m.room_key new file mode 100644 index 00000000..f5e4ac29 --- /dev/null +++ b/event-schemas/schema/m.room_key @@ -0,0 +1,24 @@ +--- +allOf: + - $ref: core-event-schema/event.yaml + +description: |- + This event type is used to exchange keys for end-to-end encryption. Typically + it is encrypted as an ``m.room.encrypted`` event. +properties: + content: + properties: + algorithm: + type: string + description: |- + The encryption algorithm the keys in this event are to be used + with. The value of this field determines which other properties will + be present. + required: + - algorithm + type: object + type: + enum: + - m.room_key + type: string +type: object diff --git a/specification/modules/end_to_end_encryption.rst b/specification/modules/end_to_end_encryption.rst index 5ea84a3f..c43f81c4 100644 --- a/specification/modules/end_to_end_encryption.rst +++ b/specification/modules/end_to_end_encryption.rst @@ -449,6 +449,18 @@ messages. Protocol definitions -------------------- +Events +~~~~~~ + +{{m_room_encryption_event}} + +{{m_room_encrypted_event}} + +{{m_room_key_event}} + +Key management API +~~~~~~~~~~~~~~~~~~ + {{keys_cs_http_api}} From 3a8d13df602bb97f1c2a580c33eda487c02f0540 Mon Sep 17 00:00:00 2001 From: Valentin Deniaud Date: Tue, 17 Jul 2018 21:25:41 +0200 Subject: [PATCH 14/27] add missing m.room.encryption properties --- event-schemas/examples/m.room.encryption | 4 +++- event-schemas/schema/m.room.encryption | 10 ++++++++++ 2 files changed, 13 insertions(+), 1 deletion(-) diff --git a/event-schemas/examples/m.room.encryption b/event-schemas/examples/m.room.encryption index 25b1271f..4c6342bb 100644 --- a/event-schemas/examples/m.room.encryption +++ b/event-schemas/examples/m.room.encryption @@ -1,6 +1,8 @@ { "content": { - "algorithm": "m.megolm.v1.aes-sha2" + "algorithm": "m.megolm.v1.aes-sha2", + "rotation_period_ms": 604800000, + "rotation_period_msgs": 100 }, "event_id": "$WLGTSEFJJKJ:localhost", "origin_server_ts": 1476648761524, diff --git a/event-schemas/schema/m.room.encryption b/event-schemas/schema/m.room.encryption index 14778efa..b990a13b 100644 --- a/event-schemas/schema/m.room.encryption +++ b/event-schemas/schema/m.room.encryption @@ -10,6 +10,16 @@ properties: description: |- The encryption algorithm to be used to encrypt messages sent in this room. For example, ``m.megolm.v1.aes-sha2``. + rotation_period_ms: + type: integer + description: |- + How long the session should be used before changing it. ``604800000`` + (a week) is the recommended default. + rotation_period_msgs: + type: integer + description: |- + How many messages should be sent before changing the session. ``100`` is the + recommended default. required: - algorithm type: object From c60109d235a1bba80f4ee003274484e3cbc8d781 Mon Sep 17 00:00:00 2001 From: Valentin Deniaud Date: Tue, 31 Jul 2018 18:59:09 +0200 Subject: [PATCH 15/27] complete m.room_key documentation --- event-schemas/examples/m.room_key | 2 +- event-schemas/schema/m.room_key | 19 +++++++++++++++---- 2 files changed, 16 insertions(+), 5 deletions(-) diff --git a/event-schemas/examples/m.room_key b/event-schemas/examples/m.room_key index 2348e47d..51249199 100644 --- a/event-schemas/examples/m.room_key +++ b/event-schemas/examples/m.room_key @@ -3,7 +3,7 @@ "algorithm": "m.megolm.v1.aes-sha2", "room_id": "!UCnwUWwIKhcpaPTHtR:sw1v.org", "session_id": "X3lUlvLELLYxeTx4yOVu6UDpasGEVO0Jbu+QFnm0cKQ", - "session_key": "AgAAAADxKHa9uFxcXzwYoNueL5Xqi69IkD4sni8LlfJL7qNBEYbf8q5V1G7D/0GHj81JbEFsaE8JOHXJCyIqUGU9svVEi52SAGiC4lpID43TAeGfYc64rUsBx5ovhZl8WrdszLxld29I+7H9e8GZt/NVd/ZQEBBfOv3vrgoODT3WpJiWZ7VEIjL6gspKkkRTDcmwYU6Eff+A11iJ2tEC9njtCeNfTrK7XUIPoXkHWmEjPwqdSQi9pqVb1OYRKT7un7WFJzo0WEw8xjo6wyEolSikaBr3/o8FhoIMIA9KvbjR4y1WDg" + "session_key": "AgAAAADxKHa9uFxcXzwYoNueL5Xqi69IkD4sni8LlfJL7qNBEY..." }, "type": "m.room_key" } diff --git a/event-schemas/schema/m.room_key b/event-schemas/schema/m.room_key index f5e4ac29..ef8c51c0 100644 --- a/event-schemas/schema/m.room_key +++ b/event-schemas/schema/m.room_key @@ -4,18 +4,29 @@ allOf: description: |- This event type is used to exchange keys for end-to-end encryption. Typically - it is encrypted as an ``m.room.encrypted`` event. + it is encrypted as an ``m.room.encrypted`` event, then sent as a `to-device`_ event. properties: content: properties: algorithm: type: string + enum: ["m.megolm.v1.aes-sha2"] description: |- - The encryption algorithm the keys in this event are to be used - with. The value of this field determines which other properties will - be present. + The encryption algorithm the key in this event is to be used with. + room_id: + type: string + description: The room where the key is used. + session_id: + type: string + description: The ID of the session that the key is for. + session_key: + type: string + description: The key to be exchanged. required: - algorithm + - room_id + - session_id + - session_key type: object type: enum: From 8732378da2e734dae5616e496eb932e0ffc991bc Mon Sep 17 00:00:00 2001 From: Valentin Deniaud Date: Tue, 17 Jul 2018 22:02:53 +0200 Subject: [PATCH 16/27] add required room ids --- event-schemas/examples/m.room.encrypted | 1 + event-schemas/examples/m.room.encryption | 1 + event-schemas/examples/m.room_key | 2 +- 3 files changed, 3 insertions(+), 1 deletion(-) diff --git a/event-schemas/examples/m.room.encrypted b/event-schemas/examples/m.room.encrypted index a0360963..0e7e677a 100644 --- a/event-schemas/examples/m.room.encrypted +++ b/event-schemas/examples/m.room.encrypted @@ -7,6 +7,7 @@ "session_id": "X3lUlvLELLYxeTx4yOVu6UDpasGEVO0Jbu+QFnm0cKQ" }, "event_id": "$WLGTSEFSEF:localhost", + "room_id": "!Cuyf34gef24t:localhost", "origin_server_ts": 1476648761524, "sender": "@example:localhost", "type": "m.room.encrypted", diff --git a/event-schemas/examples/m.room.encryption b/event-schemas/examples/m.room.encryption index 4c6342bb..08f15239 100644 --- a/event-schemas/examples/m.room.encryption +++ b/event-schemas/examples/m.room.encryption @@ -7,6 +7,7 @@ "event_id": "$WLGTSEFJJKJ:localhost", "origin_server_ts": 1476648761524, "sender": "@example:localhost", + "room_id": "!Cuyf34gef24t:localhost", "state_key": "", "type": "m.room.encryption" } diff --git a/event-schemas/examples/m.room_key b/event-schemas/examples/m.room_key index 51249199..53f83e52 100644 --- a/event-schemas/examples/m.room_key +++ b/event-schemas/examples/m.room_key @@ -1,7 +1,7 @@ { "content": { "algorithm": "m.megolm.v1.aes-sha2", - "room_id": "!UCnwUWwIKhcpaPTHtR:sw1v.org", + "room_id": "!Cuyf34gef24t:localhost", "session_id": "X3lUlvLELLYxeTx4yOVu6UDpasGEVO0Jbu+QFnm0cKQ", "session_key": "AgAAAADxKHa9uFxcXzwYoNueL5Xqi69IkD4sni8LlfJL7qNBEY..." }, From 661176cb3a4c4952edd9c9bf022fabbf82bc4a1d Mon Sep 17 00:00:00 2001 From: Valentin Deniaud Date: Tue, 17 Jul 2018 22:39:45 +0200 Subject: [PATCH 17/27] Olm m.room.encrypted example --- ...room.encrypted => m.room.encrypted#megolm} | 8 ++---- event-schemas/examples/m.room.encrypted#olm | 14 ++++++++++ event-schemas/schema/m.room.encrypted | 28 ++++++++++++++----- 3 files changed, 37 insertions(+), 13 deletions(-) rename event-schemas/examples/{m.room.encrypted => m.room.encrypted#megolm} (57%) create mode 100644 event-schemas/examples/m.room.encrypted#olm diff --git a/event-schemas/examples/m.room.encrypted b/event-schemas/examples/m.room.encrypted#megolm similarity index 57% rename from event-schemas/examples/m.room.encrypted rename to event-schemas/examples/m.room.encrypted#megolm index 0e7e677a..1f9b7520 100644 --- a/event-schemas/examples/m.room.encrypted +++ b/event-schemas/examples/m.room.encrypted#megolm @@ -1,7 +1,7 @@ { "content": { "algorithm": "m.megolm.v1.aes-sha2", - "ciphertext": "AwgAEnACgAkLmt6qF84IK++J7UDH2Za1YVchHyprqTqsg2yyOwAtHaZTwyNg37afzg8f3r9IsN9rH4RNFg7MaZencUJe4qvELiDiopUjy5wYVDAtqdBzer5bWRD9ldxp1FLgbQvBcjkkywYjCsmsq6+hArILd9oAQZnGKn/qLsK+5uNX3PaWzDRC9wZPQvWYYPCTov3jCwXKTPsLKIiTrcCXDqMvnn8m+T3zF1/I2zqxg158tnUwWWIw51UO", + "ciphertext": "AwgAEnACgAkLmt6qF84IK++J7UDH2Za1YVchHyprqTqsg...", "device_id": "RJYKSTBOIE", "sender_key": "IlRMeOPX2e0MurIyfWEucYBRVOEEUMrOHqn/8mLqMjA", "session_id": "X3lUlvLELLYxeTx4yOVu6UDpasGEVO0Jbu+QFnm0cKQ" @@ -10,9 +10,5 @@ "room_id": "!Cuyf34gef24t:localhost", "origin_server_ts": 1476648761524, "sender": "@example:localhost", - "type": "m.room.encrypted", - "unsigned": { - "age": 158, - "transaction_id": "m1476648745605.19" - } + "type": "m.room.encrypted" } diff --git a/event-schemas/examples/m.room.encrypted#olm b/event-schemas/examples/m.room.encrypted#olm new file mode 100644 index 00000000..abb23c31 --- /dev/null +++ b/event-schemas/examples/m.room.encrypted#olm @@ -0,0 +1,14 @@ +{ + "type": "m.room.encrypted", + "sender": "@example:localhost", + "content": { + "algorithm": "m.olm.v1.curve25519-aes-sha2", + "sender_key": "Szl29ksW/L8yZGWAX+8dY1XyFi+i5wm+DRhTGkbMiwU", + "ciphertext": { + "7qZcfnBmbEGzxxaWfBjElJuvn7BZx+lSz/SvFrDF/z8": { + "type": 0, + "body": "AwogGJJzMhf/S3GQFXAOrCZ3iKyGU5ZScVtjI0KypTYrW..." + } + } + } +} diff --git a/event-schemas/schema/m.room.encrypted b/event-schemas/schema/m.room.encrypted index cf3e4b4a..664b10cf 100644 --- a/event-schemas/schema/m.room.encrypted +++ b/event-schemas/schema/m.room.encrypted @@ -1,8 +1,6 @@ --- allOf: - # this is a bit of a lie; if the event is sent as a to-device event it won't - # have the room event fields. We really ought to use different event types :/ - - $ref: core-event-schema/room_event.yaml + - $ref: core-event-schema/event.yaml description: |- This event type is used when sending encrypted events. It can be used either @@ -14,16 +12,32 @@ properties: properties: algorithm: type: string + enum: + - m.olm.curve25519-aes-sha256 + - m.megolm.v1.aes-sha description: |- The encryption algorithm used to encrypt this event. The value of this field determines which other properties will be present. ciphertext: - type: - - object - - string + oneOf: + - type: string + - type: object + additionalProperties: + type: object + title: CiphertextInfo + properties: + body: + type: string + description: The encrypted payload. + type: + type: integer + description: The Olm message type. description: |- - Normally required. The encrypted content of the event. + The encrypted content of the event. Either the encrypted payload + itself, in the case of a Megolm event, or a map from the recipient + Curve25519 identity key to ciphertext information, in the case of an + Olm event. For more details, see `Messaging Algorithms`_. required: - algorithm type: object From 248786681ec9d446481b2c529f587ace18d4274c Mon Sep 17 00:00:00 2001 From: Valentin Deniaud Date: Thu, 19 Jul 2018 19:50:05 +0200 Subject: [PATCH 18/27] fix typo --- specification/modules/end_to_end_encryption.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/modules/end_to_end_encryption.rst b/specification/modules/end_to_end_encryption.rst index c43f81c4..1bc6a232 100644 --- a/specification/modules/end_to_end_encryption.rst +++ b/specification/modules/end_to_end_encryption.rst @@ -159,7 +159,7 @@ It is therefore expected that each client will maintain a list of devices for a number of users (in practice, typically each user with whom we share an encrypted room). Furthermore, it is likely that this list will need to be persisted between invocations of the client application (to preserve device -verification data and to alert Alice if Bob suddently gets a new +verification data and to alert Alice if Bob suddenly gets a new device). Alice's client can maintain a list of Bob's devices via the following From 4e0f107ef7207fde8bd9feafdd3bea88caad89b8 Mon Sep 17 00:00:00 2001 From: Valentin Deniaud Date: Thu, 19 Jul 2018 19:57:47 +0200 Subject: [PATCH 19/27] document changed field behavior in e2e sync extension --- .../modules/end_to_end_encryption.rst | 31 ++++++++++++++++--- 1 file changed, 26 insertions(+), 5 deletions(-) diff --git a/specification/modules/end_to_end_encryption.rst b/specification/modules/end_to_end_encryption.rst index 1bc6a232..194d2567 100644 --- a/specification/modules/end_to_end_encryption.rst +++ b/specification/modules/end_to_end_encryption.rst @@ -176,9 +176,10 @@ process: flag. #. During its normal processing of responses to |/sync|_, Alice's client - inspects the |device_lists|_ field. If it is tracking the device lists of - any of the listed users, then it marks the device lists for those users - outdated, and initiates another request to |/keys/query|_ for them. + inspects the ``changed`` property of the |device_lists|_ field. If it is + tracking the device lists of any of the listed users, then it marks the + device lists for those users outdated, and initiates another request to + |/keys/query|_ for them. #. Periodically, Alice's client stores the ``next_batch`` field of the result from |/sync|_ in persistent storage. If Alice later restarts her client, it @@ -214,6 +215,18 @@ process: that the first request's results are ignored (possibly by cancelling the request). +.. Note:: + + When Bob and Alice share a room, with Bob tracking Alice's devices, she may leave + the room and then add a new device. Bob will not be notified of this change, + as he doesn't share a room anymore with Alice. When they start sharing a + room again, Bob has an out-of-date list of Alice's devices. In order to address + this issue, Bob's homeserver will add Alice's user ID to the ``changed`` property of + the ``device_lists`` field, thus Bob will update his list of Alice's devices as part + of his normal processing. Note that Bob can also be notified when he stops sharing + any room with Alice by inspecting the ``left`` property of the ``device_lists`` + field, and as a result should remove her from its list of tracked users. + .. |device_lists| replace:: ``device_lists`` .. _`device_lists`: `device_lists_sync`_ @@ -500,12 +513,20 @@ device_lists DeviceLists Optional. Information on e2e device updates. Note: ========= ========= ============================================= Parameter Type Description ========= ========= ============================================= -changed [string] List of users who have updated their device identity keys - since the previous sync response. +changed [string] List of users who have updated their device identity keys, + or who now share an encrypted room with the client since + the previous sync response. left [string] List of users with whom we do not share any encrypted rooms anymore since the previous sync response. ========= ========= ============================================= +.. NOTE:: + + For optimal performance, Alice should be added to ``changed`` in Bob's sync only + when she adds a new device, or when Alice and Bob now share a room but didn't + share any room previously. However, for the sake of simpler logic, a server + may add Alice to ``changed`` when Alice and Bob share a new room, even if they + previously already shared a room. Example response: From eb8ea0e85a9771a0d4fa0d279e6700321763de47 Mon Sep 17 00:00:00 2001 From: Valentin Deniaud Date: Thu, 26 Jul 2018 10:44:42 +0200 Subject: [PATCH 20/27] remove warning pointing at outdated doc --- specification/modules/end_to_end_encryption.rst | 6 ------ 1 file changed, 6 deletions(-) diff --git a/specification/modules/end_to_end_encryption.rst b/specification/modules/end_to_end_encryption.rst index 194d2567..213d09a5 100644 --- a/specification/modules/end_to_end_encryption.rst +++ b/specification/modules/end_to_end_encryption.rst @@ -21,12 +21,6 @@ Matrix optionally supports end-to-end encryption, allowing rooms to be created whose conversation contents is not decryptable or interceptable on any of the participating homeservers. -.. WARNING:: - - End to end encryption is being worked on and will be coming soon. This - section is incomplete. You can read more about what's underway at - http://matrix.org/speculator/spec/drafts%2Fe2e/client_server/unstable.html#end-to-end-encryption. - Key Distribution ---------------- Encryption and Authentication in Matrix is based around public-key From 6c44233c42e79e5f0552f6d3288fec98be1fa146 Mon Sep 17 00:00:00 2001 From: Valentin Deniaud Date: Thu, 26 Jul 2018 11:38:17 +0200 Subject: [PATCH 21/27] require megolm algorithm in m.room.encryption --- event-schemas/schema/m.room.encryption | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/event-schemas/schema/m.room.encryption b/event-schemas/schema/m.room.encryption index b990a13b..d7c4d429 100644 --- a/event-schemas/schema/m.room.encryption +++ b/event-schemas/schema/m.room.encryption @@ -7,9 +7,11 @@ properties: properties: algorithm: type: string + enum: + - "m.megolm.v1.aes-sha2" description: |- The encryption algorithm to be used to encrypt messages sent in this - room. For example, ``m.megolm.v1.aes-sha2``. + room. rotation_period_ms: type: integer description: |- From f853856f2173792d1f9307ec77a460ccde708f35 Mon Sep 17 00:00:00 2001 From: Valentin Deniaud Date: Sat, 4 Aug 2018 14:59:09 +0200 Subject: [PATCH 22/27] add missing m.room.encrypted event properties --- event-schemas/schema/m.room.encrypted | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/event-schemas/schema/m.room.encrypted b/event-schemas/schema/m.room.encrypted index 664b10cf..6825be1d 100644 --- a/event-schemas/schema/m.room.encrypted +++ b/event-schemas/schema/m.room.encrypted @@ -38,8 +38,21 @@ properties: itself, in the case of a Megolm event, or a map from the recipient Curve25519 identity key to ciphertext information, in the case of an Olm event. For more details, see `Messaging Algorithms`_. + sender_key: + type: string + description: The Curve25519 key of the sender. + device_id: + type: string + description: The ID of the sending device. Required with Megolm. + session_id: + type: string + description: |- + The ID of the session used to encrypt the message. Required with + Megolm. required: - algorithm + - sender_key + - ciphertext type: object type: enum: From b2316ba782c098a123c8f51261c56dbb5dee24bf Mon Sep 17 00:00:00 2001 From: Valentin Deniaud Date: Thu, 16 Aug 2018 13:00:32 +0200 Subject: [PATCH 23/27] enforce unique namespacing in new algorithms experiments --- specification/modules/end_to_end_encryption.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specification/modules/end_to_end_encryption.rst b/specification/modules/end_to_end_encryption.rst index 213d09a5..7dfe8993 100644 --- a/specification/modules/end_to_end_encryption.rst +++ b/specification/modules/end_to_end_encryption.rst @@ -292,8 +292,8 @@ Messaging Algorithm Names Messaging algorithm names use the extensible naming scheme used throughout this specification. Algorithm names that start with ``m.`` are reserved for algorithms defined by this specification. Implementations wanting to experiment -with new algorithms are encouraged to pick algorithm names that start with -their domain to reduce the risk of collisions. +with new algorithms must be uniquely globally namespaced following Java's package +naming conventions. Algorithm names should be short and meaningful, and should list the primitives used by the algorithm so that it is easier to see if the algorithm is using a From 8ba19b51ab36b0fdd62084e8798ddd58c4804e14 Mon Sep 17 00:00:00 2001 From: Valentin Deniaud Date: Thu, 16 Aug 2018 13:04:29 +0200 Subject: [PATCH 24/27] complete Olm documentation --- specification/modules/end_to_end_encryption.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/modules/end_to_end_encryption.rst b/specification/modules/end_to_end_encryption.rst index 7dfe8993..b224126d 100644 --- a/specification/modules/end_to_end_encryption.rst +++ b/specification/modules/end_to_end_encryption.rst @@ -357,7 +357,7 @@ client must not persist a session or remove one-time keys used by a session until it has successfully decrypted a message using that session. Messages with type 1 can only be decrypted with an existing session. If there -is no matching session, the client should show this as an invalid message. +is no matching session, the client must treat this as an invalid message. The plaintext payload is of the form: From 9430f2c7f9a2b31de29ed08f8a5260706546cfe9 Mon Sep 17 00:00:00 2001 From: Valentin Deniaud Date: Fri, 17 Aug 2018 15:12:14 +0200 Subject: [PATCH 25/27] room ID is included in Megolm plaintext, not Olm --- specification/modules/end_to_end_encryption.rst | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/specification/modules/end_to_end_encryption.rst b/specification/modules/end_to_end_encryption.rst index b224126d..fa461cc2 100644 --- a/specification/modules/end_to_end_encryption.rst +++ b/specification/modules/end_to_end_encryption.rst @@ -366,7 +366,6 @@ The plaintext payload is of the form: { "type": "", "content": "", - "room_id": "", "sender": "", "recipient": "", "recipient_keys": { @@ -379,9 +378,6 @@ The plaintext payload is of the form: The type and content of the plaintext message event are given in the payload. -We include the room ID in the payload, because otherwise the homeserver would -be able to change the room a message was sent in. - Other properties are included in order to prevent an attacker from publishing someone else's curve25519 keys as their own and subsequently claiming to have sent messages which they didn't. @@ -433,6 +429,9 @@ The encrypted payload can contain any message event. The plaintext is of the for "room_id": "" } +We include the room ID in the payload, 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 ratchet indices of Megolm sessions. They should reject messages with a ratchet index that they have already decrypted. Care should be taken in order to avoid false positives, as a From 98e2e8de71e27b2394762f647d699ac7af1aa17a Mon Sep 17 00:00:00 2001 From: Valentin Deniaud Date: Sat, 18 Aug 2018 11:40:48 +0200 Subject: [PATCH 26/27] changelog --- changelogs/client_server/newsfragments/1284.clarification | 1 + changelogs/client_server/newsfragments/1284.feature.rst | 7 +++++++ 2 files changed, 8 insertions(+) create mode 100644 changelogs/client_server/newsfragments/1284.clarification create mode 100644 changelogs/client_server/newsfragments/1284.feature.rst diff --git a/changelogs/client_server/newsfragments/1284.clarification b/changelogs/client_server/newsfragments/1284.clarification new file mode 100644 index 00000000..7bc92f47 --- /dev/null +++ b/changelogs/client_server/newsfragments/1284.clarification @@ -0,0 +1 @@ +Clarify ``changed`` field behaviour in device tracking process diff --git a/changelogs/client_server/newsfragments/1284.feature.rst b/changelogs/client_server/newsfragments/1284.feature.rst new file mode 100644 index 00000000..c658142e --- /dev/null +++ b/changelogs/client_server/newsfragments/1284.feature.rst @@ -0,0 +1,7 @@ +End-to-end encryption for group chats: + + - Olm and Megolm messaging algorithms. + - ``m.room.encrypted``, ``m.room.encryption``, ``m.room_key`` events. + - Device verification process. + - ``device_one_time_keys_count`` sync parameter. + - ``device_lists:left`` sync parameter. From 206f78cb48ba5f247a705e6d5e0bc0737c7d7e5f Mon Sep 17 00:00:00 2001 From: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> Date: Mon, 20 Aug 2018 09:21:15 +0100 Subject: [PATCH 27/27] Rename 1284.feature.rst to 1284.feature --- .../newsfragments/{1284.feature.rst => 1284.feature} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename changelogs/client_server/newsfragments/{1284.feature.rst => 1284.feature} (100%) diff --git a/changelogs/client_server/newsfragments/1284.feature.rst b/changelogs/client_server/newsfragments/1284.feature similarity index 100% rename from changelogs/client_server/newsfragments/1284.feature.rst rename to changelogs/client_server/newsfragments/1284.feature