Merge pull request #1294 from uhoreg/rhul_clarifications

add some e2ee clarifications

data/event-schemas/examples/m.secret.request.yaml

@@ -0,0 +1,9 @@
+{
+  "type": "m.secret.request",
+  "content": {
+    "name": "org.example.some.secret",
+    "action": "request",
+    "requesting_device_id": "ABCDEFG",
+    "request_id": "randomly_generated_id_9573"
+  }
+}

data/event-schemas/examples/m.secret.send.yaml

@@ -0,0 +1,7 @@
+{
+  "type": "m.secret.send",
+  "content": {
+    "request_id": "randomly_generated_id_9573",
+    "secret": "ThisIsASecretDon'tTellAnyone"
+  }
+}

data/event-schemas/schema/m.forwarded_room_key.yaml

@@ -3,9 +3,9 @@ allOf:
   - $ref: core-event-schema/event.yaml
 
 description: |-
-  This event type is used to forward keys for end-to-end encryption. Typically
-  it is encrypted as an `m.room.encrypted` event, then sent as a [to-device](/client-server-api/#send-to-device-messaging)
-  event.
+  This event type is used to forward keys for end-to-end encryption.
+  It is encrypted as an `m.room.encrypted` event using [Olm](#molmv1curve25519-aes-sha2),
+  then sent as a [to-device](/client-server-api/#send-to-device-messaging) event.
 properties:
   content:
     properties:

data/event-schemas/schema/m.room_key.yaml

@@ -3,8 +3,9 @@ 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, then sent as a [to-device](/client-server-api/#send-to-device-messaging) event.
+  This event type is used to exchange keys for end-to-end encryption.
+  It is encrypted as an `m.room.encrypted` event using [Olm](#molmv1curve25519-aes-sha2),
+  then sent as a [to-device](/client-server-api/#send-to-device-messaging) event.
 properties:
   content:
     properties:

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

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
+  a verified device owned by the recipient. 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