wholetrans/docs-matrix-spec
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

document megolm session export format

Browse source
This commit is contained in:
Hubert Chathi 2018-10-19 10:55:14 -04:00
parent 15eb69cc47
commit 46fde9723c
1 changed files with 124 additions and 4 deletions
Download patch file Download diff file Expand all files Collapse all files

128
specification/modules/end_to_end_encryption.rst
View file

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