Apply suggestions from code review

Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>
pull/977/head
Hubert Chathi 4 years ago committed by GitHub
parent efebba62de
commit 902444ceb5
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23

@ -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:

@ -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

Loading…
Cancel
Save