diff --git a/api/client-server/cross_signing.yaml b/api/client-server/cross_signing.yaml index 655456b4..219e4b3e 100644 --- a/api/client-server/cross_signing.yaml +++ b/api/client-server/cross_signing.yaml @@ -52,16 +52,16 @@ paths: - $ref: definitions/cross_signing_key.yaml self_signing_key: description: |- - Optional. The user\'s self-signing key. Must be signed with - the accompanied master, or by the user\'s most recently + 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 request. allOf: - $ref: definitions/cross_signing_key.yaml user_signing_key: description: |- - Optional. The user\'s user-signing key. Must be signed with - the accompanied master, or by the user\'s most recently + 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 request. allOf: diff --git a/specification/modules/end_to_end_encryption.rst b/specification/modules/end_to_end_encryption.rst index acd05411..28e85159 100644 --- a/specification/modules/end_to_end_encryption.rst +++ b/specification/modules/end_to_end_encryption.rst @@ -754,18 +754,18 @@ Cross-signing ~~~~~~~~~~~~~ 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 sign their +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 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 keys pairs for cross-signing: +Each user has three ed25519 key pairs 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 user-signing key (USK) -- only visible to the user that it belongs to -- - that signs other users' master keys, and + 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 @@ -863,9 +863,11 @@ A user's master 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 storage system provided by -the operating system), then clients must not store the private part. If a user -changes their master key, clients of users that they communicate with must -notify their users about the change. +the operating system), then clients must not store the private part. + +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. 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