From 019c290fa2e4aef1e0b98aad358d5a35fef45c50 Mon Sep 17 00:00:00 2001
From: Valentin Deniaud <valentin.deniaud@inpt.fr>
Date: Wed, 1 Aug 2018 00:25:31 +0200
Subject: [PATCH] document m.forwarded_room_key

---
 event-schemas/examples/m.forwarded_room_key | 14 +++++
 event-schemas/schema/m.forwarded_room_key   | 58 +++++++++++++++++++++
 2 files changed, 72 insertions(+)
 create mode 100644 event-schemas/examples/m.forwarded_room_key
 create mode 100644 event-schemas/schema/m.forwarded_room_key

diff --git a/event-schemas/examples/m.forwarded_room_key b/event-schemas/examples/m.forwarded_room_key
new file mode 100644
index 000000000..8ab85c48d
--- /dev/null
+++ b/event-schemas/examples/m.forwarded_room_key
@@ -0,0 +1,14 @@
+{
+  "content": {
+    "algorithm": "m.megolm.v1.aes-sha2",
+    "room_id": "!Cuyf34gef24t:localhost",
+    "session_id": "X3lUlvLELLYxeTx4yOVu6UDpasGEVO0Jbu+QFnm0cKQ",
+    "session_key": "AgAAAADxKHa9uFxcXzwYoNueL5Xqi69IkD4sni8Llf...",
+    "sender_key": "RF3s+E7RkTQTGF2d8Deol0FkQvgII2aJDf3/Jp5mxVU",
+    "sender_claimed_ed25519_key": "aj40p+aw64yPIdsxoog8jhPu9i7l7NcFRecuOQblE3Y",
+    "forwarding_curve25519_key_chain": [
+      "hPQNcabIABgGnx3/ACv/jmMmiQHoeFfuLB17tzWp6Hw"
+    ]
+  },
+  "type": "m.room_key"
+}
diff --git a/event-schemas/schema/m.forwarded_room_key b/event-schemas/schema/m.forwarded_room_key
new file mode 100644
index 000000000..02d91f4ef
--- /dev/null
+++ b/event-schemas/schema/m.forwarded_room_key
@@ -0,0 +1,58 @@
+---
+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.
+properties:
+  content:
+    properties:
+      algorithm:
+        type: string
+        description: |-
+          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.
+      sender_key:
+        type: string
+        description: |-
+          The Curve25519 key of the device which initiated the session originally.
+      session_id:
+        type: string
+        description: The ID of the session holding the key.
+      session_key:
+        type: string
+        description: The key to be exchanged.
+      sender_claimed_ed25519_key:
+        type: string
+        description: |-
+          The Ed25519 key of the device which initiated the session originally.
+          It is 'claimed' because the receiving device has no way to tell that the
+          original room_key actually came from a device which owns the private part of
+          this key unless they have done device verification.
+      forwarding_curve25519_key_chain:
+        type: array
+        items:
+          type: string
+        description: |-
+          Chain of Curve25519 keys. It starts out empty, but each time the
+          key is forwarded to another device, the previous sender in the chain is added
+          to the end of the list. For example, if the key is forwarded from A to B to
+          C, this field is empty between A and B, and contains A's Curve25519 key between
+          B and C.
+    required:
+      - algorithm
+      - room_id
+      - session_id
+      - session_key
+      - sender_claimed_ed25519_key
+      - forwarding_curve25519_key_chain
+      - sender_key
+    type: object
+  type:
+    enum:
+      - m.forwarded_room_key
+    type: string
+type: object