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

add clarifications and diagrams

Browse Source
pull/977/head
Hubert Chathi 5 years ago
parent f97b394591
commit 67edc3e229
2 changed files with 74 additions and 10 deletions
Show Stats Download Patch File Download Diff File

5
api/client-server/cross_signing.yaml
Unescape Escape View File

@ -136,6 +136,11 @@ paths:
The signatures to be published. The signatures to be published.
schema: schema:
type: object type: object
title: Signatures
additionalProperties:
type: object
additionalProperties:
type: object
example: { example: {
"@alice:example.com": { "@alice:example.com": {
"HIJKLMN": { "HIJKLMN": {

79
specification/modules/end_to_end_encryption.rst
Unescape Escape View File

@ -739,19 +739,20 @@ common set of translations for all languages.
Cross-signing Cross-signing
~~~~~~~~~~~~~ ~~~~~~~~~~~~~
Rather than requiring Alice to verify each of Bob's devices will each of her Rather than requiring Alice to verify each of Bob's devices with each of her
own devices and vice versa, Matrix allows users to cross-sign their keys so own devices and vice versa, the cross-signing feature allows users sign their
that Alice and Bob only need to verify once. With cross-signing, each user has device keys such that Alice and Bob only need to verify once. With
a set of cross-signing keys that are used to sign their own device keys and cross-signing, each user has a set of cross-signing keys that are used to sign
other users' keys, and can be used to trust device keys that were not verified their own device keys and other users' keys, and can be used to trust device
directly. keys that were not verified directly.
With cross-signing, each user has three cross-signing ed25519 keys pairs: Each user has three ed25519 keys pairs for cross-signing:
* a master key that serves as the user's identity in cross-signing and signs * a master key (MSK) that serves as the user's identity in cross-signing and signs
their other cross-signing keys; their other cross-signing keys;
* a user-signing key that signs other users' master keys, and * a user-signing key (USK) -- only visible to the user that it belongs to --
* a self-signing key that signs the user's own device keys. that signs other users' master keys, and
* a self-signing key (SSK) that signs the user's own device keys.
The master key may also be used to sign other items such as the backup key. The The master key may also be used to sign other items such as the backup key. The
master key may also be signed by the user's own device keys to aid in migrating master key may also be signed by the user's own device keys to aid in migrating
@ -775,6 +776,64 @@ trust Bob's device if:
- Bob's master key has signed Bob's self-signing key, and - Bob's master key has signed Bob's self-signing key, and
- Bob's self-signing key has signed Bob's device key. - Bob's self-signing key has signed Bob's device key.
The following diagram illustrates how keys are signed:
.. code::
+------------------+ .................. +----------------+
| +--------------+ | .................. : | +------------+ |
| | v v v : : v v v | |
| | +-----------+ : : +-----------+ | |
| | | Alice MSK | : : | Bob MSK | | |
| | +-----------+ : : +-----------+ | |
| | | : : : : | | |
| | +--+ :... : : ...: +--+ | |
| | v v : : v v | |
| | +-----------+ ............. : : ............. +-----------+ | |
| | | Alice SSK | : Alice USK : : : : Bob USK : | Bob SSK | | |
| | +-----------+ :...........: : : :...........: +-----------+ | |
| | | ... | : : : : | ... | | |
| | V V :........: :........: V V | |
| | +---------+ -+ +---------+ -+ | |
| | | Devices | ...| | Devices | ...| | |
| | +---------+ -+ +---------+ -+ | |
| | | ... | | ... | | |
| +------+ | | +----+ |
+----------------+ +--------------+
.. based on https://jcg.re/blog/quick-overview-matrix-cross-signing/
In the diagram, boxes represent keys and lines represent signatures with the
arrows pointing from the signing key to the key being signed. Dotted boxes and
lines represent keys and signatures that are only visible to the user who
created them.
The following diagram illustrates Alice's view, hiding the keys and signatures
that she cannot see:
.. code::
+------------------+ +----------------+ +----------------+
| +--------------+ | | | | +------------+ |
| | v v | v v v | |
| | +-----------+ | +-----------+ | |
| | | Alice MSK | | | Bob MSK | | |
| | +-----------+ | +-----------+ | |
| | | | | | | |
| | +--+ +--+ | +--+ | |
| | v v | v | |
| | +-----------+ +-----------+ | +-----------+ | |
| | | Alice SSK | | Alice USK | | | Bob SSK | | |
| | +-----------+ +-----------+ | +-----------+ | |
| | | ... | | | | ... | | |
| | V V +--------+ V V | |
| | +---------+ -+ +---------+ -+ | |
| | | Devices | ...| | Devices | ...| | |
| | +---------+ -+ +---------+ -+ | |
| | | ... | | ... | | |
| +------+ | | +----+ |
+----------------+ +--------------+
Verification methods can be used to verify a user's master key by using the Verification methods can be used to verify a user's master key by using the
master public key, encoded using unpadded base64, as the device ID, and master public key, encoded using unpadded base64, as the device ID, and
treating it as a normal device. For example, if Alice and Bob verify each other treating it as a normal device. For example, if Alice and Bob verify each other

Write Preview
Loading…
Cancel
Save