OnionShare
Donate
OnionShare LogoUsing OnionShare in Whonix.
Introduction[edit]
[edit]
OnionShare is an open source program that allows users to share/receive files, host a website or chat anonymously utilizing the Tor network. [1] The OnionShare wiki succinctly describes the design: [2]
Web servers are started locally on your computer and made accessible to other people as Tor onion services
.
By default, OnionShare web addresses are protected with a random password. A typical OnionShare address might look something like this:
http://onionshare:constrict-purity@by4im3ir5nsvygprmjq74xwplrkdgt44qmeapxawwikxacmr3dqzyjad.onionYou’re responsible for securely sharing that URL using a communication channel of your choice like in an encrypted chat message, or using something less secure like unencrypted e-mail, depending on your threat model
The people you send the URL to then copy and paste it into their Tor Browser
It is also possible to run the program in Receive mode, allowing you to receive files via OnionShare after they are uploaded by Tor Browser users. This functions as a sort of 'SecureDrop Lite' or a personal Dropbox. Additionally, OnionShare enables the easy hosting of anonymous websites
:
In addition to the “Share Files” and “Receive Files” tabs, OnionShare 2.2 introduces the “Publish Website” tab. You drag all of the files that make up your website into the OnionShare window and click “Start sharing.” It will start a web server to host your static website and give you a .onion URL. This website is only accessible from the Tor network, so people will need Tor Browser to visit it. People who visit your website will have no idea who you are – they won’t have access to your IP address, and they won’t know your identity or your location. And, so long as your website visitors are able to access the Tor network, the website can’t be censored.
OnionShare allows users to share/receive files, host websites or chat anonymously at the same time using a tabs feature. The secure, ephemeral and anonymous chat feature is particularly useful since it does not require account creation, is encrypted end-to-end and reduces the risk of messages being stored locally: [3]
Now when you open OnionShare you are presented with a blank tab that lets you choose between sharing files, receiving files, hosting a website, or chatting anonymous. You can have as many tabs open as you want at a time, and you can easily save tabs (that's what the purple thumbtack in the tab bar means) so that if you quit OnionShare and open it again later, these services can start back up with the same OnionShare addresses. ... Another major new feature is chat. You start a chat service, it gives you an OnionShare address, and then you send this address to everyone who is invited to the chat room (using an encrypted messaging app like Signal, for example). Then everyone loads this address in a Tor Browser, makes up a name to go by, and can have a completely private conversation.
As OnionShare is an actively developed project, it is recommended to refer to official documentation for the latest features and information before use. Advanced users should also consider upstream documentation for features such as saving of tabs, turning off passwords, scheduled start/stop times, command line operations.
Security Design[edit]
Table: OnionShare Security Design [4]
| Protections | Description |
|---|---|
| Third party access | Third parties cannot access anything that happens in OnionShare because services are hosted directly on your computer. Filesharing does not utilise online servers, and chat rooms also use your computer as a server; trust in other computers is removed. |
| Network eavesdroppers | Eavesdroppers cannot spy on OnionShare activities in transit because connections between Tor onions services and Tor Browser are encrypted end-to-end. Even malicious Tor nodes used for connections will only see encrypted traffic using the onion service's private key. |
| Anonymity | OnionShare anonymity is protected by Tor. If OnionShare addresses are anonymously communicated with Tor Browser users, then eavesdroppers cannot learn the identity of the OnionShare user. |
| Onion service discovery | Malicious actors cannot access anything just by learning about the onion service; attackers also need to guess the private key used for client authentication (access). [5] |
OnionShare cannot protect users if the OnionShare address and private key is not communicated securely. For example, do not share this information via email which can be potentially monitored by attackers. It is far safer to utilize encrypted text messages for this purpose (preferably with disappearing messages enabled), encrypted email, or in-person sharing of this information. This method is not anonymous unless a new email account or chat account is only created/accessed over Tor.
Installation[edit]
Whonix-Gateway™ Installation Steps[edit]
onion-grater Profile[edit]
This application requires incoming connections through a Tor onion service. Supported Whonix-Gateway™ modifications are therefore necessary for full functionality; see the instructions below.
For better security, consider using Multiple Whonix-Gateway and Multiple Whonix-Workstation™. In any case, Whonix is the safest choice for running it. [6]
1. OnionShare onion-grater profile.
Extend the onion-grater whitelist.
2. Onion client authorization onion-grater profile.
This is required if using OnionShare in combination with Onion Client Authorization.
Extend the onion-grater whitelist.
On Whonix-Gateway (sys-whonix).
Add onion-grater profile.
sudo onion-grater-add 40_onion_authentication
3. Done.
Onion-grater configuration has been completed.
Whonix-Workstation™ Installation Steps[edit]
Installation[edit]
Before installing OnionShare:
- A separate Whonix-Workstation (Qubes-Whonix™:
anon-whonixApp Qube) is also recommended. The reason is the OnionShare installation will persist in this configuration and it is best practice to separate different, anonymous activities in distinct VMs (App Qubes). See Multiple Whonix-Workstation. - Installation using
flatpak
or snapis discouraged because it leads to Tor over Tor. - Installation from Debian package sources as documented below is recommended.
Inside Whonix-Workstation.
Install package(s) onionshare following these instructions
1 Platform specific notice.
- Non-Qubes-Whonix: No special notice.
- Qubes-Whonix: In Template.
2 Update the package lists and upgrade the system.
sudo apt update && sudo apt full-upgrade
3 Install the onionshare package(s).
Using apt command line --no-install-recommends option is in most cases optional.
sudo apt install --no-install-recommends onionshare
4 Platform specific notice.
- Non-Qubes-Whonix: No special notice.
- Qubes-Whonix: Shut down Template and restart App Qubes based on it as per Qubes Template Modification.
5 Done.
The procedure of installing package(s) onionshare is complete.
Firewall Settings[edit]
Modify the Whonix-Workstation (anon-whonix) user firewall settings and reload them.
Modify Whonix-Workstation™ User Firewall Settings
Note: If no changes have yet been made to Whonix Firewall Settings, then the Whonix User Firewall Settings File /etc/whonix_firewall.d/50_user.conf appears empty (because it does not exist). This is expected.
If using Qubes-Whonix™, complete these steps.
In Whonix-Workstation App Qube. Make sure folder /usr/local/etc/whonix_firewall.d exists.
sudo mkdir -p /usr/local/etc/whonix_firewall.d
Qubes App Launcher (blue/grey "Q") → Whonix-Workstation App Qube (commonly called anon-whonix) → Whonix User Firewall Settings
If using a graphical Whonix-Workstation, complete these steps.
Start Menu → Applications → System → User Firewall Settings
If using a terminal-only Whonix-Workstation, complete these steps.
Open file /usr/local/etc/whonix_firewall.d/50_user.conf with root rights.
sudoedit /usr/local/etc/whonix_firewall.d/50_user.conf
For more help, press on Expand on the right.
Note: This is for informational purposes only! Do not edit /etc/whonix_firewall.d/30_whonix_workstation_default.conf.
The Whonix Global Firewall Settings File /etc/whonix_firewall.d/30_whonix_workstation_default.conf contains default settings and explanatory comments about their purpose. By default, the file is opened read-only and is not meant to be directly edited. Below, it is recommended to open the file without root rights. The file contains an explanatory comment on how to change firewall settings.
## Please use "/etc/whonix_firewall.d/50_user.conf" for your custom configuration,
## which will override the defaults found here. When {{project_name_short}} is updated, this
## file may be overwritten.
Also see: Whonix modular flexible .d style configuration folders.
To view the file, follow these instructions.
If using Qubes-Whonix, complete these steps.
Qubes App Launcher (blue/grey "Q") → Template: whonix-workstation-17 → Whonix Global Firewall Settings
If using a graphical Whonix-Workstation, complete these steps.
Start Menu → Applications → Settings → Global Firewall Settings
If using a terminal-only Whonix-Workstation, complete these steps.
In Whonix-Workstation, open the whonix_firewall configuration file in an editor. nano /etc/whonix_firewall.d/30_whonix_workstation_default.conf
Add. [7]
EXTERNAL_OPEN_PORTS+=" $(seq 17600 17659) "
Save.
Reload Whonix-Workstation™ Firewall.
If you are using Qubes-Whonix™, complete the following steps.
Qubes App Launcher (blue/grey "Q") → Whonix-Workstation App Qube (commonly named anon-whonix) → Reload Whonix Firewall
If you are using a graphical Whonix-Workstation, complete the following steps.
Start Menu → Applications → System → Reload Whonix Firewall
If you are using a terminal-only Whonix-Workstation, run. sudo whonix_firewall
[edit]
[edit]
You can launch OnionShare in Whonix-Workstation using either the command-line interface (CLI) or the graphical user interface (GUI). The GUI can also be started from its icon shortcut.
- CLI: onionshare
- GUI: onionshare-gui
- If the flatpak version was installed (discouraged because of Tor over Tor), run. flatpak run org.onionshare.OnionShare
[edit]
1. Be greeted by OnionShare start screen.
Figure: OnionShare start screen
2. Network Settings.
After running OnionShare, configure Tor by clicking on "Network Settings".
3. Choose "Connect using socket file" then click "Save" [8].
Figure: OnionShare Tor Settings
4. Homepage.
It will return you to the first page after running OnionShare, hit "Connect to Tor" and you should be presented with OnionShare services.
Figure: OnionShare homepage
[edit]
OnionShare functionality (excerpt):
- Provides a feature called 'Receive Mode'. With this mode, you can start an onion service and allow other users to upload files to you via Tor Browser (rather than Share Mode, in which you share files from your OnionShare to others).
- Allows the hosting of static HTML websites.
- Allows users to set up a private, secure chat room that does not require an account and does not log activity.
A complete user guide is available, including advanced topics, hardening options [9] and development documentation; refer to the official website.
Do not change settings without fully understanding their function, otherwise onion addresses might be re-used, shares might be left open even after multiple downloads are performed, and so on.
[edit]
Once OnionShare has been installed correctly and the Tor check is successful, sharing files anonymously is easy: [10]
You can use OnionShare to send files and folders to people securely and anonymously. Open a share tab, drag in the files and folders you wish to share, and click “Start sharing”.
... When you’re ready to share, click the “Start sharing” button. You can always click “Stop sharing”, or quit OnionShare, immediately taking the website down. You can also click the “↑” icon in the top-right corner to show the history and progress of people downloading files from you.
Now that you have a OnionShare, copy the address and send it to the person you want to receive the files. If the files need to stay secure, or the person is otherwise exposed to danger, use an encrypted messaging app.
That person then must load the address in Tor Browser. After logging in with the random password included in the web address, the files can be downloaded directly from your computer by clicking the “Download Files” link in the corner.
Figure: Select File to Share
Figure: Secret Onion URL for Downloaders
Figure: Add private key in Tor Browser for authentication
Figure: OnionShare Download with Tor Browser [11]
Receive Files and Messages[edit]
Receiving files or messages is also simple: [12]
You can use OnionShare to let people anonymously submit files and messages directly to your computer, essentially turning it into an anonymous dropbox. Open a receive tab and choose the settings that you want.
You can browse for a folder to save messages and files that get submitted.
You can check “Disable submitting text” if want to only allow file uploads, and you can check “Disable uploading files” if you want to only allow submitting text messages, like for an anonymous contact form.
Figure: Receive Files Page on OnionShare
Figure: Receive Files or Messages
Figure: Receive Files Onion Hidden Services After Authentication
Website Hosting[edit]
Website hosting can be achieved in a few steps: [13]
To host a static HTML website with OnionShare, open a website tab, drag the files and folders that make up the static content there, and click “Start sharing” when you are ready. If you add an index.html file, it will render when someone loads your website. You should also include any other HTML files, CSS files, JavaScript files, and images that make up the website. (Note that OnionShare only supports hosting static websites. It can’t host websites that execute code or use databases. So you can’t for example use WordPress.)
This functionality means content can be shared temporarily to select individuals, or it can be run as a public service if desired.
Anonymous Chat[edit]
Finally, private and secure chat rooms (without logging) are possible by: [14]
- Opening a chat tab and selecting "Start chat server".
- Copy the onion address and private key and send them to the intended recipients. [15]
- To join the chat room, participants cut and paste the OnionShare address into Tor Brower; JavaScript is required, so the security level must be set to "Standard" or "Safer".
- After joining, participants are assigned a random name.
The benefit of OnionShare anonymous chat is no copies of messages are left on devices or possibly on servers/databases, and account creation is unnecessary.
[edit]
This wiki chapter might be useful for users who intent to visit authenticated OnionShare Services using Tor Browser in Whonix.
When a provider of an OnionShare service is using onion authentication, then a Whonix visitor of that OnionShare instance is required to setup Onion Service Client Authentication in Whonix first.
There are two options to setup Onion Service Client Authentication. Choose either option A) or B).
- A) Tor Browser Onion Client Authorization, or
- B) Onion Service Client Authentication setup on Whonix-Gateway.
If this step is omitted, the following symptom might be shown.
Command filtered
[edit]
AppArmor profiles are available to better contain OnionShare, but they are outdated [16].
Advanced users are encouraged to help progress and complete this wiki section. Successes or failures can also be reported in the Whonix AppArmor forum.
TODO: Test profiles and expand this section.
Troubleshooting[edit]
https://github.com/onionshare/onionshare/issues/1374
Opening tab in existing OnionShare window (pid 2)
rm ~/.config/onionshare/lock
[edit]
Prerequisite knowledge: Frozen Packages
Whonix 17 is based on Debian 12 (codename "bookworm").
Newer OnionShare versions, that is newer than the version listed on packages.debian.org page for bookworm, will only be supported once the next stable version of Debian gets released and once Whonix has been ported to that version.
Installing newer OnionShare versions is unsupported due to technical difficulties.
Technical details:
- Installation from source code is undocumented.
flatpakandsnapinstallation method currently leads to Tor over Tor. Details here:
Footnotes[edit]
- ↑ https://onionshare.org/
- ↑ https://docs.onionshare.org/
- ↑
https://blog.torproject.org/new-release-onionshare-23
- ↑ https://docs.onionshare.org/2.4/en/security.html
- ↑ Unless the private key feature is turned off.
- ↑
Security considerations:
- By using Whonix, additional protections are in place for enhanced security.
- This application requires access to Tor's control protocol.
- In the Whonix context, Tor's control protocol has dangerous features. The Tor control command GETINFO address reveals the real, external IP of the Tor client.
- Whonix provides onion-grater, a Tor Control Port Filter Proxy - filtering dangerous Tor Control Port commands.
- When this application is run inside Whonix-Gateway with an onion-grater whitelist extension, it limits Whonix-Workstation application rights to Tor control protocol access only. Non-whitelisted Tor control commands such as GETINFO address are rejected by onion-grater in these circumstances. In this event, Whonix-Workstation cannot determine its own IP address via requests to the Tor Controller, as onion-grater filters the reply.
- In comparison with other operating systems:
- If the application is run on a non-Tor-focused operating system like Debian: The application will have unlimited access to Tor's control protocol (a less secure configuration).
- Whonix: The application's access to Tor's control protocol is limited. Only whitelisted Tor control protocol commands required by the application are allowed.
- Comparison of using Tor as a client versus hosting Tor onion services.
- Using Tor only as a client: More secure.
- When hosting Tor onion services: Users are more vulnerable to attacks against the Tor network. This is elaborated in chapter Onion Services Security.
- ↑
As per https://gitlab.tails.boum.org/tails/tails/-/issues/7870#note-15 OnionShare uses ports 17600 to 17659.
- ↑
Even if you mistakenly connected by "Use the Tor version built into OnionShare" it does not lead to Tor over Tor thanks to special support by anon-ws-disable-stacked-tor.
https://github.com/Whonix/anon-ws-disable-stacked-tor/blob/master/usr/bin/tor.anondist#L70
- ↑ Such as setting a Shutdown Timer to self-destruct shares if they are not downloaded within an acceptable time window. These topics are beyond the scope of this documentation.
- ↑
https://docs.onionshare.org/2.6.2/en/features.html
- ↑
https://micahflee.com/2018/02/onionshare-has-some-exciting-new-features/
- ↑
https://docs.onionshare.org/2.4/en/features.html#receive-files-and-messages
- ↑
https://docs.onionshare.org/2.4/en/features.html#host-a-website
- ↑ https://docs.onionshare.org/2.4/en/features.html#chat-anonymously
- ↑ Preferably with an encrypted messaging application.
- ↑ https://github.com/micahflee/onionshare/issues/686 open OnionShare AppArmor ticket
The most watertight privacy operating system in the world.
At
Whonix we value freedom and trust, supporting Open Source and Freedom Software
2012-
2025 ENCRYPTED SUPPORT LLC
We believe security software like Whonix needs to remain open source and independent. Would you help sustain and grow the project? Learn more about our 13 year success story and maybe DONATE!