Added security design

docs/source/features.rst

@@ -1,3 +1,5 @@
+.. _how_it_works:
+
 How OnionShare Works
 ====================
 

docs/source/security.rst

@@ -1,3 +1,18 @@
 Security Design
 ===============
 
+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.
+* **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.
+* **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 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.