diff --git a/docs/source/security.rst b/docs/source/security.rst index e7f4529b..4f85600a 100644 --- a/docs/source/security.rst +++ b/docs/source/security.rst @@ -1,24 +1,24 @@ Security design =============== -First read :ref:`how_it_works` to understand the basics of how OnionShare works. +Read :ref:`how_it_works` first to get a handle on how OnionShare works. Like all software, OnionShare may contain bugs or vulnerabilities. What OnionShare 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.** Using OnionShare means hosting services directly on your computer. When sharing files with OnionShare, they are not uploaded to any server. If you make an OnionShare chat room, your computer acts as a server for that too. This avoids the traditional model of having to trust the computers of others. -**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. +**Network eavesdroppers can't spy on anything that happens in OnionShare in transit.** The connection between the Tor onion service and the Tor Browser is end-to-end encrypted. This means no network attackers can eavesdrop. Only Tor traffic is available to anyone at any point of the exchange. Even if eavesdropper is a malicious rendezvous node used to connect the Tor Browser with OnionShare's onion service, the traffic is encrypted using the identity private 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. +**If an attacker learns about the onion service, it still can't access anything.** Prior attacks against the Tor network to enumerate the onion services amount to discovering the .onion address of the services on it. Accessing them is stopped by a random password (unless the OnionShare user chooses to turn it off and make it public). The password is generated by choosing two random words from a list of 6800 words, making 6800^2, or about 46 million possible passwords. Only 20 wrong guesses can be made before OnionShare stops the server, preventing brute force attacks against the password. What OnionShare 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.** Communicating the OnionShare address to people is the responsibility of the OnionShare user. If sent insecurely (such as through an e-mail message monitored by an attacker), an eavesdropper can tell OnionShare is being used. By loading the address in Tor Browser before the legitimate recipient gets to it, the service can be accessed. If this is to be avoided, the address must be communicateed securely, via encrypted e-mail, or in person. Voice call is a better secondary option than unencrypted chat in most cases, as it is a different network to eavesdrop. This isn't necessary when using OnionShare 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.** To ensure maximum privacy, extra steps must be taken to ensure the OnionShare address is communicated securely. A new e-mail or chat account, only accessed over Tor, can be used to share the address. This isn't necessary unless anonymity is an absolute goal.