document E2E events

This was written by Richard van der Hoff.

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"
+  }
+}

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"
+}

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"
+}

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

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

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

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}}