Filip/matrix-spec
1
0
Fork 0
mirror of https://github.com/matrix-org/matrix-spec synced 2026-03-26 13:04:10 +01:00
Code Issues Actions 1 Packages Projects Releases Wiki Activity

docs: rename 'master key' to 'master signing key'

Browse source 
Signed-off-by: codedust <codedust@so.urceco.de>
This commit is contained in:
codedust 2025-11-11 20:08:09 +01:00
parent f0affdfa3c
commit 96e8b00236
6 changed files with 72 additions and 69 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

109
content/client-server-api/modules/end_to_end_encryption.md
View file

@ -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 15. Assuming they match, Alice and Bob's devices each calculate Message
Authentication Codes (MACs) for: Authentication Codes (MACs) for:
* Each of the keys that they wish the other user to verify (usually their * Each of the keys that they wish the other user to verify (usually their
device ed25519 key and their master key, see below). device ed25519 key and their master signing key, see below).
* The complete list of key IDs that they wish the other user to verify. * The complete list of key IDs that they wish the other user to verify.
The MAC calculation is defined [below](#mac-calculation). The MAC calculation is defined [below](#mac-calculation).
@ -937,49 +937,50 @@ used to trust device keys that were not verified directly.
Each user has three ed25519 key pairs used for cross-signing: Each user has three ed25519 key pairs used for cross-signing:
- a master key (MK) that serves as the user's identity in - a master signing key (MSK, for historical reasons sometimes known as
cross-signing and signs their user-signing and self-signing keys; `master_key`) 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 - 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 signing keys; and
- a self-signing key (SSK) that signs the user's own device keys. - 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 The master signing 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 key. The master signing key may also be signed by the user's own device keys to
aid in migrating from device verifications: if Alice's device had aid in migrating from device verifications: if Alice's device had
previously verified Bob's device and Bob's device has signed his master 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 key, then Alice's device can trust Bob's master signing key, and she can sign it
with her user-signing key. with her user-signing key.
Users upload the public part of their master, user-signing and self-signing Users upload the public part of their master signing, user-signing and
key to the server using [POST self-signing key to the server using [POST
/\_matrix/client/v3/keys/device\_signing/upload](/client-server-api/#post_matrixclientv3keysdevice_signingupload). When Alice uploads /\_matrix/client/v3/keys/device\_signing/upload](/client-server-api/#post_matrixclientv3keysdevice_signingupload). When Alice uploads
new 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 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 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) ID in his `/sync`, he will call [POST /\_matrix/client/v3/keys/query](/client-server-api/#post_matrixclientv3keysquery)
to retrieve Alice's device keys, as well as their master, user-signing and to retrieve Alice's device keys, as well as their master signing, user-signing
self-signing key. and self-signing key.
If Alice has a device and wishes to send an encrypted message to Bob, If Alice has a device and wishes to send an encrypted message to Bob,
she can trust Bob's device if: she can trust Bob's device if:
- Alice's device is using a master key that has signed her - Alice's device is using a master signing key that has signed her
user-signing key, user-signing key,
- Alice's user-signing key has signed Bob's master key, - Alice's user-signing key has signed Bob's master signing key,
- Bob's master key has signed Bob's self-signing key, and - Bob's master signing 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: The following diagram illustrates how keys are signed:
``` ```
+------------------+ .................. +----------------+ +------------------+ .................. +----------------+
| +--------------+ | ................... : | +------------+ | | +--------------+ | .................. : | +------------+ |
| | v v v : : v v v | | | | v v v : : v v v | |
| | +----------+ : : +----------+ | | | | +-----------+ : : +-----------+ | |
| | | Alice MK | : : | Bob MK | | | | | | Alice MSK | : : | Bob MSK | | |
| | +----------+ : : +----------+ | | | | +-----------+ : : +-----------+ | |
| | | : : : : | | | | | | : : : : | | |
| | +--+ :.... : : ...: +---+ | | | | +--+ :... : : ...: +--+ | |
| | v v : : v v | | | | v v : : v v | |
| | +-----------+ ............. : : ............. +-----------+ | | | | +-----------+ ............. : : ............. +-----------+ | |
| | | Alice SSK | : Alice USK : : : : Bob USK : | Bob SSK | | | | | | Alice SSK | : Alice USK : : : : Bob USK : | Bob SSK | | |
@ -1006,11 +1007,11 @@ signatures that she cannot see:
+------------------+ +----------------+ +----------------+ +------------------+ +----------------+ +----------------+
| +--------------+ | | | | +------------+ | | +--------------+ | | | | +------------+ |
| | v v | v v v | | | | v v | v v v | |
| | +----------+ | +----------+ | | | | +-----------+ | +-----------+ | |
| | | Alice MK | | | Bob MK | | | | | | Alice MSK | | | Bob MSK | | |
| | +----------+ | +----------+ | | | | +-----------+ | +-----------+ | |
| | | | | | | | | | | | | | | |
| | +--+ +---+ | +---+ | | | | +--+ +--+ | +--+ | |
| | v v | v | | | | v v | v | |
| | +-----------+ +-----------+ | +-----------+ | | | | +-----------+ +-----------+ | +-----------+ | |
| | | Alice SSK | | Alice USK | | | Bob SSK | | | | | | Alice SSK | | Alice USK | | | Bob SSK | | |
@ -1026,27 +1027,28 @@ signatures that she cannot see:
``` ```
[Verification methods](#device-verification) can be used to verify a [Verification methods](#device-verification) can be used to verify a
user's master key by treating the master public key, encoded using unpadded user's master signing key by treating its public key (master signing public
base64, as the device ID, and treating it as a normal device. For key), encoded using unpadded base64, as the device ID, and treating it as a
example, if Alice and Bob verify each other using SAS, Alice's normal device. For example, if Alice and Bob verify each other using SAS,
Alice's
`m.key.verification.mac` message to Bob may include `m.key.verification.mac` message to Bob may include
`"ed25519:alices+master+public+key": "alices+master+public+key"` in the `"ed25519:alices+master+public+key": "alices+master+public+key"` in the
`mac` property. Servers therefore must ensure that device IDs will not `mac` property. Servers therefore must ensure that device IDs will not
collide with public keys used for cross-signing. collide with public keys used for cross-signing.
Using the [Secrets](#secrets) module the private keys used for cross-signing can 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, be stored on the server or shared with other devices. When doing so, the
user-signing, and self-signing keys are identified using the names master signing, user-signing, and self-signing keys are identified using the
`m.cross_signing.master`, `m.cross_signing.user_signing`, and names `m.cross_signing.master`, `m.cross_signing.user_signing`, and
`m.cross_signing.self_signing`, respectively, and the keys are base64-encoded `m.cross_signing.self_signing`, respectively, and the keys are base64-encoded
before being encrypted. before being encrypted.
###### Key and signature security ###### Key and signature security
A user's master key could allow an attacker to impersonate that user to A user's master signing key could allow an attacker to impersonate that user to
other users, or other users to that user. Thus clients must ensure that other users, or other users to that user. Thus clients must ensure that
the private part of the master key is treated securely. If clients do the private part of the master signing key is treated securely. If clients do
not have a secure means of storing the master key (such as a secret not have a secure means of storing the master signing key (such as a secret
storage system provided by the operating system), then clients must not storage system provided by the operating system), then clients must not
store the private part. store the private part.
@ -1054,9 +1056,9 @@ 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 key, that client must notify the user about the change before allowing
communication between the users to continue. communication between the users to continue.
Since device key IDs (`ed25519:DEVICE_ID`) as well as master, user-signing and Since device key IDs (`ed25519:DEVICE_ID`) as well as master signing,
self-signing key IDs (`ed25519:PUBLIC_KEY`) occupy the same namespace, clients user-signing and self-signing key IDs (`ed25519:PUBLIC_KEY`) occupy the same
must ensure that they use the correct keys when verifying. namespace, clients must ensure that they use the correct keys when verifying.
While servers MUST not allow devices to have the same IDs as keys used for 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 cross-signing, a malicious server could construct such a situation, so clients
@ -1074,27 +1076,27 @@ precautions against this:
A user's user-signing and self-signing keys are intended to be easily 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 replaceable if they are compromised by re-issuing a new key signed by
the user's master key and possibly by re-verifying devices or users. the user's master signing key and possibly by re-verifying devices or users.
However, doing so relies on the user being able to notice when their However, doing so relies on the user being able to notice when their
keys have been compromised, and it involves extra work for the user, and keys have been compromised, and it involves extra work for the user, and
so although clients do not have to treat the private parts as so although clients do not have to treat the private parts as
sensitively as the master key, clients should still make efforts to sensitively as the master signing key, clients should still make efforts to
store the private part securely, or not store it at all. Clients will store the private part securely, or not store it at all. Clients will
need to balance the security of the keys with the usability of signing need to balance the security of the keys with the usability of signing
users and devices when performing key verification. users and devices when performing key verification.
To avoid leaking of social graphs, servers will only allow users to see: To avoid leaking of social graphs, servers will only allow users to see:
- signatures made by the user's own master, self-signing or - signatures made by the user's own master signing, self-signing or
user-signing keys, user-signing keys,
- signatures made by the user's own devices about their own master - signatures made by the user's own devices about their own master
key, key,
- signatures made by other users' self-signing keys about their - signatures made by other users' self-signing keys about their
respective devices, respective devices,
- signatures made by other users' master keys about their respective - signatures made by other users' master signing keys about their respective
self-signing key, or self-signing key, or
- signatures made by other users' devices about their respective - signatures made by other users' devices about their respective
master keys. master signing keys.
Users will not be able to see signatures made by other users' Users will not be able to see signatures made by other users'
user-signing keys. user-signing keys.
@ -1107,7 +1109,7 @@ user-signing keys.
Verifying by QR codes provides a quick way to verify when one of the parties 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' has a device capable of scanning a QR code. The QR code encodes both parties'
master keys as well as a random shared secret that is used to allow master signing keys as well as a random shared secret that is used to allow
bi-directional verification from a single scan. bi-directional verification from a single scan.
To advertise the ability to show a QR code, clients use the names To advertise the ability to show a QR code, clients use the names
@ -1196,23 +1198,24 @@ The binary segment MUST be of the following form:
- one byte indicating the QR code verification mode. Should be one of the - one byte indicating the QR code verification mode. Should be one of the
following values: following values:
- `0x00` verifying another user with cross-signing - `0x00` verifying another user with cross-signing
- `0x01` self-verifying in which the current device does trust the master key - `0x01` self-verifying in which the current device does trust the master signing key
- `0x02` self-verifying in which the current device does not yet trust the - `0x02` self-verifying in which the current device does not yet trust the
master key master signing key
- the event ID or `transaction_id` of the associated verification - the event ID or `transaction_id` of the associated verification
request event, encoded as: request event, encoded as:
- two bytes in network byte order (big-endian) indicating the length in - two bytes in network byte order (big-endian) indicating the length in
bytes of the ID as a UTF-8 string bytes of the ID as a UTF-8 string
- the ID encoded 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: - 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 public key - if `0x00` or `0x01`, then the current user's own master signing public key
- if `0x02`, then the current device's Ed25519 signing 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: - 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 - if `0x00`, then what the device thinks the other user's master
public key is public key is
- if `0x01`, then what the device thinks the other device's Ed25519 signing - if `0x01`, then what the device thinks the other device's Ed25519 signing
public key is public key is
- if `0x02`, then what the device thinks the user's master public key is - if `0x02`, then what the device thinks the user's master signing public key
is
- a random shared secret, as a sequence of bytes. It is suggested to use a secret - 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 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 secret, and it is not a fixed size, clients will just use the remainder of
@ -1228,9 +1231,9 @@ For example, if Alice displays a QR code encoding the following binary data:
``` ```
Mode `0x00` indicates that Alice is verifying another user (say Bob), in Mode `0x00` indicates that Alice is verifying another user (say Bob), in
response to the request from event "$ABCD...", her master key is response to the request from event "$ABCD...", her master signing key is
`0001020304050607...` (which is "AAECAwQFBg..." in base64), she thinks that `0001020304050607...` (which is "AAECAwQFBg..." in base64), she thinks that
Bob's master key is `1011121314151617...` (which is "EBESExQVFh..." in Bob's master signing key is `1011121314151617...` (which is "EBESExQVFh..." in
base64), and the shared secret is `2021222324252627` (which is "ICEiIyQlJic" in base64), and the shared secret is `2021222324252627` (which is "ICEiIyQlJic" in
base64). base64).
@ -1302,7 +1305,7 @@ one of its variants.
Clients must only store keys in backups after they have ensured that the Clients must only store keys in backups after they have ensured that the
`auth_data` is trusted. This can be done either by: `auth_data` is trusted. This can be done either by:
- checking that it is signed by the user's [master key](#cross-signing) - checking that it is signed by the user's [master signing key](#cross-signing)
or by a verified device belonging to the same user, or 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 - 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 source. Trusted sources for the private key include the user entering the
@ -1788,12 +1791,12 @@ a way to identify the server's support for fallback keys.
| Parameter | Type | Description | | Parameter | Type | Description |
|------------|-----------|------------------------------------------------------------------------------------------------------------------------------------------------------------------| |------------|-----------|------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| 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. | | changed | [string] | List of users who have updated their device identity or their master signing, 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. | | left | [string] | List of users with whom we do not share any encrypted rooms anymore since the previous sync response. |
{{% boxes/note %}} {{% boxes/note %}}
For optimal performance, Alice should be added to `changed` in Bob's For optimal performance, Alice should be added to `changed` in Bob's
sync only when she updates her devices or master, self-signing or sync only when she updates her devices or master signing, self-signing or
user-signing keys, or when Alice and Bob now share a room but didn't user-signing keys, or when Alice and Bob now share a room but didn't
share any room previously. share any room previously.
However, for the sake of simpler logic, a server may add Alice to However, for the sake of simpler logic, a server may add Alice to

18
data/api/client-server/cross_signing.yaml
View file

@ -28,9 +28,9 @@ paths:
This API endpoint uses the [User-Interactive Authentication API](/client-server-api/#user-interactive-authentication-api). 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: User-Interactive Authentication MUST be performed, except in these cases:
- there is no existing master key uploaded to the homeserver, OR - there is no existing master signing key uploaded to the homeserver, OR
- there is an existing master key and it exactly matches the - there is an existing master signing key and it exactly matches the
master key provided in the request body. If there are any additional master signing 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 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 match the existing keys stored on the server. In other words, the request contains
no new keys. no new keys.
@ -55,22 +55,22 @@ paths:
type: object type: object
properties: properties:
master_key: master_key:
description: Optional. The user\'s master key. description: Optional. The user\'s master signing key.
allOf: allOf:
- $ref: definitions/cross_signing_key.yaml - $ref: definitions/cross_signing_key.yaml
self_signing_key: self_signing_key:
description: |- description: |-
Optional. The user\'s self-signing key. Must be signed by Optional. The user\'s self-signing key. Must be signed by
the accompanying master key, or by the user\'s most recently the accompanying master signing key, or by the user\'s most recently
uploaded master key if no master key is included in the uploaded master signing key if no master signing key is included in the
request. request.
allOf: allOf:
- $ref: definitions/cross_signing_key.yaml - $ref: definitions/cross_signing_key.yaml
user_signing_key: user_signing_key:
description: |- description: |-
Optional. The user\'s user-signing key. Must be signed by Optional. The user\'s user-signing key. Must be signed by
the accompanying master key, or by the user\'s most recently the accompanying master signing key, or by the user\'s most recently
uploaded master key if no master key is included in the uploaded master signing key if no master signing key is included in the
request. request.
allOf: allOf:
- $ref: definitions/cross_signing_key.yaml - $ref: definitions/cross_signing_key.yaml
@ -141,7 +141,7 @@ paths:
* `M_INVALID_SIGNATURE`: For example, the self-signing or * `M_INVALID_SIGNATURE`: For example, the self-signing or
user-signing key had an incorrect signature. user-signing key had an incorrect signature.
* `M_MISSING_PARAM`: No master key is available. * `M_MISSING_PARAM`: No master signing key is available.
content: content:
application/json: application/json:
schema: schema:

4
data/api/client-server/definitions/cross_signing_key.yaml
View file

@ -44,8 +44,8 @@ properties:
title: Signatures title: Signatures
description: |- description: |-
Signatures of the key, calculated using the process described at [Signing JSON](/appendices/#signing-json). Signatures of the key, calculated using the process described at [Signing JSON](/appendices/#signing-json).
Optional for the master key. Other keys must be signed by the Optional for the master signing key. Other keys must be signed by the
user\'s master key. user\'s master signing key.
example: { example: {
"@alice:example.com": { "@alice:example.com": {
"ed25519:alice+base64+master+key": "signature+of+key" "ed25519:alice+base64+master+key": "signature+of+key"

4
data/api/client-server/keys.yaml
View file

@ -219,8 +219,8 @@ paths:
x-addedInMatrixVersion: "1.1" x-addedInMatrixVersion: "1.1"
type: object type: object
description: |- description: |-
Information on the master keys of the queried users. Information on the master signing keys of the queried users.
A map from user ID, to master key information. For each key, the A map from user ID, to master signing key information. For each key, the
information returned will be the same as uploaded via information returned will be the same as uploaded via
`/keys/device_signing/upload`, along with the signatures `/keys/device_signing/upload`, along with the signatures
uploaded via `/keys/signatures/upload` that the requesting user uploaded via `/keys/signatures/upload` that the requesting user

2
data/api/server-server/user_devices.yaml
View file

@ -79,7 +79,7 @@ paths:
- keys - keys
master_key: master_key:
type: object type: object
description: The user\'s master key. description: The user\'s master signing key.
allOf: allOf:
- $ref: ../client-server/definitions/cross_signing_key.yaml - $ref: ../client-server/definitions/cross_signing_key.yaml
- example: - example:

4
data/api/server-server/user_keys.yaml
View file

@ -194,8 +194,8 @@ paths:
x-addedInMatrixVersion: "1.1" x-addedInMatrixVersion: "1.1"
type: object type: object
description: |- description: |-
Information on the master keys of the queried users. Information on the master signing keys of the queried users.
A map from user ID, to master key information. For each key, the A map from user ID, to master signing key information. For each key, the
information returned will be the same as uploaded via information returned will be the same as uploaded via
`/keys/device_signing/upload`, along with the signatures `/keys/device_signing/upload`, along with the signatures
uploaded via `/keys/signatures/upload` that the user is uploaded via `/keys/signatures/upload` that the user is