Add advanced docs, and other docs changes

docs/source/advanced.rst

@@ -6,14 +6,55 @@ Advanced Usage
 Save Tabs
 ---------
 
+By default, everything in OnionShare is temporary. As soon as you close an OnionShare tab its address no longer exists and can't be used again. But sometimes you might want an OnionShare service to be persistent. For example, this would be useful if you want to host a website that can keep the same URL even if you reboot your computer.
+
+To make any tab persistent, check the "Save this tab, and automatically open it when I open OnionShare" box before starting the server. When a tab is saved a purple pin icon appears to the left of its server status.
+
+.. image:: _static/screenshots/advanced-save-tabs.png
+
+When you quit OnionShare and then open it again, your saved tabs will start out open. You'll have to manually start each service, but when you do they will start with the same OnionShare address, and with the same password.
+
+If you save a tab, a copy of that tab's onion service secret key will be stored on your computer with your OnionShare settings.
+
 .. _disable_passwords:
 
 Disable Passwords
 -----------------
 
+By default, all OnionShare services are protected with the username `onionshare` and a randomly-generated password. If someone makes 20 wrong guesses of the password, your onion service is automatically stopped to prevent a brute force attack against the OnionShare service.
+
+But sometimes you might want your OnionShare service to be accessible to the public. For example, if you want to set up an OnionShare receive service so the public can securely and anonymously send you files. In this case, it's better to disable the password altogether. If you don't do this, someone can force your server to stop just by making 20 wrong guesses of your password, even if they know the correct password.
+
+To disable the password for any tab, just check the "Don't use a password" box before starting the server. Then the server will be public and won't have a password.
+
 Scheduled Times
 ---------------
 
+OnionShare supports scheduling exactly when a service should start and stop. Before starting server, click "Show advanced settings" in its tab and then check the boxes next to either "Start onion service at scheduled time", "Stop onion service at scheduled time", or both, and set the desired dates and times.
+
+If you scheduled a service to start in the future, when you click the start button you will see a timer counting down until it will start. If you scheduled it to stop in the future, after it's started you will see a timer counting down to when it will stop automatically.
+
+**Scheduling an OnionShare service to automatically start can be used as a dead man's switch**, where your service will be made public at a given time in the future if anything happens to you. If nothing happens to you, you can cancel the service before it's scheduled to start.
+
+.. image:: _static/screenshots/advanced-schedule-start-timer.png
+
+**Scheduling an OnionShare service to automatically stop can be useful to limit exposure**, like if you want to share secret documents while making sure they're not available on the internet for more than a few days.
+
+.. image:: _static/screenshots/advanced-schedule-stop-timer.png
+
 Legacy Addresses
 ----------------
 
+OnionShare uses v3 Tor onion services by default. These are modern onion addresses that have 56 characters, for example::
+
+    uf3wmtpbstcupvrrsetrtct7qcmnqvdcsxqzxthxbx2y7tidatxye7id.onion
+
+But it still has support for v2 onion addresses, the old type of onion addresses that have 16 characters, for example::
+
+    lc7j6u55vhrh45eq.onion
+
+OnionShare calls v2 onion addresses "legacy addresses". v3 onion addresses are more secure, and using legacy addresses is not recommended.
+
+To use legacy addresses, before starting a server click "Show advanced settings" in its tab and check the "Use a legacy address (v2 onion service, not recommended)" box. In legacy mode you can optionally enable Tor client authentication. Once you start a server in legacy mode you cannot remove legacy mode in that tab. Instead you must start a separate service in a separate tab.
+
+Tor Project plans to `completely deprecate v2 onion services <https://blog.torproject.org/v2-deprecation-timeline>`_ on October 15, 2021, and legacy onion services will soon be removed from OnionShare as well.

docs/source/conf.py

@@ -15,7 +15,7 @@ exclude_patterns = []
 html_theme = "sphinx_rtd_theme"
 html_logo = "_static/logo.png"
 html_favicon = "_static/favicon.ico"
-html_theme_options = {"logo_only": True}
+html_theme_options = {}
 html_static_path = ["_static"]
 html_css_files = ["custom.css"]
 html_show_sourcelink = False

docs/source/features.rst

@@ -13,7 +13,7 @@ You're responsible for securely sharing that URL using a communication channel o
 
 The people who you send the URL to must then copy and paste it into `Tor Browser <https://www.torproject.org/>`_ to access the OnionShare service.
 
-With OnionShare, *your own computer is the web server*. If you run OnionShare on your laptop to send someone files, and then suspends your laptop before the files have been downloaded, the service will not be available until your laptop is unsuspended and connected to the internet again. OnionShare works best when working with people in real-time.
+With OnionShare, *your own computer is the web server*. If you run OnionShare on your laptop to send someone files, and then suspend your laptop before the files have been downloaded, the service will not be available until your laptop is unsuspended and connected to the internet again. OnionShare works best when working with people in real-time.
 
 Because your own computer is the web server, *no third party can access anything that happens in OnionShare*, not even the developers of OnionShare. It's completely private. And because OnionShare is based on Tor onion services too, it also protects your anonymity. See the :doc:`security design </security>` for more information.
 
@@ -119,7 +119,7 @@ After you start the server, copy the OnionShare address and send it to the peopl
 
 People can join the chat room by loading its OnionShare address in Tor Browser. The chat room requires JavasScript, so everyone who wants to participate must set their security level to Standard or Safer instead of Safest.
 
-When someone joins the chat room they get assigned a random name which they can change in the left panel if they want. No chat history will get displayed at all, even if others were already chatting in the room, because the chat history isn't saved anywhere.
+When someone joins the chat room they get assigned a random name. They can change their name by typing a new name in the box in the left panel and pressing enter. No chat history will get displayed at all, even if others were already chatting in the room, because the chat history isn't saved anywhere.
 
 .. image:: _static/screenshots/chat-torbrowser.png
 

docs/source/security.rst

@@ -6,13 +6,17 @@ First read :ref:`how_it_works` to understand the basics of how OnionShare works.
 What It Protects Against
 ------------------------
 
-* **Third parties don't have access to anything that happens in OnionShare.** When you use OnionShare, you host services directly on your computer. For example, when you share files with OnionShare, you don't upload these files to any server, and when you start an OnionShare chat room, your computer is the chat room server itself. Traditional ways of sharing files or setting up websites and chat rooms require trusting a service with access to your data.
+**Third parties don't have access to anything that happens in OnionShare.** When you use OnionShare, you host services directly on your computer. For example, when you share files with OnionShare, you don't upload these files to any server, and when you start an OnionShare chat room, your computer is the chat room server itself. Traditional ways of sharing files or setting up websites and chat rooms require trusting a service with access to your data.
-* **Network eavesdroppers can't spy on anything that happens in OnionShare in transit.** Because connections between Tor onion services and Tor Browser are end-to-end encrypted, no network attackers can eavesdrop on what happens in an OnionShare service. If the eavesdropper is positioned on the OnionShare user's end, the Tor Browser user's end, or is a malicious Tor node, they will only see Tor traffic. If the eavesdropper is a malicious rendezvous node used to connect Tor Browser with OnionShare's onion service, the traffic will be encrypted using the onion service key.
+
-* **Anonymity of OnionShare users are protected by Tor.** OnionShare and Tor Browser protect the anonymity of the users. As long as the OnionShare user anonymously communicates the OnionShare address with the Tor Browser users, the Tor Browser users and eavesdroppers can't learn the identity of the OnionShare user.
+**Network eavesdroppers can't spy on anything that happens in OnionShare in transit.** Because connections between Tor onion services and Tor Browser are end-to-end encrypted, no network attackers can eavesdrop on what happens in an OnionShare service. If the eavesdropper is positioned on the OnionShare user's end, the Tor Browser user's end, or is a malicious Tor node, they will only see Tor traffic. If the eavesdropper is a malicious rendezvous node used to connect Tor Browser with OnionShare's onion service, the traffic will be encrypted using the onion service key.
-* **If an attacker learns about the onion service, they still can't access anything.** There have been attacks against the Tor network that can enumerate onion services. Even if someone discovers the .onion address of an OnionShare onion service, they can't access it without also knowing the service's random password (unless, of course, the OnionShare users chooses to disable the password and make it public). The password is generated by choosing two random words from a list of 6800 words, meaning there are 6800^2, or about 46 million possible password. But they can only make 20 wrong guesses before OnionShare stops the server, preventing brute force attacks against the password.
+
+**Anonymity of OnionShare users are protected by Tor.** OnionShare and Tor Browser protect the anonymity of the users. As long as the OnionShare user anonymously communicates the OnionShare address with the Tor Browser users, the Tor Browser users and eavesdroppers can't learn the identity of the OnionShare user.
+
+**If an attacker learns about the onion service, they still can't access anything.** There have been attacks against the Tor network that can enumerate onion services. Even if someone discovers the .onion address of an OnionShare onion service, they can't access it without also knowing the service's random password (unless, of course, the OnionShare users chooses to disable the password and make it public). The password is generated by choosing two random words from a list of 6800 words, meaning there are 6800^2, or about 46 million possible password. But they can only make 20 wrong guesses before OnionShare stops the server, preventing brute force attacks against the password.
 
 What It Doesn't Protect Against
 -------------------------------
 
-* **Communicating the OnionShare address might not be secure.** The OnionShare user is responsible for securely communicating the OnionShare address with people. If they send it insecurely (such as through an email message, and their email is being monitored by an attacker), the eavesdropper will learn that they're using OnionShare. If the attacker loads the address in Tor Browser before the legitimate recipient gets to it, they can access the service. If this risk fits the user's threat model, they must find a more secure way to communicate the address, such as in an encrypted email, chat, or voice call. This isn't necessary in cases where OnionShare is being used for something that isn't secret.
+**Communicating the OnionShare address might not be secure.** The OnionShare user is responsible for securely communicating the OnionShare address with people. If they send it insecurely (such as through an email message, and their email is being monitored by an attacker), the eavesdropper will learn that they're using OnionShare. If the attacker loads the address in Tor Browser before the legitimate recipient gets to it, they can access the service. If this risk fits the user's threat model, they must find a more secure way to communicate the address, such as in an encrypted email, chat, or voice call. This isn't necessary in cases where OnionShare is being used for something that isn't secret.
-* **Communicating the OnionShare address might not be anonymous.** While OnionShare and Tor Browser allow for anonymity, if the user wishes to remain anonymous they must take extra steps to ensure this while communicating the OnionShare address. For example, they might need to use Tor to create a new anonymous email or chat account, and only access it over Tor, to use for sharing the address. This isn't necessary in cases where there's no need to protect anonymity, such as co-workers who know each other sharing work documents.
+
+**Communicating the OnionShare address might not be anonymous.** While OnionShare and Tor Browser allow for anonymity, if the user wishes to remain anonymous they must take extra steps to ensure this while communicating the OnionShare address. For example, they might need to use Tor to create a new anonymous email or chat account, and only access it over Tor, to use for sharing the address. This isn't necessary in cases where there's no need to protect anonymity, such as co-workers who know each other sharing work documents.