Understanding and using onion services in Tor Browser
Onion services (formerly known as "hidden services") are services, like websites, that are only accessible through the Tor network.
Onion services offer several advantages over ordinary services on the non-private web:
- Onion services' location and IP address are hidden, making it difficult for adversaries to censor them or identify their operators.
- All traffic between Tor users and onion services is end-to-end encrypted, so you do not need to worry about connecting over HTTPS.
- The address of an onion service is automatically generated, so the operators do not need to purchase a domain name.
- Because of the cryptography involved, the .onion URL lets Tor ensure that it is connecting to the right location and that the connection is not being tampered with.
How to access an onion service
Just like any other website, you will need to know the address of an onion service in order to connect to it. An onion address consists of 56 letters and numbers, followed by ".onion".
When accessing a website that uses an onion service, Tor Browser will show in the URL bar an icon of an onion displaying the state of your connection: secure and using an onion service. You can learn more about the onion service by clicking on the onion icon and the adjacent Circuit Display in the address bar.
Onion Icon
Another way to learn about an onion site is if the website administrator has implemented a feature called Onion-Location. Onion-Location is a non-standard HTTP header that websites can use to advertise their onion counterpart. If the website that you are visiting has an onion site available, a purple suggestion pill will prompt at the URL bar in Tor Browser displaying ".onion available". When you click on ".onion available", the website will be reloaded and redirected to its onion counterpart.
Onion-Location
Onion Icon
When browsing an Onion Service, Tor Browser displays different onion icons in the address bar indicating the security of the current webpage.
Onion service served over HTTP or HTTPS.
An onion means:
- The Onion Service is served over HTTP, or HTTPS with a CA-Issued certificate.
- The Onion Service is served over HTTPS with a Self-Signed certificate.
Onion service is served over an insecure URL.
An onion with a red slash means:
- The Onion Service is served with a script from an insecure URL.
Onion service with an expired certificate, wrong domain or served over an insecure URL.
An onion with a caution sign means:
- The Onion Service is served over HTTPS with an expired Certificate.
- The Onion Service is served over HTTPS with a wrong Domain.
- The Onion Service is served with a mixed form over an insecure URL.
Onion Service authentication
An authenticated onion service is a service like an onion site that requires the client to provide an authentication token before accessing the service. As a Tor user, you may authenticate yourself directly in Tor Browser. In order to access this service, you will need access credentials from the onion service operator. When accessing an authenticated onion service, Tor Browser will show in the URL bar an icon of a little gray key, accompanied by a tooltip. Enter your valid private key into the input field.
Client Authorization
Onion Services errors
If you can't connect to an onion site, Tor Browser will provide a specific error message informing why the website is unavailable. Errors can happen in different layers: client errors, network errors, or service errors. Some of these errors can be fixed by following the Troubleshooting section. The table below shows all the possible errors and which action you should take to solve the issue.
| Code | Error Title | Short Description |
|---|---|---|
| 0xF0 | Onionsite Not Found | The most likely cause is that the onionsite is offline. Contact the onionsite administrator. |
| 0xF1 | Onionsite Cannot Be Reached | The onionsite is unreachable due an internal error. |
| 0xF2 | Onionsite Has Disconnected | The most likely cause is that the onionsite is offline. Contact the onionsite administrator. |
| 0xF3 | Unable to Connect to Onionsite | The onionsite is busy or the Tor network is overloaded. Try again later. |
| 0xF4 | Onionsite Requires Authentication | Access to the onionsite requires a key but none was provided. |
| 0xF5 | Onionsite Authentication Failed | The provided key is incorrect or has been revoked. Contact the onionsite administrator. |
| 0xF6 | Invalid Onionsite Address | The provided onionsite address is invalid. Please check that you entered it correctly. |
| 0xF7 | Onionsite Circuit Creation Timed Out | Failed to connect to the onionsite, possibly due to a poor network connection. |
Troubleshooting
If you cannot reach the onion service you requested, make sure that you have entered the onion address correctly: even a small mistake will stop Tor Browser from being able to reach the site.
If you are trying to access a 16 character (the shorter "V2 format") onion service, this type of address no longer works on today's Tor network.
You can also test if you are able to access other onion services by connecting to DuckDuckGo's Onion Service. If you are still unable to connect to the onion service after verifying the address, please try again later. There may be a temporary connection issue, or the site operators may have allowed it to go offline without warning.