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.

I think the question was about creating a Tor Messenger plugin that automates OnionShare.

I don't see much benefit to that. It's already pretty easy to run OnionShare by itself, and if you're using XMPP over Tor Messenger, you can send files directly to the other user. I assume files are encrypted the same way messages are, be it PGP, OTR, OMEMO, or whatever. I would have to look into it to be sure, but if that's the case, OnionShare would only be advantageous in the event of a passive attack when you're not using end-to-end crypto on the conversation.

> I think the question was about creating a Tor Messenger plugin that automates OnionShare.

Are you referring to the comment which begins

>> Any chance of getting Onionshare incorporated into Tor Messenger?

I didn't have anything specific in mind.

We must always to be careful to make judicious choices between making something user-friendly, making it cross-platform, and making it secure (often three mutually contradictory goals, alas), but I trust Micah to do that well.


December 24, 2016


OnionShare doesn't protect you against bad HSDir relay operators stealing your top secret files.

Actually, it does! To reach the onionshare server and fetch the file, you need to know both the onion address and the rest of the url.

A jerk who runs a relay to learn onion addresses still doesn't learn the url, so he won't be able to reach the file.

Yup! That's why URLs looks like: http://asxmi4q6i7pajg2b.onion/egg-cain

The "egg-cain" part is randomly generated. If you don't know that part, you get a 404 error when you load the URL. And it's rate limited, so it's unfeasible guess it by brute force.

Also, future versions of OnionShare will support stealth onion services, so (if you use them) bad HSDir relay operators won't even be able to attempt reach the 404 page without the HidServAuth cookie.


December 24, 2016


I wanted this tool, but my setup is customized. It would be horrible to allow third party scripts to change my system Tor setups in such a way I don't understand. In onionshare docs everything is explained simply: it makes everything well, it guesses configuration well, and so on, just trust it! But it cannot convince me. Tor is the last mile on my security.

I use separate VM for tor applications, and none of traffic from my machine can bypass Tor because of firewalls. I could run separate two scripts or instructions: one for my VM, to start HTTP server, and another for my host system, creating new hidden service. I didn't find any information how to do it. Certainly I can read the code or create standard onion service to make it working with full understanding, but I would like to see some docs that make it easier.

Can onionshare be used in such cases, where tor and its applications are running in different machines? Since my host system knows my real IP, I don't this it is good idea to use it to run HTTP server (even temporary), I want to run HTTP server in VM.

OnionShare doesn't modify your configuration at all. But it does need access to your Tor control port, because this is necessary to create ephemeral Tor onion services. There's currently an issue to get it working in transparently torified environments like you're describing:

Specifically, it would be great if OnionShare could work in operating systems like Tails and Whonix, and it soon will. (Also, since Ricochet works in a very similar fashion, the same work can be used to make that awesome tool work in Tails and Whonix as well.)

But as far as needing to trust the OnionShare source code, this function is hopefully pretty easy to read, and is the only bit where it tries to find a working Tor control port to connect to:…

It tries port 9151 (Tor Browser), port 9153 (Tor Messenger), and port 9051 (system tor), before it fails. If you set the TOR_CONTROL_PORT environment variable, it will just try that one. Also, in an upcoming version, you'll also be able to set a control port password, so that it will be easier to use OnionShare with your system Tor, without needing to open Tor Browser.

But keep in mind: if you're in a transparently torified environment and your apps can connect to the Tor control port, they can deanonymize you. You need some sort of control port filter software. It might make sense for you to replace your custom setup with Whonix, since it's VM based -- they have put a ton of thought and work into making all of this stuff just work. And while you're at it, you might want to use Qubes, which has Whonix support built-in, and does a much better job at compartmentalization using VMs than anything you can bootstrap onto some other OS.


December 24, 2016


“If you use a filesharing service like Dropbox or Mega or whatever, you basically have to trust them. The file could end up in the hands of law enforcement. This tool lets you bypass all third parties, so that the file goes from one person to another over the Tor network completely anonymously.”
--Micah Lee


December 24, 2016


I feel like Onionshare needs more publicity, I only learned about it in this blog! (also a good "intro" video on youtube would help introducing it)

Yes, that could be an effective way of reaching many more potential users than the readers of this blog.

I am starting to think onionshare could be the "killer app" which enables Tor Project to grow from a tiny NGO to something more the size of Wikipedia. (That kind of growth is not without dangers of its own, but it would certainly tend to blunt our urgent concern that something next year, the Trump administration might simply declare TP an illegal organization, which would be a problem if TP is still registered as a US based entity.)


December 24, 2016



> Here’s how I would have done it: ... all.
OnionShare needs 2 operators but let's try with one :
- so if i let a laptop runs on in a room before taking the plane i could _when i should arrive at rio_ download my files with a link ; so in a way , i download my own files from one of my computer to another mine from 2 different place using onion sharing to bypass "draconian laws". The link is transmitted by pgp on my email account. But i need to let running one computer 10 hours (this travel takes time) and the link must be sent before.

* Does OnionShare run when the computer is in suspend or hibernate mode ?
i do not think so because Tor is not a service running in the background /an intel backdoor (who knows , maybe in a near future or in an unknown past ?).
- But should it possible if i should write a profil in a maintenance mode or a script managing all in cli ?

* Could i short the step and the open-time with the help of some options ?
i would like that :
- tor opens itself then
- onionshare be set up to send the folder i chose by default
- onionshare sends itself the link in my account encrypted with my pgp
- and that one hour after i arrive at rio.
My fist computer runs few minutes , the time to perform some actions automatically and if the timing is well managed i save 10 hours.

* Does a timer script from this model/idea/suggestion break OnionShare or improve it?
* Does a timer script running in suspend or hibernate mode from this model/idea/suggestion break OnionShare or improve it ?

Thank you.


December 24, 2016


I am not a programmer but have been reading the comments anyway for what I can pick up from them.

I'm interested to know why the people who have posted here and expressed concern about government surveillance, or who otherwise feel threatened by some degree of lack of Internet privacy that might, however, serve to protect the general public, view it as such a major concern.

In short, if back doors prevent terrorist attacks it would appear that they may be worth some sacrifice of privacy.

If you're a programmer, and not also a terrorist, how does that threaten you?

Hoo boy. I suggest you go read all the fuss about the Apple backdoor discussion, rather than trying to recreate it here.

Also read…

One of the key things to realize is that backdoors *don't* prevent terrorist attacks. In fact, they do the opposite, because they undermine the security of the system for everyone (because the backdoor is never going to stay only usable by whoever you classify as the good guy). So they harm the innocent people without helping much against the bad guys. And that's even ignoring the question of whose bad guys you want to catch -- the Western-government-mandated "lawful intercept" backdoors in Internet routers are regularly used by e.g. the Saudi regime to spy on their citizens. Also check out the misuses by the Italian and Greek governments to spy on politician's phone calls.

The politicians keep imagining that we can somehow alter reality and build a backdoor that only good guys can use. They are not understanding how software works.

You might enjoy some of the stuff Joe Hall writes at cdt, e.g.…

Hope this helps! :)

You 'prove' that "backdoors *don't* prevent terrorist attacks" by claiming that they also "harm the innocent people" (without explaining how). That's a non-sequitur. How do you know that it hasn't prevented any terrorist attacks? How many would it have to prevent for you to consider it worthwhile? (Wouldn't even one be enough?)

I don't think building "a backdoor that only good guys can use" is the point. If the information back doors provide is used in good faith, investigators will have their hands full in the pursuit of terrorists and other criminals. They are not going to concern themselves with innocuous communications.

There is always the danger that nefarious parties will abuse this, i.e., not act in good faith. So, as with anything else in the relations between government and citizens, there has to be checks and balances.

I don't, however, see surveillance of the kind that's in effect or anticipated here under Trump as an automatic conduit to a totalitarian society or to harm of the innocent. (I'm also not concerned about what happens in Saudi Arabia or other places where abuse is the norm. We can't ensure virtue in the rest of the world, but we can make a serious attempt at it here, including in the application of surveillance.)

Unlike some websites, here you can expect responses from thoughtful people who know about technology/software and who are accustomed to using statistical theory to make "evidence based" decisions. And to harshly criticizing technical flaws in hardware/software, "dirty" data, overblown statistical claims, and faulty "evidence-based" procedures.

> How do you know that it hasn't prevented any terrorist attacks? How many would it have to prevent for you to consider it worthwhile? (Wouldn't even one be enough?)

Dramatic appeals to unvalidated fears of a poorly specified hypothetical event? No, that is not at all how honest risk assessment works. Let us know if you are willing to learn how a state-of-the-art (but "conservative" rather than "wild bleeding edge") risk assessment procedure would begin looking at this problem. Or you can just read the widely admired award winning paper

Susan Landau et al., Keys Under Doormats, MIT CSAIL, Jul 2015

(Available online, better for you to search for it than for me to provide a link which might not work for you.)

Sounds like you have not read any of Bruce Schneier's superbly written, wide ranging, and enormously useful books on security issues, including both cybersecurity and physical security. If you want to discuss "encryption backdoors" or "terrorism" here, you probably should.

Without intending to imply anything about the psychology or world view of OP:

Here is a very short article (reprinted from Scientific American) which should be useful reading for anyone who arguing with someone who appears to be unshakably convinced that "global warming is fake news invented by Putin" [sic], "I'm not doing anything wrong so I don't need no stinking privacy!" [sic], "the government should be able to access any device or data", etc.:…
No ad hominem, no ad Hitlerum: How to convince someone when facts fail
Why worldview threats undermine evidence
Michael Shermer, Scientific American
26 Dec 2016

Please note:

o the worldview which is threatened by the continued existence of strong civilian encryption, Tor, Tails, OnionShare, Tahoe-LAFS, etc, is essentially authoritarian and nationalistic,

o in this subthread, we are still at the stage of presenting facts to the OP in hope of changing minds one or two at a time.

You have heard that FBI wants to outlaw strong citizen cryptography by mandating the insertion of "backdoors".

You say you don't understand why every cryptographer on the face of the planet says that is a terrible idea. Here is an authoritative prize-winning white paper which answers your question:

Susan Landau et al., Keys Under Doormats, MIT CSAIL, Jul 2015

Another way to understand why "backdoors" into encrypted communications, social media accounts, etc, are a terrible idea is to learn what governments which have already outlawed strong cryptography have done with their own backdoors. So please read next a random selection of reports at

Since you appeared to cite the hoary "I'm not doing anything wrong, so I have nothing to hide" fallacy, please read these essays:………

But it's also crucially important to understand further implications of the dragnet which are not likely to have occurred to anyone who believes "I'm not doing anything wrong, so I have nothing to hide", so please read these authoritative whitepapers:

John Villasenor, Recording Everything, Brookings, Dec 2011

Internet Enemies, Reporters without Borders, 2012

Walter Perry et al., Predictive Policing, RAND, 2013

Michael Price, National Security and Local Police, Brennan Center, 2013

Paul Davis et. al, Using Behavioral Indicators to Detect Potential Violent Acts, RAND, 2013

Frank La Rue, Report of the Special Rapporteur, UN General Assembly, Apr 2013

Tim Maurer et al, Uncontrolled Global Surveillance, New America Foundation, Mar 2014

Pam Dixon and Robert Gellman, Scoring of America, World Privacy Forum, Apr 2014

John Podesta et al., Big Data, White House, May 2014

These are available on-line (try duckduckgo and keep looking; the ones behind paywalls can be found elsewhere):


o Brookings, yes, the US NGO which US President Richard Nixon wanted to firebomb,

o RAND: yes, the defense contractor; sometimes they say smart things such as "the mission of NCTC is mathematically impossible", in which case USG ignores their own advisors,

o White House: yes, the House of War Criminals; sometimes they do good by accident,

o Podesta: yes, the same guy who ignored warnings his email inbox had been breached.

You appeared to cite the hoary "security or privacy is a binary choice" fallacy. So you should read some books which debunk that misconception.

You also appeared to hint at a belief that USIC and LEAs are working to protect the ordinary citizen. So you should read some books which debunk that misconception.

So here are some books I think you should read, listed by my own short summaries of the relevant thesis of each book:

o surveillance/security not a binary choice:

Susan Landau, Surveillance or Security?, MIT Press, 2010

o CIA is utterly utterly incompetent and purely evil:

Tim Weiner, Legacy of Ashes, Anchor, 2007

o CIA is a state-sponsored collective of war-criminals:

Stephen Grey, Ghost Plane, St. Martin's Press, 2006

o FBI is utterly incompetent and purely evil (plus, why FBI hates ACLU so much):

Tim Weiner, Enemies, Random House, 2012

o NSA is purely evil, terrifyingly powerful, but no means invincible:

James Bamford, The Puzzle Palace

James Bamford, Body of Secrets, Anchor, 2002

James Bamford, The Shadow Factory, Doubleday, 2008

Matthew Aid, The Secret Sentry, Bloomsbury, 2009

o it helps to know your enemy, so read this book NSA didn't want to be published:

David Kahn, The Codebreakers, MacMillan, 1967

o much better to be a good guy than a bad guy:

Steven Levy, crypto, Viking, 2001

o malware-as-a-service companies such as Gamma and Hacking Team are pure evil:

Ronald Deibert, Black Code, Random House, 2013

o militarized policing is stupid and self-destructive:

Radley Balko, Rise of the Warrior Cop, Public Affairs, 2014

o military =/= strength, nations which tolerate povery are doomed for death:

Catherine Bestemen and Hugh Gusterson (eds), The Insecure American, UC Press, 2010

o Corporate surveillance is pervasive, dehumanizing, and terribly dangerous:

Julia Angwin, Dragnet Nation, Henry Holt, 2014

o Surveillance generally is pervasive, dehumanizing, and terribly dangerous:

Christian Parenti, The Soft Cage, Basic Books, 2003

Bruce Schneier, Data and Goliath, Norton & Norton, 2015

o the confluence of government/corporate dragnets with Big Data is terrifying:

Cathy O'Neill, Weapons of Math Destruction, Crown, 2016

o the greatest danger of all: CVE and real-time-auto-updated robotic "citizenship" scoring:

(!!! No book has yet appeared on CVE programs !!!)

That's partly my fault. Shari posted the blog post originally, then I made a blog account so Micah can answer comments, and I swapped his name in as the author so his comments would have boxes around them.

I think leaving that line in isn't so bad. :)


December 26, 2016


It seems that if you have contrib section in your repositories, you still need to add Micah's key to APT before you can install onionshare. I haven't experienced this with other packages in contrib and hope the reason why is *not* that contrary to my naive expectations, Debian allows people to install unauthenticated software without warning.

Does anyone know the reason?

One of the depedencies drawn in startled me: python-isdangerous. Even after reading the description of what it actually does, I remained nervous.

Can anyone convince me I'm just being silly?


December 28, 2016


using a free o.s means that :
° you are involved in the philosophy, in the development,being a part of the community etc.
° you know & understand that you are doing
° as soon as you change the default parameters you are out of the original o.s
° you are free to manage, tweak, copy, share etc like you want and install all you want : it is up to you.
° you must not install a soft without gpg-key - it is especially true about tor (you download from their site & verify it)
° ... look at the first sentence written on your terminal ...
*** debian does not include contrib/free section & the reason why Debian allows people to install unauthenticated software without silly : you are the admin of your system & the owner of yours personal *o.s , you do decide and even could built your own from scratch.
*** if you think that python is a bad d habit of dev ; you could ask them to develop their in another language or in a different way with no-python dependencies ; donations are welcome.

Twas asked:

> Does anyone know the reason?

You replied (yes?)

>> using a free o.s means that :
>> ° you are involved in the philosophy, in the development,being a part of the community etc.
>> ° you know & understand that you are doing

You did not answer the question. Instead you quoted your summary of a peculiarly outdated view of what the Open Source software movement is all about.

I feel it makes no sense to insist that people who develop/use such software are somehow prohibited from modifying their philosophy to take account of a political/technical environment which in many ways is dramatically different from the times when the first statements of "Open Source philosophy" appeared. Those were statements of what early enthusiasts hoped OS could become, not accurate descriptions of what it has become.

The claim that everyone who uses open source software "must know what they are doing" is particularly absurd. The fact is, most people who use OS software do so out of necessity or convenience, are not coders, and try to get by reading a minimum of documentation. That may not conform to your ideal, but it does conform to reality. In my view, it is not very smart to try to insist that reality conform to your ideal, rather than modifying your ideal to take account of reality. An ideal can only be effective as a guiding principle if it takes account of current hard truths.

That is a big misunderstood : we are speaking on the Tor blog about onionshare !!!

Misunderstood : it is not about Open Source software movement
It is about debian & install it & update & manage it like you want (it is written every where in all the manual & doc for every operating system which are not microsoft or mac/o.s).
>> ° you know & understand that you are doing means you are using the terminal and like it is written the first time you open it ... But are you running a Debian ?
>> using a free o.s means that : you are involved in the philosophy, in the development,being a part of the community etc.
Of course ! As soon as you are in , you tweak, install,test,try,manage,update you are your own admin : an important user whom every question is relevant,important ...

You do not understand the post & the answer : it is about installing a soft without a pgp key not discussing about the foundation of a movement, or the difference between the past and the future, or the user and the coder or an ideal as a philosophy !

That is a big misunderstood : we are speaking on the Tor blog about onionshare !!!
<> I haven't experienced this with other packages in contrib and hope the reason why is *not* that contrary to my naive expectations, Debian allows people to install unauthenticated software without warning. Does anyone know the reason?
YES, the reason why is that you are the admin you decide : it is one of the advantage, rule of being a part of the community of using debian.
Every user of linux have understood immediately what it was about of course !!!

@ Peter P or other Debian Project developers:

It seems that this commentator is claiming that when a Debian user installs a deb from the contrib section, this software is installed without any authentication.

Is that true?

Can someone who knows please answer the question, with a citation to if possible?



January 07, 2017


Any reason why onionshare shouldn't install ubuntu 16.10 ? blowing errors ?

Some packages could not be installed. This may mean that you have
requested an impossible situation or if you are using the unstable
distribution that some required packages have not yet been created
or been moved out of Incoming.
The following information may help to resolve the situation:

The following packages have unmet dependencies:
onionshare : Depends: python3-flask but it is not going to be installed
E: Unable to correct problems, you have held broken packages.

fresh OS install


January 07, 2017


Hi Micah, first of all my respect and thankfulness for developing such a tool.
Is there of will there be the possibility to use OnionShare with Tails OS as a standard application



January 26, 2017


Tails 2.10 was just released ( and as promised above, it offers OnionShare!

This is an exciting development for Tails advocates, since it should help to convince medical providers, lawyers, reporters, scientists, and yes, government agencies (especially small ones with no cybersecurity expertise) to adopt Tails and OnionShare for the ad hoc sharing of files in a well secured manner.

Adam Tanner, Our Bodies Our Data, Beacon Press, 2017 offers a good (but very incomplete) suggestion of the kinds of endemic cyber-insecurities which affect essentially all "covered entities" in the US (health insurers, state health care authorities, clinics, business associates such as companies hired to provide "secure" [hah!] servers, etc). In particular, it is standard practice in the US for providers who need to share files on a common patient to transmit medical records by unencrypted fax transmission. OnionShare would be an infinitely superior method of carrying out such a common task.


January 26, 2017


@ Micah Lee:

Might I suggest a topic for a Tor blog post?

Explainer on how to use OnionShare and Tor Messenger to share files on an adhoc basis.

Would this work?

Use Tor Messenger to meet in a chat room, start an encrypted private one-one chat, use OnionShare to set up a temporary onion service, share the address of the temporary onion service in the encrypted chat, then when the second party confirms in the chat that they downloaded the file, the first party can immediately take down the temporary onion service.

If so, this would be much easier once Tor Messenger is also included in Tails.