Tor at the Heart: OnionShare

During the month of December, we're highlighting other organizations and projects that rely on Tor, build on Tor, or are accomplishing their missions better because Tor exists. Check out our blog each day to learn about our fellow travelers. And please support the Tor Project! We're at the heart of Internet freedom.
Donate today!

By Micah Lee

In August 2013, David Miranda was detained for nine hours and searched at Heathrow Airport in London while he was trying to board a plane back home to Rio de Janeiro. Working on a journalism assignment for the Guardian, he was carrying an encrypted USB stick that contained classified government documents. When I first learned about this story, I knew there must be safer ways to move sensitive documents across the world than physically carrying them, one that didn’t involve putting individual people at risk from border agents and draconian “terrorism” laws that are used to stifle award-winning journalism.

Here’s how I would have done it: In Berlin (where the secret files originated), I would set up a local web server on my computer, that isn’t accessible from the internet. The only thing on the website would be a download link to an encrypted file that contained the secret documents. Then I would setup a Tor onion service -- one of the coolest and most under-appreciated technologies on the internet, in my opinion -- to make this simple website accessible from a special “.onion” domain name. I would send my colleague in Rio (in this case, Glenn Greenwald) the URL to the onion service. He would open it in Tor Browser and download the encrypted file. As soon as he finished the download, I would stop the local web server and remove the onion service, so it would no longer be on the internet at all.

Of course, the problem is that while this may be simple for seasoned nerds like myself, it’s not for many journalists, activists, or lawyers who run into similar problems on a regular basis. Inspired by this idea, I developed a simple and user-friendly open source tool called OnionShare that automates this process. You open OnionShare, drag some files into it, and click the “Start Sharing” button. After a moment, OnionShare gives you URL that looks something like http://4a7kqhcc7ko6a5rd.onion/logan-chopin. You send this URL to someone you’d like to share files with, and they load it using Tor Browser and download the files directly from the web server running on your computer. The moment the download is complete, OnionShare shuts down the web service, the URL no longer works, and the files you shared disappear from the internet. (Since OnionShare runs a server directly on your computer, this also means that your computer needs to be online for the URL to work -- if you suspend your laptop, for example, the URL won’t work until you get back online.)

Onionshare server side

Onionshare client side

I’m the developer of OnionShare, but I have no idea how many users it has. I consider this a feature. It’s completely decentralized, anonymous, and private. I don’t run a central service -- instead, every user runs their own short-lived service, often only for a few minutes, and that service disappears as soon as they finish sharing their files.

However, I do know that people use it. I use it on a regular basis myself while working on sensitive journalism projects with my colleagues at The Intercept. Sources use it to send me and other journalists documents. I’ve heard from digital security trainers that OnionShare is used by the Movement for Black Lives in the United States, and by activists in Latin America. A European human rights lawyer told me that their client in Africa used it to send them sensitive files.

What OnionShare protects against:

  • Third parties don't have access to files being shared. The files are hosted directly on the sender's computer and don't get uploaded to any server. Instead, the sender's computer becomes the server. Traditional ways of sending files, like in an email or using a cloud hosting service like Dropbox or Google Drive, require trusting the service with access to the files being shared.
  • Network eavesdroppers can't spy on files in transit. Because connections between Tor onion services and Tor Browser are end-to-end encrypted, no network attackers can eavesdrop on the shared files while the recipient is downloading them. If the eavesdropper is positioned on the sender's end, the recipient's end, or is a malicious Tor node, they will only see Tor encrypted traffic.
  • Anonymity of sender and recipient are protected by Tor. OnionShare and Tor Browser protect the anonymity of the users. As long as the sender anonymously communicates the OnionShare URL with the recipient, the recipient and eavesdroppers can't learn the identity of the sender.
  • If an attacker enumerates the onion service, the shared files remain safe. There have been attacks against the Tor network that can enumerate onion services. If someone discovers the .onion address of an OnionShare onion service, they still cannot download the shared files without knowing the full URL, and OnionShare has rate-limited to protect against attempts to guess the URL.

What OnionShare doesn't protect against:

  • Communicating the OnionShare URL might not be secure. The sender is responsible for securely communicating the OnionShare URL with the recipient. 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 sending files with OnionShare. If the attacker loads the URL in Tor Browser before the legitimate recipient gets to it, they can download the files being shared. If this risk fits the sender's threat model, they must find a more secure way to communicate the URL, such as in an encrypted email, chat, or voice call. This isn't necessary in cases where the files being shared aren't secret.
  • Communicating the OnionShare URL might not be anonymous. While OnionShare and Tor Browser allow for anonymously sending files, if the sender wishes to remain anonymous they must take extra steps to ensure this while communicating the OnionShare URL. 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 URL. This isn't necessary in cases where there's no need to protect anonymity, such as coworkers who know each other sharing work documents.

You can find the source code for OnionShare here, and you download it from its website here.


December 23, 2016


I tested all the free "Cloud" services out there: Google Drive, Dropbox, ... to send a 'big' 4Go zip file, in all cases the upload would terminate at some point due to my terrible connection, and I didn't have the patience to continue. Then I learned about OnionShare and I've never been more happy! Even do I don't care much about the privacy side, OS managed to finish the zip transfer. Thank you Micah!


December 23, 2016


To get around the URL exchange (key exchange) issue you could either:
a) Pre-generate a fully random service public key and share it face-to-face before departing
b) Use one of the following to generate a predetermined string for the URL that the other party already gave you…
c) If only the keys were ECC Curve 25519, you could generate them deterministically from a shared secret and a windowed timestamp.

I agree that's a huge feature.

I think the original person was asking about how to get the url to your recipient though.

And for that, yes, Ricochet or the like is not a bad answer -- "however you do secure metadata-resistant messaging now."

(It seems to me that Signal and email are less good, because you leave clear metadata right before doing the thing that doesn't leave clear metadata, so you undermine your security properties.)


December 23, 2016


Is there/are there plans for an Onion Share Android app or extension to Orfox browser?

There isn't an OnionShare for Android yet, but I have talked with people from Guardian Project (who made Orbot) who have some interest in it.

CameraV, a secure camera app that Guardian Project made, already has some support for sharing via onion service. If you dig through the source code that feature uses something called libonionshare :).


December 23, 2016


It is very interesting and i did 'nt know this tool :
OnionShare : where are the steps to install a server on his own computer ?
OnionShare : do i need to install a server version of an operating system or only download & set up it ?
OnionShare : do i need to create an onion service before or does it every time that i wish send a file ?
OnionShare : can i send encrypted file (so it must be encrypted on the server onion * mine installed on the local folder , right ?) ?
OnionShare : has it a pgp key ?
OnionShare : has it a test page _ a server user test under the responsibility of the tor team or the maintainer (yourself is 'nt it ?)
OnionShare : whitout a pgp key verifying the download/installation & clear answer to simple questions ; it is a difficult to give it a try blindly.

URL : Whare are you thinking about these 2 ways to communicate the url :
URL : SMS4TOR is a Tor-friendly version of PrivNote : http://sms4tor3vcr2geip.onion/
Secure Messaging System for TOR
Anonymous Encrypted Messages That Self-destruct When Read
URL : i wonder if ricochet could be used and if my email could do the job.

Under the hood, OnionShare starts a web server and creates a Tor onion service for you. But this is all completely invisible to the user -- you don't even have to realize that it does this to use it. It works in Windows, Mac OS X, and Linux, and literally all you have to do to use it is:

1. Open Tor Browser in the background (OnionShare needs it for its tor process)
2. Open OnionShare, drag files into it, and click "Start Sharing"

That's it. That's all you need to do to set up the server on your own computer. Then finally:

3. Send the OnionShare URL to the person you're sharing the file with. They need to open the URL in Tor Browser, and then they can download the file.

You can send encrypted files, or you can send plaintext files. It also lets you send folders full of files. It's all up to you. However onion services are end-to-end encrypted, so pre-encrypting files manually yourself (like with PGP) just gives you an extra layer of encryption, but isn't strictly necessary.

As far as sharing the URL, it depends on your threat model. In many cases, it's probably fine to just send a private message on Twitter or Facebook -- it's unlikely that an attacker will see the URL, open it in Tor Browser, and download the file _before_ the intended recipient gets it. However it's always safest to use encryption to share the URL -- like a Signal message, a PGP email, and OTR chat.

It should definitely be able to run on a Raspberry Pi -- and in fact, I believe it's in Debian contrib already, so you likely can just "apt-get install onionshare" from your Pi running Raspbian (although, the version in Debian is very old, so I'd build it from source to get the newest version).

But Tor Browser itself isn't support for Raspberry Pis because they use arm processors. So in you'll have to do a few tweaks to make OnionShare work with your system tor. The next version of OnionShare will include better support for working with a system tor.

I don't know if it's portable, as in only writes to its own directory, like Tor Browser is, but if it is then you could definitely run it from removable media. You could try running it from a chroot installed on the removable drive, if you're so inclined.

I don't see any reason you couldn't run it on a Raspberry Pi. It's written in python so it should be architecture-independent. Depending on which distro you're using, you might have to build it yourself like the other commenter says, but that should be quite possible.


December 23, 2016




December 23, 2016


What I like the most about onionshare is that it forces the receiver to use Tor, and if he gets things wrong the *.onion link wont even work


December 23, 2016


This is the first time I heard about OnionShare. I especially like how the client user doesn't have to install anything besides Tor Browser. Maybe someday OnionShare will also be able to accept files from the client, uploaded in the browser?

Just a question. Does it bundle and manage its own Tor client (like Tor Browser + Tor Launcher)? Or does it expect to be able to connect to an already running SOCKSPort and ControlPort?

Thanks for the tip. I suppose that's an alternative, but it comes with some drawbacks. For one thing, it's centralized, which means that a server compromise could leak the files, whereas OnionShare creates temporary ad-hoc servers. Also, I think you have to register with Secure Drop to receive files, making it only pseudonymous. It would be good for certain use cases, but it's not that much different from using Drop Box or Google Drive, or even an anonymous (as in, no registration) Megaupload-style service, other than being accessible by .onion only.

I didn't want the responsibility of shipping my own version of tor, so the user needs to provide their own. The easiest way to use OnionShare is to just open Tor Browser in the background, and OnionShare will use its tor.

And in terms of using OnionShare to accept files, I hope to support this eventually. Here's the open issue for it:


December 23, 2016


Would Onionshare work for me if only obfs4 or meek-amazon bridges work for now for me?

Yes. OnionShare doesn't come with its own version of Tor, it uses one you already have, like your Tor Browser. So if you configure Tor Browser to use a bridge, OnionShare will too.

It already is! It's in contrib though, not main:

The reason it's in contrib is because it currently has a dependency for torbrowser-launcher, which is also in contrib. But I'm hoping to drop that dependency in the next version, and get it in main instead.

I also run an Ubuntu PPA, that has newer versions of OnionShare in it:

You are my hero!

Will check it out later.

Can you help ensure that OONI is better integrated with Debian infrastructure and with the onion services repositories? And to persuade Debian to ensure that there are Debian mirrors for the *entire* vast Debian repository?

If you get a chance, please pass on the warm regards of an utterly random Tor user to our man in Moscow :-)

Oh my, the dirty b-ds, a certain evil-minded Congressional committee waited until all the tech-minded editorialists (in particular Glenn Greenwald) were on vacation before suddenly releasing their absurdly counterfactual "report", which is actually a fine example of the kind of "fake news" we can expect from USG's new Ministry of Propaganda (the Global Engagement Center under the US State Department which was just created by a few lines in the NDAA).

On the bright side, the timing shows our enemies believe the tech community is effective at preventing the bad guys from always getting whatever they want.

I just hope FBI is not following the same tactic (as it has done before) by suddenly attacking Tor network while key people are on vacation.

> But I'm hoping to drop that dependency in the next version, and get it in main instead.

Another good reason to do that: Debian users can then obtain it using the onion service mirrors of the main section of the Debian repositories.

But in any case, I hope Peter P can get onion service mirrors of the *complete* Debian repositories very soon!


December 23, 2016


@ Micah:

Are you and/or Tor Project working with Citizen Lab to capture and reverse engineer samples of (possibly state-sponsored) malware attacking Tor users?

Would Onionshare be a suitable way to share malware samples with Citizen Lab?


December 23, 2016


In order to use Onionshare, are there any restrictions on your local (desktop) or LAN firewall?

As far as I can tell, if your Tor client can reach the Tor network (you can browse with Tor Browser), then you can use OnionShare. Onion services have a side-effect of NAT traversal.

Nope. If you can connect to Tor, OnionShare will work too. You won't need to do any configuration to your network at all. This is one of the magical things about Tor onion services, they slice through all inbound firewalls like NAT.

Allow me to disagree, using Ubuntu I have my firewall configured so that it only allows access on ports 80 and 443, which is enough for Tor Browser to work. However when I click on "start sharing" in Onionshare, it crashes the program. Works fine when I allow all outgoing traffic in Gufw.
Or maybe I am doing something wrong??


Sometimes people need to pass something (e.g. a hard drive or USB with forensic image of same) through US customs but do not wish to give up passphrases. For example, trying to get CitizenLab help in investigating suspected state-sponsored malware.

More generally, people relocating need to pass through customs but don't want to give up the passphrase to the detached hard drive containing their entire life. Could Onionshare be used like this?

o set up webserver to be active in certain narrow time frame, with protected access to the original LUKS encrypted hard drive with tarball backup,

o leave old country and set up in new country,

o buy new detached hard drive, computer, etc. in new country,

o use Onionshare to retrieve the original tarball and reconstitute ones life.

Could be useful for journalists, mineral exploration engineers, political dissidents, etc.

That could work, but if the server crashes or becomes inaccessible for any reason when you're a thousand miles away, you'll need some way to get it running again.

In this case, it is more reliable to encrypt the file and upload it to an anonymous DropBox account or the like, since nothing needs to be running once the file is uploaded. This solution also allows you to use a user-generated password and encryption passphrase, avoiding writing down an .onion URL or Tahoe-LAFS "cap" that Customs could find in your baggage/pocket and use to download the file themselves.

You might also consider Tahoe-LAFS, which doesn't require the uploader to be online when the file is downloaded (but keep an eye out for storage servers' garbage collection algorithms!), although this is much more difficult to setup.

I recommend a CCC talk called "Crypto Tales from the Trenches" in which a panel of journalists discuss securely traveling with documents.


December 23, 2016


@ Shari, Micah:

As you know, urged on by embattled FBI Director James Comey, the know-nothings in the US Congress are continuing to scream for mandatory backdoors in all civilian encryption, or even a ban on civilian encryption. And the Trump campaign has signaled strong support for the know-nothings.

One of the most effective ways to decisively remove this threat would be to persuade essential "civilian" USG agencies to adopt onion services. And one of the most essential "civilian" USG agencies--- so essential that even Trump promised not to attack it, although his extremist advisors appear to be reneging on that promise--- is the Social Security Administration. And SSA has a enormous problem which I think Onionshare could fix.

The problem is that SSA needs to share extremely personal/sensitive/dangerous information on essentially all US citizens in order to administer the program. In particular, it often needs to obtain the complete medical files of individual citizens from their medical provider(s), including such highly sensitive items as interviews by psychologists. However, SSA's core computer system is so antiquated, and the workforce so limited, that SSA has experienced great difficulty in using suitably strong encryption. The result is that in almost all portions of the USA, the default is for medical providers to share files with SSA (and each other) by sending them by unencrypted fax.

I hardly need explain why this is so dangerous, but would like to stress the fact that some of us have been warning for years that in the 21st century, no citizen is too small-fry or too innocent to be attacked by professional spooks with extensive resources, not infrequently including spooks working for the government of some nation regarded by USG as an adversary. And during the past year, agencies running the gamut from NSA to CIA to FBI have joined the chorus of warning voices.

It seems that if Onionshare can scale to the enormous volumes required, it might be just what SSA has been looking for, because the system requirements and employee expertise appear to be sufficiently modest that SSA could adopt it if it provided some high bandwidth Tor nodes to help accommodate the increased network flow. It may be just a matter of TorProject giving SSA officials a few briefings to get a test program set up to demonstrate the potential of Onionshare for solving SSA's biggest technical problem.

More generally, it seems that Onionshare could be just what hospitals and other medical providers need to securely share highly sensitive patient files. The same goes for law offices.

Somewhat worrisome: law enforcement agencies, jails, and court networks also share enormous volumes of highly sensitive information on US citizens, using woefully inadequate security, and Onionshare could solve their problems too. I hate to think of Tor Network carrying information on behalf of the Surveillance State, but there is no better way of killing off FBI's attacks on onion services than by persuading its local "partners" that since they shouldn't be trying to beat us, they should be pleading for us to help them join us.

I point to the example of Wikipedia as a project which grew from something very tiny (two employees) to something which the whole world regards as an essential resource. In the same way, because Tor Project provides a number of comparatively easy to use cross platform services which solve a broad range of critical infrastructure problems for which no other solutions appear to exist, I believe it now has the potential to make itself equally indispensable.

Of course, enormous growth to Wikipedia scale carries significant risks which TP has never previously confronted, but that would be a suitable topic for discussion in the future. The first task is to work hard to get agencies like SSA willing to seriously consider what onion services have to offer. I suspect that NIST could be very helpful here.

> @ Shari, Micah:
# if it is a private message to @ Shari, Micah: write them with your favorite e-mail or use OnionShare (where is your or their pgp key ? and your photo ?)
# you are boring us with your stupid propaganda
> Wikipedia
# you are boring us with your stupid propaganda
> but there is no better way of killing off FBI's attacks on onion services than by persuading its local "partners" that since they shouldn't be trying to beat us, they should be pleading for us to help them join us.
# you are boring us with your stupid propaganda
Nota Bene : encryption is not a right ; banning, allowing ,regulating, surveying, monitoring, licensing, have nothing to do with the encryption protocol or model or code. It is their infrastructure and their potential client ; the worst was avoided because trump was elected legally-fairly-rightly.

I hope you will reconsider, for at least two reasons:

o TP should not make it so easy for our enemies to censor comments expressing views which they dislike as "make nasty comments and watch Roger shut down the thread"

o You should know by now that I am not as volatile as the... er, cited media personality :-) and am not likely to react to our troll by calling names.

If you are getting many hate comments, this is regrettable, but you should never forget who are the friends and who are the enemies of the Project.

The cyberwoes of SSA are sufficiently glaring to have caught the eye of the Congress:…
How did the government’s technology get so bad?
Joe Uchill
13 Dec 2016

> The Social Security Administration was one of the first groups in government to
adopt a big-data approach to operations. Once an international leader in cutting-edge technology, the administration was “pushing the edge,” said the agency’s chief information officer, Robert Klopp. “ IBM was scrambling to make systems big enough to solve the complex problems we’d pose.” Forty years later, times have changed, and much of the core software running the Social Security Administration is pushing a different kind of edge. Despite decades of improvements to commercial technology that have made it more secure, efficient and cost-effective, the administration uses a core system that is more than 30 years old.

>> The problem is that SSA needs

Another big problem is authentication. This might help:…
This low-cost device may be the world’s best hope against account takeovers
Privacy-preserving “cryptographic assertions” are impossible to guess or phish.
Dan Goodin
23 Dec 2016

>>> The past five years have witnessed a seemingly unending series of high-profile account take-overs. A growing consensus has emerged among security practitioners: even long, randomly generated passwords aren't sufficient for locking down e-mail and other types of online assets. According to the consensus, these assets need to be augmented with a second factor of authentication. Now, a two-year study of more than 50,000 Google employees concludes that cryptographically based Security Keys beat out smartphones and most other forms of two-factor verification.

Let's put an onion in every Social Security office and a keydrive in every pocket!


December 23, 2016


Any chance of getting Onionshare incorporated into Tor Messenger?

(Someone already said that Tails Project is considering incorporating Tor Messenger, which seems to fit with Onionshare to make a very powerful and convenient way for sources to share sensitive files with journalists, or for human rights groups to share information across international boundaries.)