Skip to content

Commit 67edc3e

Browse files
uhoreguhoreg
committed
add clarifications and diagrams
1 parent f97b394 commit 67edc3e

File tree

2 files changed

+74
-10
lines changed

2 files changed

+74
-10
lines changed

‎api/client-server/cross_signing.yaml‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -136,6 +136,11 @@ paths:
136136
The signatures to be published.
137137
schema:
138138
type: object
139+
title: Signatures
140+
additionalProperties:
141+
type: object
142+
additionalProperties:
143+
type: object
139144
example: {
140145
"@alice:example.com": {
141146
"HIJKLMN": {

‎specification/modules/end_to_end_encryption.rst‎

Lines changed: 69 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -739,19 +739,20 @@ common set of translations for all languages.
739739
Cross-signing
740740
~~~~~~~~~~~~~
741741

742-
Rather than requiring Alice to verify each of Bob's devices will each of her
743-
own devices and vice versa, Matrix allows users to cross-sign their keys so
744-
that Alice and Bob only need to verify once. With cross-signing, each user has
745-
a set of cross-signing keys that are used to sign their own device keys and
746-
other users' keys, and can be used to trust device keys that were not verified
747-
directly.
742+
Rather than requiring Alice to verify each of Bob's devices with each of her
743+
own devices and vice versa, the cross-signing feature allows users sign their
744+
device keys such that Alice and Bob only need to verify once. With
745+
cross-signing, each user has a set of cross-signing keys that are used to sign
746+
their own device keys and other users' keys, and can be used to trust device
747+
keys that were not verified directly.
748748

749-
With cross-signing, each user has three cross-signing ed25519 keys pairs:
749+
Each user has three ed25519 keys pairs for cross-signing:
750750

751-
* a master key that serves as the user's identity in cross-signing and signs
751+
* a master key (MSK) that serves as the user's identity in cross-signing and signs
752752
their other cross-signing keys;
753-
* a user-signing key that signs other users' master keys, and
754-
* a self-signing key that signs the user's own device keys.
753+
* a user-signing key (USK) -- only visible to the user that it belongs to --
754+
that signs other users' master keys, and
755+
* a self-signing key (SSK) that signs the user's own device keys.
755756

756757
The master key may also be used to sign other items such as the backup key. The
757758
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:
775776
- Bob's master key has signed Bob's self-signing key, and
776777
- Bob's self-signing key has signed Bob's device key.
777778

779+
The following diagram illustrates how keys are signed:
780+
781+
.. code::
782+
783+
+------------------+ .................. +----------------+
784+
| +--------------+ | .................. : | +------------+ |
785+
| | v v v : : v v v | |
786+
| | +-----------+ : : +-----------+ | |
787+
| | | Alice MSK | : : | Bob MSK | | |
788+
| | +-----------+ : : +-----------+ | |
789+
| | | : : : : | | |
790+
| | +--+ :... : : ...: +--+ | |
791+
| | v v : : v v | |
792+
| | +-----------+ ............. : : ............. +-----------+ | |
793+
| | | Alice SSK | : Alice USK : : : : Bob USK : | Bob SSK | | |
794+
| | +-----------+ :...........: : : :...........: +-----------+ | |
795+
| | | ... | : : : : | ... | | |
796+
| | V V :........: :........: V V | |
797+
| | +---------+ -+ +---------+ -+ | |
798+
| | | Devices | ...| | Devices | ...| | |
799+
| | +---------+ -+ +---------+ -+ | |
800+
| | | ... | | ... | | |
801+
| +------+ | | +----+ |
802+
+----------------+ +--------------+
803+
804+
.. based on https://jcg.re/blog/quick-overview-matrix-cross-signing/
805+
806+
In the diagram, boxes represent keys and lines represent signatures with the
807+
arrows pointing from the signing key to the key being signed. Dotted boxes and
808+
lines represent keys and signatures that are only visible to the user who
809+
created them.
810+
811+
The following diagram illustrates Alice's view, hiding the keys and signatures
812+
that she cannot see:
813+
814+
.. code::
815+
816+
+------------------+ +----------------+ +----------------+
817+
| +--------------+ | | | | +------------+ |
818+
| | v v | v v v | |
819+
| | +-----------+ | +-----------+ | |
820+
| | | Alice MSK | | | Bob MSK | | |
821+
| | +-----------+ | +-----------+ | |
822+
| | | | | | | |
823+
| | +--+ +--+ | +--+ | |
824+
| | v v | v | |
825+
| | +-----------+ +-----------+ | +-----------+ | |
826+
| | | Alice SSK | | Alice USK | | | Bob SSK | | |
827+
| | +-----------+ +-----------+ | +-----------+ | |
828+
| | | ... | | | | ... | | |
829+
| | V V +--------+ V V | |
830+
| | +---------+ -+ +---------+ -+ | |
831+
| | | Devices | ...| | Devices | ...| | |
832+
| | +---------+ -+ +---------+ -+ | |
833+
| | | ... | | ... | | |
834+
| +------+ | | +----+ |
835+
+----------------+ +--------------+
836+
778837
Verification methods can be used to verify a user's master key by using the
779838
master public key, encoded using unpadded base64, as the device ID, and
780839
treating it as a normal device. For example, if Alice and Bob verify each other

0 commit comments

Comments
 (0)