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

Start describing the plaintext payload format for encrypted messages, add the exact URLs used for key queries from clients and for key queries for federation

Browse source
This commit is contained in:
Mark Haines 2015-07-24 11:21:14 +01:00
parent 41d204e72c
commit 6597aaa448
1 changed files with 43 additions and 14 deletions
Download patch file Download diff file Expand all files Collapse all files

57
specification/41_end_to_end_encryption.rst
View file

@ -96,7 +96,7 @@ The JSON object is signed using the process given by `Signing JSON`_.
.. code:: http .. code:: http
200 OK HTTP/1.1 200 OK
Content-Type: application/json Content-Type: application/json
{ {
@ -162,6 +162,12 @@ lies about the keys a user owns.
} } } } } } } } } } } }
Clients use ``/_matrix/client/v2_alpha/keys/query`` on their own homeservers to
claim keys for any user they wish to contact. Homeservers will respond with the
keys for their local users and forward requests for remote users to
``/_matrix/federation/v1/user/keys/query``.
Claiming One Time Keys Claiming One Time Keys
~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~
@ -212,6 +218,11 @@ time key once it has given that key to another user.
} } } } } } } }
Clients use ``/_matrix/client/v2_alpha/keys/claim`` on their own homeservers to
claim keys for any user they wish to contact. Homeservers will respond with the
keys for their local users and forward requests for remote users to
``/_matrix/federation/v1/user/keys/claim``.
Sending a Message Sending a Message
~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~
@ -220,24 +231,27 @@ Encrypted messages are sent in the form.
.. code:: json .. code:: json
{ {
"type": "m.room.encrypted" "type": "m.room.encrypted"
"content": { "content": {
"algorithm": "<algorithm_name>" "algorithm": "<algorithm_name>"
} } } } }
Using Olm
#########
.. code:: json .. code:: json
{ {
"type": "m.room.message" "type": "m.room.encrypted"
"content": { "content": {
"algorithm": "m.olm.v1.curve25519-aes-sha2", "algorithm": "m.olm.v1.curve25519-aes-sha2",
"sender_key": <sender_curve25519_key>, "sender_key": "<sender_curve25519_key>",
"ciphertext": { "ciphertext": {
"<device_curve25519_key>: { "<device_curve25519_key>": {
"type": 0, "type": 0,
"body": "<base_64>" "body": "<base_64>"
} } } } } } } }
The plaintext payload is of the form: The plaintext payload is of the form:
@ -245,4 +259,19 @@ The plaintext payload is of the form:
.. code:: json .. code:: json
{ {
"type": "<type of the plaintext event>",
"content": "<content for the plaintext event>",
"room_id": "<the room_id>",
"fingerprint": "<sha256 hash of the currently participating keys>"
} }
The type and content of the plaintext message event are given in the payload.
Encyrpting state events is not supported.
We include the room ID in the payload, because otherwise the homeserver would
be able to change the room a message was sent in. We include a hash of the
participating keys so that clients can detect if another device is unexpectedly
included in the conversation.
Clients must confirm that the ``sender_key`` actually belongs to the device
that sent the message.