Clarify terminology for keys in cross-signing module #2188
Conversation
- 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 <[email protected]>
codedust
force-pushed
the
clarify-keys-used-for-cross-signing
branch
from
1c78feb to
f42ce28
Compare
| 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). |
There was a problem hiding this comment.
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).
There was a problem hiding this comment.
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".
There was a problem hiding this comment.
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).
There was a problem hiding this comment.
Hm, that's true and changing API identifiers feels quite unfeasible. 🫤
There was a problem hiding this comment.
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.
Co-authored-by: Richard van der Hoff <[email protected]>
4 participants
Pull Request Checklist
Preview: https://pr2188--matrix-spec-previews.netlify.app