# Introduction to the Matrix ### Other Languages To translate large sections of text use e.g. deepl.com. - [Zur Deutschen Version (German version)]( https://pad.kanthaus.online/s/Matrix-Einfuehrung#). # Introduction to the Matrix [Link to the German version]( https://pad.kanthaus.online/s/Matrix-Introduction#) ## Glossary * **matrix.org**: The organization coordinating the project and providing the largest home server, similar to how Gmail dominates email traffic. Having an account on matrix.org is not necessary and not recommended. * **Matrix**: The protocol you use to communicate. Similar to email. * **Homeserver**: Your Matrix server. Similar to your email provider. * **Matrix ID**: Your unique address that can be used to find you. `@username:homeserver.topleveldomain`. Similar to your email address. * **[Top-Level-Domain (tld)](https://icannwiki.org/Top-Level_Domain)**: The last part of a domain, e.g. `.com, .org, .de, .chat, .im` * **Client**: An app to read Matrix messages. I recommend installing a client on your cell phone or PC. But there are also clients that you can use from the browser. * **Session**: Every time you log in, you create a new session. (e.g. browser + mobile phone + laptop) * **Element**: One of many Matrix clients. Element is available on almost all operating systems and is the most advanced client. Comparable to Thunderbird for email. * **Room**: What is called channel or group in other messengers is a room in Matrix. * **Space**: A folder for rooms. Rooms can be set so that everyone in the space can see and join them. You may know this from Slack, RocketChat, Mattermost, Discord, etc. :::success If you don't understand terms, try leo.org, dict.cc or wikipedia.org. ::: ## Why Matrix? Matrix is a **decentralized**, *federated* communication protocol. In principle, it is like e-mail, only more modern and with many more possibilities. * **Decentralized**: Everyone can run their own server. So there is no central organization that controls all servers. * *Federated*: The servers can communicate with each other. People don't have to have accounts on the same server to be able to communicate with each other. **Strong against censorship:** The decentralized structure is particularly advantageous when services are being blocked by governments in states of "emergency". - [01/2022 in Kazakhstan](https://www.tagesschau.de/ausland/asien/kazakhstan-ausnahmestaat-proteste-gaspreise-101.html) - [10/2022 in Iran](https://www.deutschlandfunkkultur.de/internetsperre-in-iran-100.html) ### What can Matrix do? Matrix offers opportunities to bundle your communication on one platform and thereby optimize your cooperation. - **private end-to-end encrypted rooms** - **Public rooms** (unencrypted, can be activated later) - **Text, Links, Images, Videos, Voice Messages, Polls** - **Formatting** with [Markdown](https://www.markdownguide.org/getting-started/) (Like this guide) => [Tutorial](https://www.markdowntutorial.com/), [ Cheat sheet](https://www.markdownguide.org/cheat-sheet) - **Encrypted voice and video conferences** - **Spaces** as folders for rooms, so you can create working groups - **Include other programs, messengers and websites** such as Pads, Telegram, Signal, blog feeds or email newsletters. ### What can Matrix not (yet) do? - Disguise **metadata** (times, communication partners...). - **Disappearing messages** that delete themselves - **Send large files** > 100MB **Alternatives:** | Obfuscate metadata | Disappearing News | Send large files| | -------- | -------- | -------- | | cwtch.im | signal.org | kiki.lecomitedeschats.com | | jami.net | bin.disroot.org | upload.disroot.org | | [simplex.chat](https://simplex.chat) | paste.systemli.org | onionshare.org | | briarproject.org | pb.envs.net | file.io | ### Data protection notice ::: warning Although the end-to-end encryption prevents those monitoring you from reading your messages (given they have no access to a logged in device), it is still possible to monitor which account communicated with whom and when ([**see metadata**](https://wiki.systemli.org/howto/matrix/privacy)). You can spoof your IP address by using a [VPN](https://riseup.net/en/vpn) or [Tor](https://0xacab.org/about.privacy/messengers-on-tails-os/-/wikis/HowTo), then your metadata will allow fewer conclusions on your real life identity. With some servers ([e.g. Systemli](https://wiki.systemli.org/howto/matrix/privacy), [Hackliberty](https://hackliberty.org/register)) this is not as necessary because your IP address is not being logged at all. ::: :::info **Example Room** *All Cats Are Beautiful*: @Alice:matrix.org -- @Bob:systemli.org -- @Carol:systemfall.org => The chat history is saved on all three servers (encrypted), as well as on Alice's, Bob's and Carol's devices that are logged in (encrypted, along with the keys). This is why your devices are the best point of attack for reading your messages. ::: # Join the Matrix ### Summary of above :::success Matrix is like **email in modern**. A good tool to use to replace unencrypted **email lists** or **telegram groups** as it offers more **security**. It's also **easier** to create a Matrix room than an email list, there are **no phone numbers** and **no smartphone** needed, and you have **free server choice**. Whenever you don't trust people enough to give them your phone number, Matrix is a good option. => **[In Germany, security officials ask every second who owns a phone number!](https://netzpolitik.org/2023/bestandsdatenauskunft-2022-behoerden-fragen-sekuendlich-wem-eine-telefonnummer-gehoert/)** ::: :::danger For **critical things** I would recommend **Signal** or [other alternatives](#What-can-Matrix-not-yet-do) because it is difficult to impossible to **completely delete chats** from Matrix - see [Privacy Notice](##Data-protection-notice). ::: ## 1. Select a server In order to register, you have to choose one of over 40,000 "home servers" (see [Glossary](#Glossary)). This is comparable to your email provider. **Recommendations:** * chat.livingutopia.org/#/register * https://systemfallout.org/account-request (messages will be [deleted after 1 year](https://hilfe.systemfallout.org/matrix/fristen/)) * https://hackliberty.org/register * https://registration.matrix.catgirl.cloud/ * https://users.systemli.org/en/register (You need an invite code) * [host your own server](https://matrix.org/blog/2020/04/06/running-your-own-secure-communication-service-with-matrix-and-jitsi) **An email address must be provided:** * element.envs.net/#/register * https://element.together.now/#/register * https://element.matrix.im/#/register ## 2. Set up encryption :::info Matrix's encryption system is based on **Cross-Signing**. That means every time you log in, you have to **verify** that you're actually you with a different device or a password. Only then you have **access** to former encrypted **messages**. This is similar to PGP encryption, but easier to use. ::: :::success To ensure that encryption always works in all **sessions** (see [Glossary](#GlossaryTerminology)), i recommend setting up a **password-encrypted backup** on your home server. ::: **1. Click: Profile Picture > Settings > Security > Secure Backup**  **2. Save all:** Copy the displayed key and the entered password and save them in a password manager - recommendation: [KeepassXC](https://keepassxc.org/), [KeepassDX (Android)](https://www.keepassdx.com/) , [Keepassium (iOS)](https://keepassium.com/). :::warning **If you lose** this you can no longer **read** old encrypted messages because your keys are missing! Also, others can see that you have **not verified** you and may not **trust** you anymore. Further down below under [Encryption](#Encryption) you can find out what you can do in such a case to save your account. ::: ## 3. Install a client :::warning **Clients** (see [Glossary](#Glossary)), just like e-mail clients, are developed independently of the chat protocol and therefore do not all support the same features. ::: **Recommendations** * **[Element:](https://element.io/get-started)** Recommendation if you switch to Matrix with your group and want to use all features. No multi-user support. => has a [good user guide](https://element.io/user-guide) :::info I recommend trying Element at first to get an overview of what is possible. Other clients are more privacy friendly but don't have [integrations](#integrations). ::: **Alternatives** * **[FluffyChat:](https://fluffychat.im/)** Recommended if you mainly want to chat with your friends and/or use multiple accounts at the same time. The User Interface reminds me of Signal. * **[Cinny:](https://cinny.in/)** Recommended if you want a client that looks like Slack, RocketChat or Mattermost. Available for desktop only. No voice calls. :::warning [List of other clients](https://matrix.org/clients) & [Feature overview](https://matrix.org/clients-matrix). Choose wisely, the safety of your communication partners and your options depend on it. ::: ## 4. Get in touch **By Matrix ID:** Now you can share your Matrix ID (see [Glossary](#Glossary)) and wait until you are invited. `@username:homeserver.tld` **By invitation link (matrix.to):** Your personal invitation link is https://matrix.to/#/ followed by your Matrix ID: `https://matrix.to/#/@username:homeserver.tld` # Features :::success You managed? Congratulations! 🎉 If you after you still have problems reading, or you want **help** for your group - whether **setting up** [Bridges](#Bridges) or more complex [Spaces](#Spaces), feel free to send me an email 🤗 Also feedback , suggestions for changes and translations by mail to helpmewithmatrix@riseup.net ([PGP-Key](https://bin.disroot.org/?2e8de48c508807c5#DZNVVTbfL3rjv9ne86vNozuLejauCAFaUqAPi4VkfEG6)) - continue with a short **introduction** :arrow_down: ::: ## Rooms :::info All chats, no matter how public - no matter if channel or group, are **rooms** in Matrix. All rooms can be used either encrypted or unencrypted. Encryption is enabled **by default** for **Private** Rooms and Direct Messages. For **public** rooms you can enable encryption **afterwards** - but keep in mind that the chat history will not be visible when people join. ::: ### Private rooms **Direct messages (so called in some clients):** These are chats between two accounts - they can be expanded to include more accounts at any time, and then they automatically become private rooms. **Private Rooms:** The default when you create a room. Everyone has to be invited manually, you can set a **room name and theme** and make many settings. ### Public spaces **"Space Rooms"** :::info These spaces are visible to everyone in a [Space](#Spaces). This works for both public and formerly private spaces. First you have to **add** the rooms to a space, you do that via the respective space menu. Then you set the **room access** to "visible for the space" in each room via the settings. It is **easier** to create the space **first** and then to create such rooms directly in the space. ::: **Hidden rooms with invite link:** :::success These rooms only have an unreadable invitation link, the `!raum-id` acts like a **password**: `https://matrix.to/#/!raum-id:homeserver.domain` You create such a room by creating a **private** room and **thereafter** changing it to public. This also has the advantage that it is then **encrypted** and thus resembles a private Telegram group. You will receive the invitation link if you go to the share symbol in the top right corner of the room description (element/smartphone). **Note:** This room is also available to everyone in Spaces! ::: **Local public spaces:** :::warning These rooms have a human-readable alias as an invitation link that makes them visible via the room directory on your own home server, where they can be found: `https://matrix.to/#/#roomname:homeserver.domain` The room can be entered from other home servers if people know the **exact** link. In this case, the `#roomname` acts as a (usually weak) password. **Note:** Creating a room like this means that it is easily accessible to **all** people on the server. A room can be configured like this on **multiple** servers. For this you need accounts on each of the servers. ::: **Global (really fully public):** :::danger These rooms have an alias published in the matrix.org **public room directory**. There the room can be viewed from **all** home servers and can be found via **search engines** (also in the browser). You create such a room by ticking the box "Publish in the room directory". ::: **Channels (only certain people can broadcast):** To do this, set the permission to send messages to "Admin" in the settings under **Room Permissions**, and promote everyone who should be allowed to send. :::danger Channels in Matrix have a key **privacy flaw**: **everyone** can see who **reads what** when and **who's in the channel**, and there's no way to post anonymously except with an extra account registered for this purpose. I would recommend **Telegram** instead, possibly with [Bridge](#Bridges) into a hidden public space in your space. ::: ## spaces ::: success Spaces can be used to better organize rooms. Everyone in the space can see all rooms that are accessible and can enter and exit freely - like in a **house**. Spaces can thus depict a **community** or a **group**, in which all the people who belong to exchange and **organize** in **working groups** or **thematic** rooms are . ::: **Personal Space:** Optimized for you. Only you can see them. **Private Space:** Optimized for groups. Everyone must be invited. **Public Spaces:** Optimized for communities. There is an invite link. :::info **Tip:** When starting out with Spaces, simply create a private one, add a main room inside, and then let it grow organically as needed. ::: **Fun Fact** anyone? Spaces are a Also just a modification of [rooms](#rooms) 🤦‍ It follows that almost everything that applies to rooms also applies to spaces :) So I've kept this short - here are [some more info](https://element.io/blog/spaces-blast-out-of-beta/). ### Explore rooms in Space :::success **Element on mobile:** Click on the space menu (Three tiles + circle bottom right), then long on the space and then on "Explore (and manage) spaces" => the # symbol with the magnifying glass. **Elenent on the laptop:** Right-click on the space on the far left, then on "Explore and manage rooms" => the # symbol with the magnifying glass. ::: ## Encryption :::success **End-to-end encryption** ensures that messages can only be read by those for whom they are intended. This assumes that the **keys** are only available on the end devices. So far so good. As soon as several end devices (**sessions**) come into play, things get tricky, because then keys have to be transferred from one device to the other. A **key backup** will help you with that. ::: **To set up and understand (with screenshots):** * https://samuels-blog.de/sichere-chats-mit-matrix-matrix-teil-2/#cross-signing * https://doc.matrix.tu-dresden.de/encryption/ * https://matrix-help.envs.net/first-steps/#convenient_use_of_end-to-end_encryption_e2ee :::danger **Help!** I lost the key backup password and my phone broke, now I can't get my messages and everyone thinks I've been hacked - because of course I don't have the [password manager](# 2-encryption-setup) used! 😖 ::: **Steps to verify you:** 1. **Click on:** profile picture > Settings > Security > Sessions (you may need to search) 2. Log out of your old sessions by entering your login password. 3. Set up the [Key Backup](#2-encryption-setup) again (see instructions above). ## Voice and video calls :::success Matrix supports encrypted **voice calls** and **video conferences via [Jitsi](https://jitsi.org/)**. It is possible to hold entire **plena including call and [Pad](#Widgets)** via matrix. ➡️ [**Instructions**](https://wiki.systemli.org/howto/matrix/jitsi) ::: ## Integrations :::warning An integration manager is required for integrations. Your home server usually comes with an integration manager, which is called `scalar.vector.im` (evil) at matrix.org. If you're on another server, it's usually called `dimension.homeserver.tld` (Good). Here you can find [more information about what **meta data** is generated on the server when you use integrations](https://element.io/integration-manager-privacy-notice). ::: ### Widgets :::success A widget is a **slice** of an app that is displayed in another program. You may know this from the start screen of your cell phone. For example, in Element you can add a **Pad** to a room and store your **Logs** there. It works well with [**Etherpad**](https://pad.systemli.org) (unencrypted) and [**CryptPad**](cryptpad.fr) (encrypted). ➡️ To the [**Cryptpad introduction**](https://pad.kanthaus.online/s/CryptPad#). ::: ### How do I use widgets? **1. Enable: Avatar > Settings > General > "Manage Integrations"** **2. Laptop (element):** In rooms at the top right, the small ℹ️ > Manage widgets. **2. Mobile phone (element):** Click on the cube in the upper right corner of the room. **3. Add custom widget** and paste link of your pad. :::danger If you use widgets, the URL of the embedded website is **not end-to-end encrypted**. With e.g. Croodle surveys or **cryptpads** the password for the encryption is sent **in the link**, which means sharing the password with the **admins of all participating home servers** in a room. In CryptPad you can set an **additional password**. This makes sense in this case! ::: :::info The website that is embedded as a widget can see your **IP address**. But that would also be the case if you simply call up the website in the browser 🤷. ::: ## bots :::success Bots are programs that can **send messages** within a Matrix room. You can e.g. ** integrate into a room. ::: * https://t2bot.io/ * https://hilfe.systemfallout.org/matrix/features/ (only for systemfallout.org accounts) * https://matrix.org/bots/ :::danger It makes sense to do this in an **extra room** for **privacy** reasons, because bots read your messages & transmit them to the server (even encrypted ones). ::: ## Bridges :::success Bridges to other communication **protocols** allow a Matrix room to communicate with groups and channels on Telegram, Signal, Mattermost and **many more platforms** can be nicated, mostly in **both directions**. ::: * https://hilfe.systemfallout.org/matrix/telegram/ (only for systemfallout.org) * https://hilfe.systemfallout.org/matrix/signal/ (only for systemfallout.org) * https://gitlab.com/etke.cc/postmoogle * [rent a server (incl. bridges)](https://etke.cc/) * https://matrix.org/bridges/ :::danger **Disappearing messages** on Telegram or Signal are now **obsolete** because they are distributed on Matrix servers! ::: ## Other resources/links * Introduction: https://matrix.org/faq/#intro * Matrix wikis: * https://doc.matrix.tu-dresden.de/ * https://matrix-help.envs.net/ * https://element.io/help