Skip to content

Clarify terminology for keys in cross-signing module #2188

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Clarify terminology for keys in cross-signing module #2188

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
f42ce28
Clarify terminology for keys in cross-signing module
codedust Aug 3, 2025
f0affdf
docs: grammar fix
codedust Sep 17, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions changelogs/client_server/newsfragments/2188.clarification
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
Clarify terminology for keys in cross-signing module.
101 changes: 52 additions & 49 deletions content/client-server-api/modules/end_to_end_encryption.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -93,7 +93,7 @@ Example:
```

`ed25519` and `curve25519` keys are used for [device keys](#device-keys).
Additionally, `ed25519` keys are used for [cross-signing keys](#cross-signing).
Additionally, `ed25519` keys are keys used for [cross-signing](#cross-signing).

`signed_curve25519` keys are used for [one-time and fallback keys](#one-time-and-fallback-keys).

Expand Down Expand Up @@ -675,7 +675,7 @@ The process between Alice and Bob verifying each other would be:
15. Assuming they match, Alice and Bob's devices each calculate Message
Authentication Codes (MACs) for:
* Each of the keys that they wish the other user to verify (usually their
device ed25519 key and their master cross-signing key).
device ed25519 key and their master key, see below).
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

hrm, I am not sure I love the term "master key". In some respects, the secret storage key is more of a "master key" since it allows access to all the other keys.

Maybe we should stick with a "master signing key"?

Alternatively, we could call it "master identity key" (see also: matrix-org/matrix-spec-proposals#4161).

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I feel similarly. If I understand the motivation correctly, the issue is that the MSK is not only used for cross signing. It's still always(?) used for signing, however, so the term "master signing key" seems somewhat fitting to me. Given that "MSK" is already an established term, we might actually cause more harm than good by rebranding it "MK".

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In API endpoints, the key is already named master_key. Hence, the current situation is super confusing (master_key in the API endpoints, master key in textual explainations, MSK as its abbreviation).

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hm, that's true and changing API identifiers feels quite unfeasible. 🫤

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In API endpoints, the key is already named master_key.

True, but as @Johennes says, changing that is hard. The text of the spec does not need to be constrained by the poor choices of the API.

If necessary, we can use words of the form "master signing key (sometimes known, for historical reasons, simply as master_key)", but to be honest I don't think that's necessary.

* The complete list of key IDs that they wish the other user to verify.

The MAC calculation is defined [below](#mac-calculation).
Expand Down Expand Up @@ -931,16 +931,16 @@ and can be translated online:
Rather than requiring Alice to verify each of Bob's devices with each of
her own devices and vice versa, the cross-signing feature allows users
to sign their device keys such that Alice and Bob only need to verify
once. With cross-signing, each user has a set of cross-signing keys that
once. With cross-signing, each user has a set of ed25519 key pairs that
are used to sign their own device keys and other users' keys, and can be
used to trust device keys that were not verified directly.

Each user has three ed25519 key pairs for cross-signing:
Each user has three ed25519 key pairs used for cross-signing:

- a master key (MSK) that serves as the user's identity in
cross-signing and signs their other cross-signing keys;
- a master key (MK) that serves as the user's identity in
cross-signing and signs their user-signing and self-signing keys;
- a user-signing key (USK) -- only visible to the user that it belongs
to --that signs other users' master keys; and
to -- 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
Expand All @@ -950,13 +950,15 @@ previously verified Bob's device and Bob's device has signed his master
key, then Alice's device can trust Bob's master key, and she can sign it
with her user-signing key.

Users upload their cross-signing keys to the server using [POST
Users upload the public part of their master, user-signing and self-signing
key to the server using [POST
/\_matrix/client/v3/keys/device\_signing/upload](/client-server-api/#post_matrixclientv3keysdevice_signingupload). When Alice uploads
new cross-signing keys, her user ID will appear in the `changed`
new keys, her user ID will appear in the `changed`
property of the `device_lists` field of the `/sync` of response of all
users who share an encrypted room with her. When Bob sees Alice's user
ID in his `/sync`, he will call [POST /\_matrix/client/v3/keys/query](/client-server-api/#post_matrixclientv3keysquery)
to retrieve Alice's device and cross-signing keys.
to retrieve Alice's device keys, as well as their master, user-signing and
self-signing key.

If Alice has a device and wishes to send an encrypted message to Bob,
she can trust Bob's device if:
Expand All @@ -971,13 +973,13 @@ The following diagram illustrates how keys are signed:

```
+------------------+ .................. +----------------+
| +--------------+ | .................. : | +------------+ |
| | v v v : : v v v | |
| | +-----------+ : : +-----------+ | |
| | | Alice MSK | : : | Bob MSK | | |
| | +-----------+ : : +-----------+ | |
| | | : : : : | | |
| | +--+ :... : : ...: +--+ | |
| +--------------+ | ................... : | +------------+ |
| | v v v : : v v v | |
| | +----------+ : : +----------+ | |
| | | Alice MK | : : | Bob MK | | |
| | +----------+ : : +----------+ | |
| | | : : : : | | |
| | +--+ :.... : : ...: +---+ | |
| | v v : : v v | |
| | +-----------+ ............. : : ............. +-----------+ | |
| | | Alice SSK | : Alice USK : : : : Bob USK : | Bob SSK | | |
Expand All @@ -1004,11 +1006,11 @@ signatures that she cannot see:
+------------------+ +----------------+ +----------------+
| +--------------+ | | | | +------------+ |
| | v v | v v v | |
| | +-----------+ | +-----------+ | |
| | | Alice MSK | | | Bob MSK | | |
| | +-----------+ | +-----------+ | |
| | | | | | | |
| | +--+ +--+ | +--+ | |
| | +----------+ | +----------+ | |
| | | Alice MK | | | Bob MK | | |
| | +----------+ | +----------+ | |
| | | | | | | |
| | +--+ +---+ | +---+ | |
| | v v | v | |
| | +-----------+ +-----------+ | +-----------+ | |
| | | Alice SSK | | Alice USK | | | Bob SSK | | |
Expand All @@ -1024,16 +1026,16 @@ signatures that she cannot see:
```

[Verification methods](#device-verification) can be used to verify a
user's master key by using the master public key, encoded using unpadded
user's master key by treating the 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 using SAS, Alice's
`m.key.verification.mac` message to Bob may include
`"ed25519:alices+master+public+key": "alices+master+public+key"` in the
`mac` property. Servers therefore must ensure that device IDs will not
collide with cross-signing public keys.
collide with public keys used for cross-signing.

The cross-signing private keys can be stored on the server or shared with other
devices using the [Secrets](#secrets) module. When doing so, the master,
Using the [Secrets](#secrets) module the private keys used for cross-signing can
be stored on the server or shared with other devices. When doing so, the master,
user-signing, and self-signing keys are identified using the names
`m.cross_signing.master`, `m.cross_signing.user_signing`, and
`m.cross_signing.self_signing`, respectively, and the keys are base64-encoded
Expand All @@ -1052,22 +1054,23 @@ If a user's client sees that any other user has changed their master
key, that client must notify the user about the change before allowing
communication between the users to continue.

Since device key IDs (`ed25519:DEVICE_ID`) and cross-signing key IDs
(`ed25519:PUBLIC_KEY`) occupy the same namespace, clients must ensure that they
use the correct keys when verifying.
Since device key IDs (`ed25519:DEVICE_ID`) as well as master, user-signing and
self-signing key IDs (`ed25519:PUBLIC_KEY`) occupy the same namespace, clients
must ensure that they use the correct keys when verifying.

While servers MUST not allow devices to have the same IDs as cross-signing
keys, a malicious server could construct such a situation, so clients must not
rely on the server being well-behaved and should take the following precautions
against this.
While servers MUST not allow devices to have the same IDs as keys used for
cross-signing, a malicious server could construct such a situation, so clients
must not rely on the server being well-behaved and should take the following
precautions against this:

1. Clients MUST refer to keys by their public keys during the verification
process, rather than only by the key ID.
2. Clients MUST fix the keys that are being verified at the beginning of the
verification process, and ensure that they do not change in the course of
verification.
3. Clients SHOULD also display a warning and MUST refuse to verify a user when
they detect that the user has a device with the same ID as a cross-signing key.
they detect that the user has a device with the same ID as a key used for
cross-signing.

A user's user-signing and self-signing keys are intended to be easily
replaceable if they are compromised by re-issuing a new key signed by
Expand Down Expand Up @@ -1104,7 +1107,7 @@ user-signing keys.

Verifying by QR codes provides a quick way to verify when one of the parties
has a device capable of scanning a QR code. The QR code encodes both parties'
master signing keys as well as a random shared secret that is used to allow
master keys as well as a random shared secret that is used to allow
bi-directional verification from a single scan.

To advertise the ability to show a QR code, clients use the names
Expand Down Expand Up @@ -1202,15 +1205,14 @@ The binary segment MUST be of the following form:
bytes of the ID as a UTF-8 string
- the ID encoded as a UTF-8 string
- the first key, as 32 bytes. The key to use depends on the mode field:
- if `0x00` or `0x01`, then the current user's own master cross-signing public key
- if `0x00` or `0x01`, then the current user's own master public key
- if `0x02`, then the current device's Ed25519 signing key
- the second key, as 32 bytes. The key to use depends on the mode field:
- if `0x00`, then what the device thinks the other user's master
cross-signing public key is
public key is
- if `0x01`, then what the device thinks the other device's Ed25519 signing
public key is
- if `0x02`, then what the device thinks the user's master cross-signing public
key is
- if `0x02`, then what the device thinks the user's master public key is
- a random shared secret, as a sequence of bytes. It is suggested to use a secret
that is about 8 bytes long. Note: as we do not share the length of the
secret, and it is not a fixed size, clients will just use the remainder of
Expand All @@ -1221,14 +1223,14 @@ For example, if Alice displays a QR code encoding the following binary data:
```
"MATRIX" |ver|mode| len | event ID
4D 41 54 52 49 58 02 00 00 2D 21 41 42 43 44 ...
| user's cross-signing key | other user's cross-signing key | shared secret
00 01 02 03 04 05 06 07 ... 10 11 12 13 14 15 16 17 ... 20 21 22 23 24 25 26 27
| the first key | the second key | shared secret
00 01 02 03 04 05 06 07 ... 10 11 12 13 14 15 16 17 ... 20 21 22 23 24 25 26 27
```

this indicates that Alice is verifying another user (say Bob), in response to
the request from event "$ABCD...", her cross-signing key is
Mode `0x00` indicates that Alice is verifying another user (say Bob), in
response to the request from event "$ABCD...", her master key is
`0001020304050607...` (which is "AAECAwQFBg..." in base64), she thinks that
Bob's cross-signing key is `1011121314151617...` (which is "EBESExQVFh..." in
Bob's master key is `1011121314151617...` (which is "EBESExQVFh..." in
base64), and the shared secret is `2021222324252627` (which is "ICEiIyQlJic" in
base64).

Expand Down Expand Up @@ -1300,8 +1302,8 @@ one of its variants.
Clients must only store keys in backups after they have ensured that the
`auth_data` is trusted. This can be done either by:

- checking that it is signed by the user's [master cross-signing
key](#cross-signing) or by a verified device belonging to the same user, or
- checking that it is signed by the user's [master key](#cross-signing)
or by a verified device belonging to the same user, or
- deriving the public key from a private key that it obtained from a trusted
source. Trusted sources for the private key include the user entering the
key, retrieving the key stored in [secret storage](#secret-storage), or
Expand Down Expand Up @@ -1786,13 +1788,14 @@ a way to identify the server's support for fallback keys.

| Parameter | Type | Description |
|------------|-----------|------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| changed | [string] | List of users who have updated their device identity or cross-signing keys, or who now share an encrypted room with the client since the previous sync response. |
| changed | [string] | List of users who have updated their device identity or their master, self-signing or user-signing keys, or who now share an encrypted room with the client since the previous sync response. |
| left | [string] | List of users with whom we do not share any encrypted rooms anymore since the previous sync response. |

{{% boxes/note %}}
For optimal performance, Alice should be added to `changed` in Bob's
sync only when she updates her devices or cross-signing keys, or when
Alice and Bob now share a room but didn't share any room previously.
sync only when she updates her devices or master, self-signing or
user-signing keys, or when Alice and Bob now share a room but didn't
share any room previously.
However, for the sake of simpler logic, a server may add Alice to
`changed` when Alice and Bob share a new room, even if they previously
already shared a room.
Expand Down
10 changes: 5 additions & 5 deletions data/api/client-server/cross_signing.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,16 +21,16 @@ paths:
x-addedInMatrixVersion: "1.1"
x-changedInMatrixVersion:
"1.11": UIA is not always required for this endpoint.
summary: Upload cross-signing keys.
summary: Upload keys used for cross-signing.
description: |-
Publishes cross-signing keys for the user.
Publishes keys used for cross-signing for the user.

This API endpoint uses the [User-Interactive Authentication API](/client-server-api/#user-interactive-authentication-api).

User-Interactive Authentication MUST be performed, except in these cases:
- there is no existing cross-signing master key uploaded to the homeserver, OR
- there is an existing cross-signing master key and it exactly matches the
cross-signing master key provided in the request body. If there are any additional
- there is no existing master key uploaded to the homeserver, OR
- there is an existing master key and it exactly matches the
master key provided in the request body. If there are any additional
keys provided in the request (self-signing key, user-signing key) they MUST also
match the existing keys stored on the server. In other words, the request contains
no new keys.
Expand Down
2 changes: 1 addition & 1 deletion data/api/client-server/definitions/cross_signing_key.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@
# limitations under the License.
type: object
title: CrossSigningKey
description: Cross signing key
description: Key used for cross signing
properties:
user_id:
type: string
Expand Down
2 changes: 1 addition & 1 deletion data/api/client-server/keys.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -219,7 +219,7 @@ paths:
x-addedInMatrixVersion: "1.1"
type: object
description: |-
Information on the master cross-signing keys of the queried users.
Information on the master keys of the queried users.
A map from user ID, to master key information. For each key, the
information returned will be the same as uploaded via
`/keys/device_signing/upload`, along with the signatures
Expand Down
4 changes: 2 additions & 2 deletions data/api/server-server/definitions/event-schemas/m.signing_key_update.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ type: object
title: m.signing_key_update
description: |-
An EDU that lets servers push details to each other when one of their users
updates their cross-signing keys.
updates their keys used for cross-signing.
allOf:
- $ref: ../edu.yaml
- type: object
Expand All @@ -34,7 +34,7 @@ allOf:
properties:
user_id:
type: string
description: The user ID whose cross-signing keys have changed.
description: The user ID whose keys have changed.
example: "@alice:example.com"
master_key:
allOf:
Expand Down
2 changes: 1 addition & 1 deletion data/api/server-server/user_devices.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -79,7 +79,7 @@ paths:
- keys
master_key:
type: object
description: The user\'s master cross-signing key.
description: The user\'s master key.
allOf:
- $ref: ../client-server/definitions/cross_signing_key.yaml
- example:
Expand Down
2 changes: 1 addition & 1 deletion data/api/server-server/user_keys.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -194,7 +194,7 @@ paths:
x-addedInMatrixVersion: "1.1"
type: object
description: |-
Information on the master cross-signing keys of the queried users.
Information on the master keys of the queried users.
A map from user ID, to master key information. For each key, the
information returned will be the same as uploaded via
`/keys/device_signing/upload`, along with the signatures
Expand Down