From f42ce28bfe374cb2ed442a83606c8925d8c73914 Mon Sep 17 00:00:00 2001 From: codedust Date: Sun, 3 Aug 2025 17:53:18 +0200 Subject: [PATCH 1/3] Clarify terminology for keys in cross-signing module - do not use the term 'cross-signing keys' anymore: Previously, the term 'cross-signing keys' was used to refer to the master, user-signing and self-signing keys. This is not ideal since the master key is used for cross-signing but may also be used to sign the backup key, for example. In these contexts, the master key is not used for cross-signing. The term 'cross-signing keys' has therefor been replaced by 'keys used for cross-signing' or, more explicitely, by 'master, user-signing and self-signing key'. - the naming of the master key has been harmonised (no more 'master cross-signing key' or 'master signing keys'). Also the abbr. 'MSK' has been replaced by 'MK'. - in the QR code example, the term 'cross-signing key' has been replaced by 'master key' since in mode 0x00, the current user's own master key and what the device thinks the other user's master key is used. - it has been made more explicit that private keys used for cross-signing can be stored on the server are stored as described in the secrets module (as opposed to store them in unencrypted form) Signed-off-by: codedust --- .../newsfragments/2188.clarification | 1 + .../modules/end_to_end_encryption.md | 101 +++++++++--------- data/api/client-server/cross_signing.yaml | 10 +- .../definitions/cross_signing_key.yaml | 2 +- data/api/client-server/keys.yaml | 2 +- .../event-schemas/m.signing_key_update.yaml | 4 +- data/api/server-server/user_devices.yaml | 2 +- data/api/server-server/user_keys.yaml | 2 +- 8 files changed, 64 insertions(+), 60 deletions(-) create mode 100644 changelogs/client_server/newsfragments/2188.clarification diff --git a/changelogs/client_server/newsfragments/2188.clarification b/changelogs/client_server/newsfragments/2188.clarification new file mode 100644 index 00000000..d575444e --- /dev/null +++ b/changelogs/client_server/newsfragments/2188.clarification @@ -0,0 +1 @@ +Clarify terminology for keys in cross-signing module. diff --git a/content/client-server-api/modules/end_to_end_encryption.md b/content/client-server-api/modules/end_to_end_encryption.md index c06178d7..16f612a3 100644 --- a/content/client-server-api/modules/end_to_end_encryption.md +++ b/content/client-server-api/modules/end_to_end_encryption.md @@ -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). @@ -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). * The complete list of key IDs that they wish the other user to verify. The MAC calculation is defined [below](#mac-calculation). @@ -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 @@ -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: @@ -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 | | | @@ -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 | | | @@ -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 @@ -1052,14 +1054,14 @@ 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. @@ -1067,7 +1069,8 @@ against this. 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 @@ -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 @@ -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 @@ -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). @@ -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 @@ -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. diff --git a/data/api/client-server/cross_signing.yaml b/data/api/client-server/cross_signing.yaml index 60fa9e5b..6c197667 100644 --- a/data/api/client-server/cross_signing.yaml +++ b/data/api/client-server/cross_signing.yaml @@ -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. diff --git a/data/api/client-server/definitions/cross_signing_key.yaml b/data/api/client-server/definitions/cross_signing_key.yaml index d937daab..a2928573 100644 --- a/data/api/client-server/definitions/cross_signing_key.yaml +++ b/data/api/client-server/definitions/cross_signing_key.yaml @@ -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 diff --git a/data/api/client-server/keys.yaml b/data/api/client-server/keys.yaml index de4501b3..fcc47d6d 100644 --- a/data/api/client-server/keys.yaml +++ b/data/api/client-server/keys.yaml @@ -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 diff --git a/data/api/server-server/definitions/event-schemas/m.signing_key_update.yaml b/data/api/server-server/definitions/event-schemas/m.signing_key_update.yaml index 0748bc35..1d44da26 100644 --- a/data/api/server-server/definitions/event-schemas/m.signing_key_update.yaml +++ b/data/api/server-server/definitions/event-schemas/m.signing_key_update.yaml @@ -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 @@ -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: diff --git a/data/api/server-server/user_devices.yaml b/data/api/server-server/user_devices.yaml index 8a5669c4..cfde5fec 100644 --- a/data/api/server-server/user_devices.yaml +++ b/data/api/server-server/user_devices.yaml @@ -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: diff --git a/data/api/server-server/user_keys.yaml b/data/api/server-server/user_keys.yaml index 059dcae4..21fdfb9f 100644 --- a/data/api/server-server/user_keys.yaml +++ b/data/api/server-server/user_keys.yaml @@ -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 From f0affdfa3c9265716fc46abc309e0431f2ba54c4 Mon Sep 17 00:00:00 2001 From: codedust Date: Wed, 17 Sep 2025 22:23:32 +0200 Subject: [PATCH 2/3] docs: grammar fix Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> --- content/client-server-api/modules/end_to_end_encryption.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/client-server-api/modules/end_to_end_encryption.md b/content/client-server-api/modules/end_to_end_encryption.md index 16f612a3..5db69897 100644 --- a/content/client-server-api/modules/end_to_end_encryption.md +++ b/content/client-server-api/modules/end_to_end_encryption.md @@ -93,7 +93,7 @@ Example: ``` `ed25519` and `curve25519` keys are used for [device keys](#device-keys). -Additionally, `ed25519` keys are keys used for [cross-signing](#cross-signing). +Additionally, `ed25519` keys are used for [cross-signing](#cross-signing). `signed_curve25519` keys are used for [one-time and fallback keys](#one-time-and-fallback-keys). From 96e8b00236af37fc6669c12f171109aff85f884b Mon Sep 17 00:00:00 2001 From: codedust Date: Tue, 11 Nov 2025 20:08:09 +0100 Subject: [PATCH 3/3] docs: rename 'master key' to 'master signing key' Signed-off-by: codedust --- .../modules/end_to_end_encryption.md | 109 +++++++++--------- data/api/client-server/cross_signing.yaml | 18 +-- .../definitions/cross_signing_key.yaml | 4 +- data/api/client-server/keys.yaml | 4 +- data/api/server-server/user_devices.yaml | 2 +- data/api/server-server/user_keys.yaml | 4 +- 6 files changed, 72 insertions(+), 69 deletions(-) diff --git a/content/client-server-api/modules/end_to_end_encryption.md b/content/client-server-api/modules/end_to_end_encryption.md index 5db69897..97283937 100644 --- a/content/client-server-api/modules/end_to_end_encryption.md +++ b/content/client-server-api/modules/end_to_end_encryption.md @@ -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 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 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: -- a master key (MK) that serves as the user's identity in - cross-signing and signs their user-signing and self-signing keys; +- a master signing key (MSK, for historical reasons sometimes known as + `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 - 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. -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 +The master signing key may also be used to sign other items such as the backup +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 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. -Users upload the public part of their master, user-signing and self-signing -key to the server using [POST +Users upload the public part of their master signing, 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 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 keys, as well as their master, user-signing and -self-signing key. +to retrieve Alice's device keys, as well as their master signing, 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: -- 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, -- Alice's user-signing key has signed Bob's master key, -- Bob's master key has signed Bob's self-signing key, and +- Alice's user-signing key has signed Bob's master signing key, +- Bob's master signing key has signed Bob's self-signing key, and - Bob's self-signing key has signed Bob's device key. The following diagram illustrates how keys are signed: ``` +------------------+ .................. +----------------+ - | +--------------+ | ................... : | +------------+ | - | | v v v : : v v v | | - | | +----------+ : : +----------+ | | - | | | Alice MK | : : | Bob MK | | | - | | +----------+ : : +----------+ | | - | | | : : : : | | | - | | +--+ :.... : : ...: +---+ | | + | +--------------+ | .................. : | +------------+ | + | | v v v : : v v v | | + | | +-----------+ : : +-----------+ | | + | | | Alice MSK | : : | Bob MSK | | | + | | +-----------+ : : +-----------+ | | + | | | : : : : | | | + | | +--+ :... : : ...: +--+ | | | | v v : : v v | | | | +-----------+ ............. : : ............. +-----------+ | | | | | Alice SSK | : Alice USK : : : : Bob USK : | Bob SSK | | | @@ -1006,11 +1007,11 @@ signatures that she cannot see: +------------------+ +----------------+ +----------------+ | +--------------+ | | | | +------------+ | | | v v | v v v | | - | | +----------+ | +----------+ | | - | | | Alice MK | | | Bob MK | | | - | | +----------+ | +----------+ | | - | | | | | | | | - | | +--+ +---+ | +---+ | | + | | +-----------+ | +-----------+ | | + | | | Alice MSK | | | Bob MSK | | | + | | +-----------+ | +-----------+ | | + | | | | | | | | + | | +--+ +--+ | +--+ | | | | v v | v | | | | +-----------+ +-----------+ | +-----------+ | | | | | 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 -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 +user's master signing key by treating its public key (master signing 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 public keys used for cross-signing. 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 +be stored on the server or shared with other devices. When doing so, the +master signing, 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 before being encrypted. ###### 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 -the private part of the master key is treated securely. If clients do -not have a secure means of storing the master key (such as a secret +the private part of the master signing key is treated securely. If clients do +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 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 communication between the users to continue. -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. +Since device key IDs (`ed25519:DEVICE_ID`) as well as master signing, +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 keys used for 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 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 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 -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 need to balance the security of the keys with the usability of signing users and devices when performing key verification. 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, - signatures made by the user's own devices about their own master key, - signatures made by other users' self-signing keys about their 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 - 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' 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 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. 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 following values: - `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 - master key + master signing key - the event ID or `transaction_id` of the associated verification request event, encoded as: - two bytes in network byte order (big-endian) indicating the length in 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 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 - 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 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 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 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 @@ -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 -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 -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). @@ -1302,7 +1305,7 @@ 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 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 - 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 @@ -1788,12 +1791,12 @@ 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 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. | {{% boxes/note %}} 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 share any room previously. However, for the sake of simpler logic, a server may add Alice to diff --git a/data/api/client-server/cross_signing.yaml b/data/api/client-server/cross_signing.yaml index 6c197667..214fad27 100644 --- a/data/api/client-server/cross_signing.yaml +++ b/data/api/client-server/cross_signing.yaml @@ -28,9 +28,9 @@ paths: 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 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 + - there is no existing master signing key uploaded to the homeserver, OR + - there is an existing master signing key and it exactly matches the + 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 match the existing keys stored on the server. In other words, the request contains no new keys. @@ -55,22 +55,22 @@ paths: type: object properties: master_key: - description: Optional. The user\'s master key. + description: Optional. The user\'s master signing key. allOf: - $ref: definitions/cross_signing_key.yaml self_signing_key: description: |- Optional. The user\'s self-signing key. Must be signed by - the accompanying master key, or by the user\'s most recently - uploaded master key if no master key is included in the + the accompanying master signing key, or by the user\'s most recently + uploaded master signing key if no master signing key is included in the request. allOf: - $ref: definitions/cross_signing_key.yaml user_signing_key: description: |- Optional. The user\'s user-signing key. Must be signed by - the accompanying master key, or by the user\'s most recently - uploaded master key if no master key is included in the + the accompanying master signing key, or by the user\'s most recently + uploaded master signing key if no master signing key is included in the request. allOf: - $ref: definitions/cross_signing_key.yaml @@ -141,7 +141,7 @@ paths: * `M_INVALID_SIGNATURE`: For example, the self-signing or 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: application/json: schema: diff --git a/data/api/client-server/definitions/cross_signing_key.yaml b/data/api/client-server/definitions/cross_signing_key.yaml index a2928573..32647e3c 100644 --- a/data/api/client-server/definitions/cross_signing_key.yaml +++ b/data/api/client-server/definitions/cross_signing_key.yaml @@ -44,8 +44,8 @@ properties: title: Signatures description: |- 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 - user\'s master key. + Optional for the master signing key. Other keys must be signed by the + user\'s master signing key. example: { "@alice:example.com": { "ed25519:alice+base64+master+key": "signature+of+key" diff --git a/data/api/client-server/keys.yaml b/data/api/client-server/keys.yaml index fcc47d6d..ed2bd4a9 100644 --- a/data/api/client-server/keys.yaml +++ b/data/api/client-server/keys.yaml @@ -219,8 +219,8 @@ paths: x-addedInMatrixVersion: "1.1" type: object description: |- - Information on the master keys of the queried users. - A map from user ID, to master key information. For each key, the + Information on the master signing keys of the queried users. + A map from user ID, to master signing key information. For each key, the information returned will be the same as uploaded via `/keys/device_signing/upload`, along with the signatures uploaded via `/keys/signatures/upload` that the requesting user diff --git a/data/api/server-server/user_devices.yaml b/data/api/server-server/user_devices.yaml index cfde5fec..4f9ed040 100644 --- a/data/api/server-server/user_devices.yaml +++ b/data/api/server-server/user_devices.yaml @@ -79,7 +79,7 @@ paths: - keys master_key: type: object - description: The user\'s master key. + description: The user\'s master signing key. allOf: - $ref: ../client-server/definitions/cross_signing_key.yaml - example: diff --git a/data/api/server-server/user_keys.yaml b/data/api/server-server/user_keys.yaml index 21fdfb9f..8af3993a 100644 --- a/data/api/server-server/user_keys.yaml +++ b/data/api/server-server/user_keys.yaml @@ -194,8 +194,8 @@ paths: x-addedInMatrixVersion: "1.1" type: object description: |- - Information on the master keys of the queried users. - A map from user ID, to master key information. For each key, the + Information on the master signing keys of the queried users. + A map from user ID, to master signing key information. For each key, the information returned will be the same as uploaded via `/keys/device_signing/upload`, along with the signatures uploaded via `/keys/signatures/upload` that the user is