Wanted: documentation regarding user-relevant cryptographic mechanisms

Nobody has claimed this yet.

Apologies if this is the wrong repository or platform for the following request.

I am looking for a good documentation of Matrix' concept regarding cryptography. It does not need cover algorithms but abstract mechanisms and pitfalls for daily users.

There are a bunch of icons displayed along contacts as well as individual messages in element-web and element-android. I can think of the green-shield-with-white-checkmark, the grey-shield and some icon(s) with an exclamation mark. Each of those icons seems to represent one or possibly multiple abstract states, and I would like to know what these states are. **I assume that the concept which includes the set of states is not specific to an individual client or server implementation, but emerges from the matrix specification**.

There are multiple possibilities what a state incorporates:

- It is a unary predicate of a contact.
- It is a binary predicate of your account and a contact.
- It is a binary predicate of your account and a specific message.
- It is a binary predicate of your account and a specific room.
- It is a ternary predicate of your account, a contact and a time.
- Anything of the above plus a specific client device.
- Whatever else.

There also seems to be a (partial?) transition graph between those states. The most prominent transition would be the verification process between two devices (either between the same or different accounts). What is this transition graph? Does it have sinks one cannot get out of? Are there transitions where a user could lose access to chats and uploaded attachments?

As an example for the last question, I primarily use element-android and sometimes log into element-web anew (i.e. without previous cookies, local browser store etc), so that I have to cross-verify the element-web session with my element-android. After that, it sometimes happens that I still cannot see some messages and have to re-query the encryption keys. I assume they are queried, from my element-android device. What if I decided to log-out from element-android after my verification of element-web? Would I have lost access to messages?

The issue does not identify a file, test, or entry point. Start by reviewing the Matrix specification's encryption and device-verification material, then define documentation that explains the user-visible states, their transitions, and whether losing a device can prevent access to messages or attachments.

Written by the indexing model from the issue text.