From 2395dd87c061f6b37f91857e5a410b4ef150abc2 Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Tue, 1 Nov 2022 17:49:45 -0400 Subject: [PATCH] more clarifications, and move event definitions to yaml --- .../newsfragments/1294.clarification | 1 + .../modules/end_to_end_encryption.md | 9 ++++ content/client-server-api/modules/secrets.md | 47 +------------------ .../examples/m.secret.request.yaml | 6 +++ .../event-schemas/examples/m.secret.send.yaml | 4 ++ .../schema/m.secret.request.yaml | 40 ++++++++++++++++ data/event-schemas/schema/m.secret.send.yaml | 32 +++++++++++++ 7 files changed, 94 insertions(+), 45 deletions(-) create mode 100644 changelogs/client_server/newsfragments/1294.clarification create mode 100644 data/event-schemas/examples/m.secret.request.yaml create mode 100644 data/event-schemas/examples/m.secret.send.yaml create mode 100644 data/event-schemas/schema/m.secret.request.yaml create mode 100644 data/event-schemas/schema/m.secret.send.yaml diff --git a/changelogs/client_server/newsfragments/1294.clarification b/changelogs/client_server/newsfragments/1294.clarification new file mode 100644 index 00000000..8132e060 --- /dev/null +++ b/changelogs/client_server/newsfragments/1294.clarification @@ -0,0 +1 @@ +Clarify parts of the end-to-end encryption sections. 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 05093b63..cc4b1571 100644 --- a/content/client-server-api/modules/end_to_end_encryption.md +++ b/content/client-server-api/modules/end_to_end_encryption.md @@ -510,6 +510,15 @@ could also send that message. As well, the order of the | | | | ``` +In contrast with the case of using to-devices messages, when using in-room +messages, Alice only sends one request event (an event with type +`m.room.message` with `msgtype: m.key.verification.request`, rather than an +event with type `m.key.verification.request`), to the room. In addition, Alice +does not send an `m.key.verification.cancel` event to tell Bob's other devices +that the request as already been accepted; instead, when Bob's other devices +see his `m.key.verification.ready` event, they will know that the request has +already been accepted, and that they should ignore the request. + When using in-room messages and the room has encryption enabled, clients should ensure that encryption does not hinder the verification. For example, if the verification messages are encrypted, clients must ensure that all the diff --git a/content/client-server-api/modules/secrets.md b/content/client-server-api/modules/secrets.md index fcc36898..38534a4e 100644 --- a/content/client-server-api/modules/secrets.md +++ b/content/client-server-api/modules/secrets.md @@ -292,49 +292,6 @@ confirm sharing the secret. ##### Event definitions -###### `m.secret.request` +{{% event event="m.secret.request" %}} -Sent by a client to request a secret from another device or to cancel a -previous request. It is sent as an unencrypted to-device event. - -| Parameter | Type | Description | -|-----------------------|--------|----------------------------------------------------------------------------------------| -| name | string | Required if ``action`` is ``request``. The name of the secret that is being requested. | -| action | enum | **Required.** One of ["request", "request_cancellation"]. | -| requesting_device_id | string | **Required.** The ID of the device requesting the secret. | -| request_id | string | **Required.** A random string uniquely identifying (with respect to the requester and the target) the target for a secret. If the secret is requested from multiple devices at the same time, the same ID may be used for every target. The same ID is also used in order to cancel a previous request. | - -Example: - -```json -{ - "name": "org.example.some.secret", - "action": "request", - "requesting_device_id": "ABCDEFG", - "request_id": "randomly_generated_id_9573" -} -``` - -###### `m.secret.send` - -Sent by a client to share a secret with another device, in response to an -`m.secret.request` event. It must be encrypted as an `m.room.encrypted` event -using [Olm](#molmv1curve25519-aes-sha2), then sent as a to-device event. - -The `request_id` must match the ID previously given in an `m.secret.request` -event, and this event must come from a device that the `m.secret.request` event -was originally sent to. - -| Parameter | Type | Description | -|-------------|--------|--------------------------------------------------------------| -| request_id | string | **Required.** The ID of the request that this a response to. | -| secret | string | **Required.** The contents of the secret. | - -Example: - -```json -{ - "request_id": "randomly_generated_id_9573", - "secret": "ThisIsASecretDon'tTellAnyone" -} -``` +{{% event event="m.secret.send" %}} diff --git a/data/event-schemas/examples/m.secret.request.yaml b/data/event-schemas/examples/m.secret.request.yaml new file mode 100644 index 00000000..e510632d --- /dev/null +++ b/data/event-schemas/examples/m.secret.request.yaml @@ -0,0 +1,6 @@ +{ + "name": "org.example.some.secret", + "action": "request", + "requesting_device_id": "ABCDEFG", + "request_id": "randomly_generated_id_9573" +} diff --git a/data/event-schemas/examples/m.secret.send.yaml b/data/event-schemas/examples/m.secret.send.yaml new file mode 100644 index 00000000..02c7ad6b --- /dev/null +++ b/data/event-schemas/examples/m.secret.send.yaml @@ -0,0 +1,4 @@ +{ + "request_id": "randomly_generated_id_9573", + "secret": "ThisIsASecretDon'tTellAnyone" +} diff --git a/data/event-schemas/schema/m.secret.request.yaml b/data/event-schemas/schema/m.secret.request.yaml new file mode 100644 index 00000000..e9d72200 --- /dev/null +++ b/data/event-schemas/schema/m.secret.request.yaml @@ -0,0 +1,40 @@ +--- +allOf: + - $ref: core-event-schema/event.yaml +description: |- + Sent by a client to request a secret from another device or to cancel a + previous request. It is sent as an unencrypted to-device event. +properties: + content: + properties: + name: + type: string + description: |- + Required if `action` is `request`. The name of the secret that is + being requested. + action: + type: string + enum: + - request + - request_cancellation + requesting_device_id: + type: string + description: |- + The ID of the device requesting the secret. + request_id: + type: string + description: |- + A random string uniquely identifying (with respect to the requester + and the target) the target for a secret. If the secret is requested + from multiple devices at the same time, the same ID may be used for + every target. The same ID is also used in order to cancel a previous + request. + required: + - action + - requesting_device_id + - request_id + type: + enum: + - m.secret.request + type: string +type: object diff --git a/data/event-schemas/schema/m.secret.send.yaml b/data/event-schemas/schema/m.secret.send.yaml new file mode 100644 index 00000000..0ec9d2b4 --- /dev/null +++ b/data/event-schemas/schema/m.secret.send.yaml @@ -0,0 +1,32 @@ +--- +allOf: + - $ref: core-event-schema/event.yaml +description: |- + Sent by a client to share a secret with another device, in response to an + `m.secret.request` event. It must be encrypted as an `m.room.encrypted` event + using [Olm](#molmv1curve25519-aes-sha2), then sent as a to-device event. + + The `request_id` must match the ID previously given in an `m.secret.request` + event. The recipient must ensure that this event comes from a device that the + `m.secret.request` event was originally sent to, and that the device is + trusted. This should be done by checking the sender key of the Olm session that + the event was sent over. +properties: + content: + properties: + request_id: + type: string + description: |- + The ID of the request that this is a response to. + secret: + type: string + description: |- + The contents of the secret + required: + - request_id + - secret + type: + enum: + - m.secret.send + type: string +type: object