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

Merge pull request #1701 from uhoreg/e2e_export

Browse source 
document megolm session export format
This commit is contained in:
Richard van der Hoff 2018-11-06 11:58:00 +00:00 • committed by GitHub
commit 767af87744
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
2 changed files with 117 additions and 4 deletions
Download patch file Download diff file Expand all files Collapse all files

1
changelogs/client_server/newsfragments/1701.feature Normal file
View file

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

120
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,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