archive
/
matrix-spec-proposals
mirror of https://github.com/matrix-org/matrix-spec-proposals
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #3150 from uhoreg/verification_fixes

Browse Source 
Make SAS outline fit with key verification in DM flow.
pull/3368/head
Hubert Chathi 4 years ago committed by Richard van der Hoff
parent 194fef8022 7a960375cc
commit 3084f3d32f
2 changed files with 23 additions and 25 deletions
Show Stats Download Patch File Download Diff File

1
changelogs/client_server/newsfragments/3150.feature
Unescape Escape View File

@ -0,0 +1 @@
Add key verification using in-room messages as per [MSC2241](https://github.com/matrix-org/matrix-doc/pull/2241).

47
content/client-server-api/modules/end_to_end_encryption.md
Unescape Escape View File

@ -247,8 +247,7 @@ file type. The key is sent using the [JSON Web
Key](https://tools.ietf.org/html/rfc7517#appendix-A.3) format, with a Key](https://tools.ietf.org/html/rfc7517#appendix-A.3) format, with a
[W3C extension](https://w3c.github.io/webcrypto/#iana-section-jwk). [W3C extension](https://w3c.github.io/webcrypto/#iana-section-jwk).
Extensions to `m.room.message` msgtypes ###### Extensions to `m.room.message` msgtypes
<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
This module adds `file` and `thumbnail_file` properties, of type This module adds `file` and `thumbnail_file` properties, of type
`EncryptedFile`, to `m.room.message` msgtypes that reference files, such `EncryptedFile`, to `m.room.message` msgtypes that reference files, such
@ -572,8 +571,7 @@ To advertise support for this method, clients use the name `m.sas.v1` in the
`methods` fields of the `m.key.verification.request` and `methods` fields of the `m.key.verification.request` and
`m.key.verification.ready` events. `m.key.verification.ready` events.
The verification process takes place over [to-device](#send-to-device-messaging) messages in two The verification process takes place in two phases:
phases:
1. Key agreement phase (based on [ZRTP key 1. Key agreement phase (based on [ZRTP key
agreement](https://tools.ietf.org/html/rfc6189#section-4.4.1)). agreement](https://tools.ietf.org/html/rfc6189#section-4.4.1)).
@ -584,63 +582,62 @@ The process between Alice and Bob verifying each other would be:
1. Alice and Bob establish a secure out-of-band connection, such as 1. Alice and Bob establish a secure out-of-band connection, such as
meeting in-person or a video call. "Secure" here means that either meeting in-person or a video call. "Secure" here means that either
party cannot be impersonated, not explicit secrecy. party cannot be impersonated, not explicit secrecy.
2. Alice and Bob communicate which devices they'd like to verify with 2. Alice and Bob begin a key verification using the key verification
each other. framework as described above.
3. Alice selects Bob's device from the device list and begins 3. Alice's device sends Bob's device an `m.key.verification.start`
verification. message. Alice's device ensures it has a copy of Bob's device key.
4. Alice's client ensures it has a copy of Bob's device key. 4. Bob's device receives the message and selects a key agreement
5. Alice's device sends Bob's device an `m.key.verification.start`
message.
6. Bob's device receives the message and selects a key agreement
protocol, hash algorithm, message authentication code, and SAS protocol, hash algorithm, message authentication code, and SAS
method supported by Alice's device. method supported by Alice's device.
7. Bob's device ensures it has a copy of Alice's device key. 5. Bob's device ensures it has a copy of Alice's device key.
8. Bob's device creates an ephemeral Curve25519 key pair 6. Bob's device creates an ephemeral Curve25519 key pair
(*K<sub>B</sub><sup>private</sup>*, *K<sub>B</sub><sup>public</sup>*), (*K<sub>B</sub><sup>private</sup>*, *K<sub>B</sub><sup>public</sup>*),
and calculates the hash (using the chosen algorithm) of the public and calculates the hash (using the chosen algorithm) of the public
key *K<sub>B</sub><sup>public</sup>*. key *K<sub>B</sub><sup>public</sup>*.
9. Bob's device replies to Alice's device with an 7. Bob's device replies to Alice's device with an
`m.key.verification.accept` message. `m.key.verification.accept` message.
10. Alice's device receives Bob's message and stores the commitment hash 8. Alice's device receives Bob's message and stores the commitment hash
for later use. for later use.
11. Alice's device creates an ephemeral Curve25519 key pair 9. Alice's device creates an ephemeral Curve25519 key pair
(*K<sub>A</sub><sup>private</sup>*, *K<sub>A</sub><sup>public</sup>*) (*K<sub>A</sub><sup>private</sup>*, *K<sub>A</sub><sup>public</sup>*)
and replies to Bob's device with an `m.key.verification.key`, and replies to Bob's device with an `m.key.verification.key`,
sending only the public key sending only the public key
*K<sub>A</sub><sup>public</sup>*. *K<sub>A</sub><sup>public</sup>*.
12. Bob's device receives Alice's message and replies with its own 10. Bob's device receives Alice's message and replies with its own
`m.key.verification.key` message containing its public key `m.key.verification.key` message containing its public key
*K<sub>B</sub><sup>public</sup>*. *K<sub>B</sub><sup>public</sup>*.
13. Alice's device receives Bob's message and verifies the commitment 11. Alice's device receives Bob's message and verifies the commitment
hash from earlier matches the hash of the key Bob's device just sent hash from earlier matches the hash of the key Bob's device just sent
and the content of Alice's `m.key.verification.start` message. and the content of Alice's `m.key.verification.start` message.
14. Both Alice and Bob's devices perform an Elliptic-curve 12. Both Alice and Bob's devices perform an Elliptic-curve
Diffie-Hellman Diffie-Hellman
(*ECDH(K<sub>A</sub><sup>private</sup>*, *K<sub>B</sub><sup>public</sup>*)), (*ECDH(K<sub>A</sub><sup>private</sup>*, *K<sub>B</sub><sup>public</sup>*)),
using the result as the shared secret. using the result as the shared secret.
15. Both Alice and Bob's devices display a SAS to their users, which is 13. Both Alice and Bob's devices display a SAS to their users, which is
derived from the shared key using one of the methods in this derived from the shared key using one of the methods in this
section. If multiple SAS methods are available, clients should allow section. If multiple SAS methods are available, clients should allow
the users to select a method. the users to select a method.
16. Alice and Bob compare the strings shown by their devices, and tell 14. Alice and Bob compare the strings shown by their devices, and tell
their devices if they match or not. their devices if they match or not.
17. Assuming they match, Alice and Bob's devices calculate the HMAC of 15. Assuming they match, Alice and Bob's devices calculate the HMAC of
their own device keys and a comma-separated sorted list of the key their own device keys and a comma-separated sorted list of the key
IDs that they wish the other user to verify, using SHA-256 as the IDs that they wish the other user to verify, using SHA-256 as the
hash function. HMAC is defined in [RFC hash function. HMAC is defined in [RFC
2104](https://tools.ietf.org/html/rfc2104). The key for the HMAC is 2104](https://tools.ietf.org/html/rfc2104). The key for the HMAC is
different for each item and is calculated by generating 32 bytes different for each item and is calculated by generating 32 bytes
(256 bits) using [the key verification HKDF](#hkdf-calculation). (256 bits) using [the key verification HKDF](#hkdf-calculation).
18. Alice's device sends Bob's device an `m.key.verification.mac` 16. Alice's device sends Bob's device an `m.key.verification.mac`
message containing the MAC of Alice's device keys and the MAC of her message containing the MAC of Alice's device keys and the MAC of her
key IDs to be verified. Bob's device does the same for Bob's device key IDs to be verified. Bob's device does the same for Bob's device
keys and key IDs concurrently with Alice. keys and key IDs concurrently with Alice.
19. When the other device receives the `m.key.verification.mac` message, 17. When the other device receives the `m.key.verification.mac` message,
the device calculates the HMAC of its copies of the other device's the device calculates the HMAC of its copies of the other device's
keys given in the message, as well as the HMAC of the keys given in the message, as well as the HMAC of the
comma-separated, sorted, list of key IDs in the message. The device comma-separated, sorted, list of key IDs in the message. The device
compares these with the HMAC values given in the message, and if compares these with the HMAC values given in the message, and if
everything matches then the device keys are verified. everything matches then the device keys are verified.
18. Alice and Bob's devices send `m.key.verification.done` messages to complete
the verification.
The wire protocol looks like the following between Alice and Bob's The wire protocol looks like the following between Alice and Bob's
devices: devices:

Write Preview
Loading…
Cancel
Save