document 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,120 @@ 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 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.)
+4. Concatenate the following strings:
+
+   ============ ===============================================================
+   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 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 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``
+
+=============================== =========== ====================================
+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.
+                                            It starts out empty, but each time
+                                            the key is forwarded to another
+                                            device, such as via a
+                                            `m.forwarded_room_key`_ event, the
+                                            previous sender in the chain is
+                                            added to the end of the list.
+                                            Key exports do not affect this
+                                            list.
+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. 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. This will be an
+                                            object with an ``ed25519`` property
+                                            whose value is the Ed25519 key.
+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
 --------------------