Merge pull request #1701 from uhoreg/e2e_export

document megolm session export format

Author: richvdh

changelogs/client_server/newsfragments/1701.feature

@@ -0,0 +1 @@
+Documented megolm session export format.

specification/modules/end_to_end_encryption.rst

@@ -422,13 +422,19 @@ Device verification may reach one of several conclusions. For example:
    decrypted by such a device. For the Olm protocol, this is documented at
    https://matrix.org/git/olm/about/docs/signing.rst.
 
-Key sharing
------------
+.. section name changed, so make sure that old links keep working
+.. _key-sharing:
+
+Sharing keys between devices
+----------------------------
 
 If Bob has an encrypted conversation with Alice on his computer, and then logs in
 through his phone for the first time, he may want to have access to the previously
-exchanged messages. To address this issue, events exist for requesting and sending
-keys from device to device.
+exchanged messages. To address this issue, several methods are provided to
+allow users to transfer keys from one device to another.
+
+Key requests
+~~~~~~~~~~~~
 
 When a device is missing keys to decrypt messages, it can request the keys by
 sending `m.room_key_request`_ to-device messages to other devices with
@@ -447,6 +453,111 @@ previously-received ``request`` message with the same ``request_id`` and
   A reasonable stategy is for a user's client to only send keys requested by the
   verified devices of the same user.
 
+Key exports
+~~~~~~~~~~~
+
+Keys can be manually exported from one device to an encrypted file, copied to
+another device, and imported. The file is encrypted using a user-supplied
+passphrase, and is created as follows:
+
+1. Encode the sessions a JSON object, formatted as described in `Key export
+   format`_.
+2. Generate a 512-bit key from the user-entered passphrase by computing
+   `PBKDF2`_\(HMAC-SHA-512, passphrase, S, N, 512), where S is a 128-bit
+   cryptographically-random salt and N is the number of rounds.  N should be at
+   least 100,000.  The keys K and K' are set to the first and last 256 bits of
+   this generated key, respectively.  K is used as an AES-256 key, and K' is
+   used as an HMAC-SHA-256 key.
+3. Serialize the JSON object as a UTF-8 string, and encrypt it using
+   AES-CTR-256 with the key K generated above, and with a 128-bit
+   cryptographically-random initialization vector, IV, that has bit 63 set to
+   zero. (Setting bit 63 to zero in IV is needed to work around differences in
+   implementations of AES-CTR.)
+4. Concatenate the following data:
+
+   ============ ===============================================================
+   Size (bytes) Description
+   ============ ===============================================================
+   1            Export format version, which must be ``0x01``.
+   16           The salt S.
+   16           The initialization vector IV.
+   4            The number of rounds N, as a big-endian unsigned 32-bit integer.
+   variable     The encrypted JSON object.
+   32           The HMAC-SHA-256 of all the above string concatenated together,
+                using K' as the key.
+   ============ ===============================================================
+
+5. Base64-encode the string above. Newlines may be added to avoid overly long
+   lines.
+6. Prepend the resulting string with ``-----BEGIN MEGOLM SESSION DATA-----``,
+   with a trailing newline, and append ``-----END MEGOLM SESSION DATA-----``,
+   with a leading and trailing newline.
+
+Key export format
+<<<<<<<<<<<<<<<<<
+
+The exported sessions are formatted as a JSON object of type ``ExportData``
+described as follows:
+
+``ExportData``
+
+=============== ================= ==============================================
+Parameter       Type              Description
+=============== ================= ==============================================
+sessions        ``[SessionData]`` Required. The sessions that are being
+                                  exported.
+=============== ================= ==============================================
+
+``SessionData``
+
+.. table::
+   :widths: auto
+
+   =============================== =========== ====================================
+   Parameter                       Type        Description
+   =============================== =========== ====================================
+   algorithm                       string      Required. The encryption algorithm
+                                               that the session uses. Must be
+                                               ``m.megolm.v1.aes-sha2``.
+   forwarding_curve25519_key_chain [string]    Required. Chain of Curve25519 keys
+                                               through which this session was
+                                               forwarded, via
+                                               `m.forwarded_room_key`_ events.
+   room_id                         string      Required. The room where the
+                                               session is used.
+   sender_key                      string      Required. The Curve25519 key of the
+                                               device which initiated the session
+                                               originally.
+   sender_claimed_keys             {string:    Required. The Ed25519 key of the
+                                   integer}    device which initiated the session
+                                               originally.
+   session_id                      string      Required. The ID of the session.
+   session_key                     string      Required. The key for the session.
+   =============================== =========== ====================================
+
+Example:
+
+.. code:: json
+
+    {
+        "sessions": [
+            {
+                "algorithm": "m.megolm.v1.aes-sha2",
+                "forwarding_curve25519_key_chain": [
+                    "hPQNcabIABgGnx3/ACv/jmMmiQHoeFfuLB17tzWp6Hw"
+                ],
+                "room_id": "!Cuyf34gef24t:localhost",
+                "sender_key": "RF3s+E7RkTQTGF2d8Deol0FkQvgII2aJDf3/Jp5mxVU",
+                "sender_claimed_keys": {
+                    "ed25519": "<device ed25519 identity key>",
+                },
+                "session_id": "X3lUlvLELLYxeTx4yOVu6UDpasGEVO0Jbu+QFnm0cKQ",
+                "session_key": "AgAAAADxKHa9uFxcXzwYoNueL5Xqi69IkD4sni8Llf..."
+            },
+            ...
+        ]
+    }
+
 Messaging Algorithms
 --------------------
 
@@ -724,6 +835,7 @@ Example response:
 .. _`Megolm specification`: http://matrix.org/docs/spec/megolm.html
 .. _`JSON Web Key`: https://tools.ietf.org/html/rfc7517#appendix-A.3
 .. _`W3C extension`: https://w3c.github.io/webcrypto/#iana-section-jwk
+.. _`PBKDF2`: https://tools.ietf.org/html/rfc2898#section-5.2
 
 .. _`Signing JSON`: ../appendices.html#signing-json