Onion Service version 2 deprecation timeline

From today (July 2nd, 2020), the Internet has around 16 months to migrate from onion services v2 to v3 once and for all.


More than 15 years ago, Onion Service (at the time named Hidden Service) saw the light of day. It was initially an experiment in order to learn more on what the Tor Network could offer. The protocol reached its version 2 soon after deployment.

Over the years, onion services evolved and version 2 developed into a strong stable product that has been used for over a decade now. During all those years, onion service adoption increased drastically. From the .onion tld being standarized by ICANN, to SSL certificates being issued to .onion addresses. Onion services these days support a whole ecosystem of client applications: from web browsing to file sharing and private messaging.

As humankind's understanding of math and cryptography evolved, the foundation of version 2 became fragile and at this point in time, unsafe. If you want to read more about the technical problems that version 2 faces, please read this post and don't hesitate to ask questions if any.

Which lead us to 2015: a large scale development effort spanning over 3 years resulted in version 3. On January 9th 2018, Tor version was released which was the first tor supporting onion service version 3. And I bet you've encountered them, they have 56 characters and end in .onion ;).

Every single relay on the Tor Network now supports version 3. It is also today's default version when creating an onion service.

With onions v3 standing strong, we are at a good position to retire version 2: Version 2 has completed its course. Run its circle it has provided security and privacy to countless people around the world. But more importantly, it has created and propulsed a new era of private and secure communication.


Here is our planned deprecation timeline:

  1. September 15th, 2020
    0.4.4.x: Tor will start warning onion service operators and clients that v2 is deprecated and will be obsolete in version 0.4.6.
  2. July 15th, 2021
    0.4.6.x: Tor will no longer support v2 and support will be removed from the code base.
  3. October 15th, 2021
    We will release new Tor client stable versions for all supported series that will disable v2.

This effectively means that from today (July 2nd, 2020), the Internet has around 16 months to migrate from v2 to v3 once and for all.

We'll probably run into some difficulties here; no matter how prepared we think we are, we find that there are always more surprises. Nonetheless, we'll do our best to fix problems as they come up, and try to make this process as smooth as possible.

Transition from v2 to v3

This section details how to setup a v3 service from your existing v2 service. Unfortunately, there is no mechanism to cross-certify the two addresses.

In torrc, to create a version 3 address, you simply need to add these two lines. The default version is now set to 3 so you don't need to explicitly set it.

HiddenServiceDir /full/path/to/your/hs/v3/directory/  
HiddenServicePort <virtual port> <target-address>:<target-port>

Finally, if you wish to keep running your version 2 service until it is deprecated to provide a transition path to your users, add this line to the configuration block of your version 2 service:

HiddenServiceVersion 2

This will allow you to identify in your configuration file which one is which version.

Good Luck with the migration.

From:On DarkNet – Dark Web News and Analysis
Copyright of the article belongs to the author, please do not reproduce without permission.

<<Pre Post
Next Post>>