diff --git a/changelogs/client_server/newsfragments/1701.feature b/changelogs/client_server/newsfragments/1701.feature new file mode 100644 index 00000000..39c22dd7 --- /dev/null +++ b/changelogs/client_server/newsfragments/1701.feature @@ -0,0 +1 @@ +Documented megolm session export format. \ No newline at end of file diff --git a/specification/modules/end_to_end_encryption.rst b/specification/modules/end_to_end_encryption.rst index 7a9dbabc..72bfae35 100644 --- a/specification/modules/end_to_end_encryption.rst +++ b/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": "", + }, + "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