Security terminology

[ManDay]

I would like to break this down into smaller bugs, but I'm afraid I can't because I have not at all understood what is what myself. I'm only fairly confident that the amount of different terms exceeds the number of actual concepts used here, so this needs a cleanup. I am at a complete loss as to what this cleanup would look like.

The following summarizes the non-selfexplanatory (even for someone familiar with assymetric encryption, but much less so for an average user) terms that are mentioned on the Security & Privacy dialog alone.

• Session ID
• Verify User
• Verify Session
• Secure Backup
• Encryption Keys
• Recovery Key
• Backup key
• Secret Storage
• Security Passphase
• Backup
• Signature
• Cross-signing
• Cross-signing Key
• Master (Private) Key
• Self-signing (Private) Key
• User-signing (Private) Key
• Session Key
• Security Key

Particularly confusing is the mention of the three "private-only" keys and the remark that something called a "Backup Key" has been stored in "Secret Storage" (which perhaps could be the "Secure Backup").

I hope, if you are a developer, you can appreciate just how confusing this is for anyone who was not involved in designing it. I have mentioned a couple of terms which are clear to me (e.g. "Session ID"), but I think the gist of it should be that the terms are given names of concepts which can be understood without detailled, technical insight. I would speculate that it boils down to approximately (where KP = Key pair), at least that's what I could make sense of:

• Per-Session-KP / Per-Device-KP
• Account KP (a.k.a. "Cross-Signing Key")
• Backup Key

[jryans]

Thanks for this comprehensive list! Yes, we're aware there are many moving parts and concepts. To be honest, it can be hard for anyone to follow, even those who implemented these features. 😅

Nearly all of these things do actually exist as independent things (they aren't synonyms), and it would also be quite challenging to explain many of them in a non-technical way... Anyway, I agree that some amount of documentation is definitely needed.

[jryans]

Related to #1870

[ManDay]

Although I'm certainly unqualified, I will make an attempt at an explanation. Hopefully, you can point out what I should correct, so that other users can take it as a preliminary explanation until you have written a real reference document. After all, a wrong documentation is better than no documentation! (irony intended)

I take the liberty to phrase this in terms of expressions which I think describe the respective concepts well and are commonly heard, while pointing out "non-normative" synonyms in parentheses.

Security and Encryption

As a user of Matrix/Element, you are required to keep around two tokens of security:

• The Account Password (login password), which is the password you choose during your registration
• The Account Key (recovery key, security key; backup key), which you will set -- that is either choose, generate automatically, or generate from a human readable phassphrase (security passphrase) -- upon first login

and your client keeps another one for you, the Session Key.

NB: You may ask "why two?" at this point as, indeed, the Account Key alone could probably be used for authenticating you much like your Account Password (using an public key encryption scheme). The answer to this question is simply that it's by design, which will give you an additional layer of security and the option to separate the two tokens (physically).

Your Account Password is used to establish a connection to your Homeserver HS. Although your HS does not know your Account Password, you will be giving it to the HS in plain text. By now, you have established rudimentary function of Matrix, that is you are "sufficiently" authenticated (establish your identity, proven to be you) towards your HS for it to allow you to send and receive events in your joined rooms.

NB: But that's about it. You are still lacking a large part of functionality. Notably, you are not yet equipped to operate with encrypted events in encrypted rooms and you have not yet "sufficiently authenticated" towards other users (verification), either.

Since you have established the basic functionality by authenticating to the HS, your HS will provide you with your Secret Storage which has been encrypted with your second token of security, your Account Key, such that only you and not your HS can access its contents.
You can choose to do none, either, or both of the following and your client will rely on data in the Secret Storage to achieve it:

• Authenticate to others (session verification), who, by design, do not trust you to be you, as, for example, the HS could be impersonating you at this point
• Crypt on encrypted rooms, meaning you decrypt events which you receive and encrypt events to send to others

To Crypt on encrypted rooms, you will require the Room Encryption Key (encryption key) of the respective room which symmetrically encrypts and decrypt all events in the room. There are three possibilities how you can obtain that key:

• If you are creating the room, then your client will automatically generate a key and put it into the Secret Storage
• You can retrieve it from the Secret Storage on your HS
• You can receive it from another person in the room who knows it (TODO: How does this happen?)
  and put it into the Secret Storage

Authentication to others is performed for one of many Sessions that each user has, not per user like it was done towards the HS. Typically, each client creates a random Session ID for itself which can also be assigned human readable names like "Computer" or "Phone". Everyone authenticated as you towards the HS can create arbitrary sessions for your user at will and other users will decide to either trust or not trust each Session ID.

NB: There are other constraints in the Matrix protocol which render the following statement inaccurate, but as far as security is concerned, distinguishing between multiple sessions is not a logical necessity, but only gives you finer control over authentication. That is to say, you could theoretically use a single Session ID across many devices and only ever show up as one to others.

Authentication to others works in two steps. First, your client must sign your events to prove that they do indeed come from someone who is allowed to claim a Session ID. Signing a datum shows that you have access to the Private Session Key, originally only known to who created the Session and its associated Public Session Key (session key).

Next, your session must be authorized to represent you (session verification). There are multiple ways how this can be done

1. You grant authorization in person via an authentic channel, for example by speaking to the person and asserting "Session MJBCFNKVWX with public key …, yes that's really me!"
2. You authorize it by validating a random token exchange such as a list of Emoji, which is more convenient than spelling out the Session by ID
3. You certify the Session ID by your account and authorize your account to represent you (user verification)

The certificate which you issue to certify a Session ID is generated and signed with keys (Master Key, Cross-Signing Key Pair) which are generated initially for your account and are kept in the Secret Storage. Authorization of your account then, has to be done similarly, but only by either bullet 1 or 2.

(TODO: How are session authorizations revoked?)

Last, there might be users in encrypted rooms who have chosen to send their events in those rooms only to participants whom they did authenticate. In which case, you must not only be able to decrypt those messages but also use an authenticated session in order to read them.

In all other cases, authentication to others will remain merely an informational input to them: They will see a green 🛡️ next to those events issued by authorized sessions and a red 🛡️ next to others, in encrypted rooms.

NB: Both, the option to send only to authenticated users and the colored shields, exist only for encrypted rooms by design, as it would unreasonable, although logically possible, for unencrypted rooms.

[domoritz]

I found this screen particularly confusing. I think a "Security Phrase" and a "recovery passphrase" are the same but I am honestly not sure. It would be good to use the same wording.

[domoritz]

Related issue: #1474 and an incoming improvement matrix-org/matrix-react-sdk#5533.

[aaronraimist]

Ugh matrix-org/matrix-react-sdk#5807 is a step backwards IMO.

"Use another login" sounds like you just login with your username and password again or you are logging in with some external credentials or something. "Login" does not sound to me like pick up your other device/session. Plus they are still called "Sessions" elsewhere in the interface.

[SimonBrandner]

Something like Use another session/device to verify might be better (see this)

[aaronraimist]

"Verify with another session" is what they switched away from in that PR. Not perfect but I think that was much more clear than "Use another login".

Personally I liked when they were called devices but since everything in the interface has switched to calling them sessions I would vote to keep everything using the word session. The terminology can't keep changing. It makes the users confused every time it does.