From 46fde9723cce522655b5375b1962ef0650438b03 Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Fri, 19 Oct 2018 10:55:14 -0400 Subject: [PATCH] document megolm session export format --- .../modules/end_to_end_encryption.rst | 128 +++++++++++++++++- 1 file changed, 124 insertions(+), 4 deletions(-) diff --git a/specification/modules/end_to_end_encryption.rst b/specification/modules/end_to_end_encryption.rst index 7a9dbabc..06a3ec19 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,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": "", + }, + "session_id": "X3lUlvLELLYxeTx4yOVu6UDpasGEVO0Jbu+QFnm0cKQ", + "session_key": "AgAAAADxKHa9uFxcXzwYoNueL5Xqi69IkD4sni8Llf..." + }, + ... + ] + } + Messaging Algorithms --------------------