From 7f83355ce7a4d46c8a60627a2093df9d5e81d6c0 Mon Sep 17 00:00:00 2001 From: "James E. Blair" Date: Thu, 8 Jul 2021 16:18:02 -0700 Subject: [PATCH] Split optional matrix howto steps into new docs So that the "How to matrix" doc isn't so large, split the optional add-on steps into separate documents. Change-Id: I1ef1c8c0280dccda12fe0fd9c6498d202f769ab5 --- doc/source/howtos/matrix-encryption.rst | 32 +++++++ doc/source/howtos/matrix-id.rst | 76 ++++++++++++++++ doc/source/howtos/matrix.rst | 116 ++---------------------- 3 files changed, 118 insertions(+), 106 deletions(-) create mode 100644 doc/source/howtos/matrix-encryption.rst create mode 100644 doc/source/howtos/matrix-id.rst diff --git a/doc/source/howtos/matrix-encryption.rst b/doc/source/howtos/matrix-encryption.rst new file mode 100644 index 0000000000..10a895b0ab --- /dev/null +++ b/doc/source/howtos/matrix-encryption.rst @@ -0,0 +1,32 @@ +Optional: Save Encryption Keys +============================== + +The Matrix protocol supports end-to-end encryption. We don't have +this enabled for the ``#zuul`` room (there's little point as it's a +public room), but if you start direct chats with other Matrix users, +your communication will be encrypted by default. Since it's +*end-to-end* encryption, that means your encryption keys are stored on +your client, and the server has no way to decrypt those messages. But +that also means that if you sign out of your client or switch +browsers, you will lose your encryption keys along with access to any +old messages that were encrypted with them. To avoid this, you can +back up your keys to the server (in an encrypted form, of course) so +that if you log in from another session, you can restore those keys +and pick up where you left off. To set this up, open the User Menu by +clicking on your name at the top left of the screen. + +.. image:: /images/matrix/user-menu.png + :align: center + +Click the `Security & privacy` menu item in the dropdown. + +.. image:: /images/matrix/user-menu-dropdown.png + :align: center + +Click the `Set up` button under `Encryption` / `Secure Backup` in the +dialog that pops up. + +.. image:: /images/matrix/user-encryption.png + :align: center + +Follow the prompts to back up your encryption keys. diff --git a/doc/source/howtos/matrix-id.rst b/doc/source/howtos/matrix-id.rst new file mode 100644 index 0000000000..44203d83ef --- /dev/null +++ b/doc/source/howtos/matrix-id.rst @@ -0,0 +1,76 @@ +Optional: Register with an Identity Provider +============================================ + +By default, there is no public link between your Matrix account and +any identifying information such as your email address. However, you +may wish people to be able to find your Matrix ID by looking up your +email address or phone number. We also have plans to add additional +functionality to our bots if they are able to look up contributors by +email addresses. If you wish to make your account discoverable in +this way, you may perform the following steps to list your account in +one of the public third-party identifier services. Note that these +services are designed to only return results for someone who already +knows your email address or phone number; they take care to ensure +that it is not possible (or nearly so) to "scrape" their data sets to +obtain lists of users. + +To get started, open the User Menu and click `All settings`. Under +the `General` section, find `Email addresses`. If you followed the +instructions above, you should already have an email address listed +here. If you don't, enter your address, click `Add`, and follow the +instructions to verify your address. The dialog should look like this +when complete: + +.. image:: /images/matrix/id-email-complete.png + :align: center + +To make your account discoverable by email, scroll down to the +`Discovery` section. + +.. image:: /images/matrix/id-disc.png + :align: center + +Read the privacy notice and click the checkbox +next to `Accept`. That will enable the `Continue` button; click that +to proceed. + +.. image:: /images/matrix/id-disc-accept.png + :align: center + +The `Discovery` section will be replaced with the email address you +registered above. + +.. image:: /images/matrix/id-disc-accept.png + :align: center + +Click the `Share` button next to the address. The system will send an +email to you, and meanwhile the dialog will show this: + +.. image:: /images/matrix/id-disc-verify-wait.png + :align: center + +You will receive an email like this: + +.. image:: /images/matrix/id-disc-verify-email.png + :align: center + +Follow the link in the email to verify it really is you making the +request. + +.. image:: /images/matrix/id-disc-verify-success.png + :align: center + +Then return to the settings page and click the `Complete` button. + +.. image:: /images/matrix/id-disc-verify-wait.png + :align: center + +Once everything is finished, the complete button should change to read +`Revoke`. + +.. image:: /images/matrix/id-disc-verify-complete.png + :align: center + +If you see that, you're all done. If you change your mind and don't +want your account to be discoverable via email, you can click the +`Revoke` button at any time. diff --git a/doc/source/howtos/matrix.rst b/doc/source/howtos/matrix.rst index 16afae1620..1444662227 100644 --- a/doc/source/howtos/matrix.rst +++ b/doc/source/howtos/matrix.rst @@ -134,112 +134,16 @@ join. Because Matrix keeps a message history, we'll see your message and you'll see any responses, even if you close your browser and log in later. -Optional: Save Encryption Keys ------------------------------- +Optional Next Steps +------------------- -The Matrix protocol supports end-to-end encryption. We don't have -this enabled for the ``#zuul`` room (there's little point as it's a -public room), but if you start direct chats with other Matrix users, -your communication will be encrypted by default. Since it's -*end-to-end* encryption, that means your encryption keys are stored on -your client, and the server has no way to decrypt those messages. But -that also means that if you sign out of your client or switch -browsers, you will lose your encryption keys along with access to any -old messages that were encrypted with them. To avoid this, you can -back up your keys to the server (in an encrypted form, of course) so -that if you log in from another session, you can restore those keys -and pick up where you left off. To set this up, open the User Menu by -clicking on your name at the top left of the screen. +The following steps are optional. You don't need to do these just to +hop in with a quick question, but if you plan on spending more than a +brief amount of time interacting with communities in Matrix, they will +improve your experience. -.. image:: /images/matrix/user-menu.png - :align: center +.. toctree:: + :maxdepth: 1 -Click the `Security & privacy` menu item in the dropdown. - -.. image:: /images/matrix/user-menu-dropdown.png - :align: center - -Click the `Set up` button under `Encryption` / `Secure Backup` in the -dialog that pops up. - -.. image:: /images/matrix/user-encryption.png - :align: center - -Follow the prompts to back up your encryption keys. - -Optional: Register with an Identity Provider --------------------------------------------- - -By default, there is no public link between your Matrix account and -any identifying information such as your email address. However, you -may wish people to be able to find your Matrix ID by looking up your -email address or phone number. We also have plans to add additional -functionality to our bots if they are able to look up contributors by -email addresses. If you wish to make your account discoverable in -this way, you may perform the following steps to list your account in -one of the public third-party identifier services. Note that these -services are designed to only return results for someone who already -knows your email address or phone number; they take care to ensure -that it is not possible (or nearly so) to "scrape" their data sets to -obtain lists of users. - -To get started, open the User Menu and click `All settings`. Under -the `General` section, find `Email addresses`. If you followed the -instructions above, you should already have an email address listed -here. If you don't, enter your address, click `Add`, and follow the -instructions to verify your address. The dialog should look like this -when complete: - -.. image:: /images/matrix/id-email-complete.png - :align: center - -To make your account discoverable by email, scroll down to the -`Discovery` section. - -.. image:: /images/matrix/id-disc.png - :align: center - -Read the privacy notice and click the checkbox -next to `Accept`. That will enable the `Continue` button; click that -to proceed. - -.. image:: /images/matrix/id-disc-accept.png - :align: center - -The `Discovery` section will be replaced with the email address you -registered above. - -.. image:: /images/matrix/id-disc-accept.png - :align: center - -Click the `Share` button next to the address. The system will send an -email to you, and meanwhile the dialog will show this: - -.. image:: /images/matrix/id-disc-verify-wait.png - :align: center - -You will receive an email like this: - -.. image:: /images/matrix/id-disc-verify-email.png - :align: center - -Follow the link in the email to verify it really is you making the -request. - -.. image:: /images/matrix/id-disc-verify-success.png - :align: center - -Then return to the settings page and click the `Complete` button. - -.. image:: /images/matrix/id-disc-verify-wait.png - :align: center - -Once everything is finished, the complete button should change to read -`Revoke`. - -.. image:: /images/matrix/id-disc-verify-complete.png - :align: center - -If you see that, you're all done. If you change your mind and don't -want your account to be discoverable via email, you can click the -`Revoke` button at any time. + matrix-encryption + matrix-id