diff --git a/changelogs/client_server/newsfragments/2410.clarification b/changelogs/client_server/newsfragments/2410.clarification new file mode 100644 index 00000000..995a6a88 --- /dev/null +++ b/changelogs/client_server/newsfragments/2410.clarification @@ -0,0 +1 @@ +Clarify history key sharing requirements. Contributed by @HarHarLinks and Matrix Stammtisch Aachen. 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 ac77ec76..b056d3bd 100644 --- a/content/client-server-api/modules/end_to_end_encryption.md +++ b/content/client-server-api/modules/end_to_end_encryption.md @@ -1551,7 +1551,7 @@ objects described as follows: {{% added-in v="1.19" %}} -When Alice invites Bob to an encrypted room, she might want Bob to have access +When Alice invites Bob to an encrypted room, she likely wants Bob to have access to messages that were previously sent in that room, subject to the [history visibility](#room-history-visibility) setting of the room. @@ -1610,12 +1610,22 @@ room. ##### Construction and sharing of the key bundle -Alice's client MAY choose not to share any room history (even messages sent when the -history visibity setting would allow sharing) if the current history -visibility setting does not allow sharing (i.e. if `history_visibility` is -set to `invited` or `joined`). +Marking keys as [shareable](#shareable-encryption-sessions) essentially serves as +precomputation of which keys Bob needs to decrypt all messages he can see, as +defined by the room's history visibility. -Otherwise, before inviting Bob to a room, Alice's client constructs and sends a key bundle as follows: +History visibility mechanics prevent changing the visibility of events +retrospectively. It is thus possible for a room timeline to have "gappy" visibility. +For example, events sent in the past during `shared` visibility are visible to new +members, even though events sent more recently (during `joined` visibility) are not visible. +In such cases where the current history visibility setting does not allow sharing +(i.e. if `history_visibility` is set to `invited` or `joined`), client implementations +MAY choose not to share *any* room history, even messages sent when the +history visibility setting would allow sharing. + +In all other cases, Alice's client SHOULD share all available shareable keys. + +Before inviting Bob to a room, Alice's client constructs and sends a key bundle as follows: 1. Alice's client SHOULD ensure that it has downloaded all keys relevant to the room from [server-side key backup](#server-side-key-backups), if she is using it. diff --git a/data/event-schemas/schema/components/room_key_withheld_content.yaml b/data/event-schemas/schema/components/room_key_withheld_content.yaml index ec7bc136..e25b5424 100644 --- a/data/event-schemas/schema/components/room_key_withheld_content.yaml +++ b/data/event-schemas/schema/components/room_key_withheld_content.yaml @@ -33,7 +33,9 @@ properties: - m.no_olm - m.history_not_shared description: |- - A machine-readable code for why the key was not sent. Codes beginning + A machine-readable code for why the key was not sent, as defined by + [Reporting that decryption keys are withheld](#reporting-that-decryption-keys-are-withheld). + Codes beginning with `m.` are reserved for codes defined in the Matrix specification. Custom codes must use the Java package naming convention.