Skip to main content

The ".onion" Special-Use Domain Name

The information below is for an old version of the document that is already published as an RFC.
Document Type
This is an older version of an Internet-Draft that was ultimately published as RFC 7686.
Authors Jacob Appelbaum , Alec Muffett
Last updated 2021-12-01 (Latest revision 2015-09-09)
Replaces draft-appelbaum-dnsop-onion-tld
RFC stream Internet Engineering Task Force (IETF)
Additional resources Mailing list discussion
Stream WG state Submitted to IESG for Publication
Document shepherd Tim Wicinski
Shepherd write-up Show Last changed 2015-06-20
IESG IESG state RFC 7686 (Proposed Standard)
Consensus boilerplate Yes
Telechat date (None)
Responsible AD Joel Jaeggli
Send notices to (None)
IANA IANA review state Version Changed - Review Needed
IANA action state RFC-Ed-Ack
dnsop                                                       J. Appelbaum
Internet-Draft                                      The Tor Project, Inc
Intended status: Standards Track                              A. Muffett
Expires: March 12, 2016                                         Facebook
                                                       September 9, 2015

                   The .onion Special-Use Domain Name


   This document registers the ".onion" Special-Use Domain Name.

Status of This Memo

   This Internet-Draft is submitted in full conformance with the
   provisions of BCP 78 and BCP 79.

   Internet-Drafts are working documents of the Internet Engineering
   Task Force (IETF).  Note that other groups may also distribute
   working documents as Internet-Drafts.  The list of current Internet-
   Drafts is at

   Internet-Drafts are draft documents valid for a maximum of six months
   and may be updated, replaced, or obsoleted by other documents at any
   time.  It is inappropriate to use Internet-Drafts as reference
   material or to cite them other than as "work in progress."

   This Internet-Draft will expire on March 12, 2016.

Copyright Notice

   Copyright (c) 2015 IETF Trust and the persons identified as the
   document authors.  All rights reserved.

   This document is subject to BCP 78 and the IETF Trust's Legal
   Provisions Relating to IETF Documents
   ( in effect on the date of
   publication of this document.  Please review these documents
   carefully, as they describe your rights and restrictions with respect
   to this document.  Code Components extracted from this document must
   include Simplified BSD License text as described in Section 4.e of
   the Trust Legal Provisions and are provided without warranty as
   described in the Simplified BSD License.

Appelbaum & Muffett      Expires March 12, 2016                 [Page 1]
Internet-Draft                   .onion                   September 2015

Table of Contents

   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   2
     1.1.  Notational Conventions  . . . . . . . . . . . . . . . . .   3
   2.  The ".onion" Special-Use Domain Name  . . . . . . . . . . . .   3
   3.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .   4
   4.  Security Considerations . . . . . . . . . . . . . . . . . . .   4
   5.  References  . . . . . . . . . . . . . . . . . . . . . . . . .   5
     5.1.  Normative References  . . . . . . . . . . . . . . . . . .   5
     5.2.  Informative References  . . . . . . . . . . . . . . . . .   6
   Appendix A.  Acknowledgements . . . . . . . . . . . . . . . . . .   6
   Authors' Addresses  . . . . . . . . . . . . . . . . . . . . . . .   6

1.  Introduction

   The Tor network [Dingledine2004] has the ability to host network
   services using the ".onion" Special-Use Top-Level Domain.  Such names
   can be used as other domain names would be (e.g., in URLs [RFC3986]),
   but instead of using the DNS infrastructure, .onion names
   functionally correspond to the identity of a given service, thereby
   combining location and authentication.

   .onion names are used to provide access to end to end encrypted,
   secure, anonymized services; that is, the identity and location of
   the server is obscured from the client.  The location of the client
   is obscured from the server.  The identity of the client may or may
   not be disclosed through an optional cryptographic authentication

   .onion names are self-authenticating, in that they are derived from
   the cryptographic keys used by the server in a client-verifiable
   manner during connection establishment.  As a result, the
   cryptographic label component of a .onion name is not intended to be

   The Tor network is designed to not be subject to any central
   controlling authorities with regards to routing and service
   publication, so .onion names cannot be registered, assigned,
   transferred or revoked.  "Ownership" of a .onion name is derived
   solely from control of a public/private key pair which corresponds to
   the algorithmic derivation of the name.

   In this way, .onion names are "special" in the sense defined by
   [RFC6761] Section 3; they require hardware and software
   implementations to change their handling in order to achieve the
   desired properties of the name (see Section 4).  These differences
   are listed in Section 2.

Appelbaum & Muffett      Expires March 12, 2016                 [Page 2]
Internet-Draft                   .onion                   September 2015

   Like Top-Level Domain Names, .onion names can have an arbitrary
   number of subdomain components.  This information is not meaningful
   to the Tor protocol, but can be used in application protocols like
   HTTP [RFC7230].

   Note that .onion names are required conform to DNS name syntax (as
   defined in Section 3.5 of [RFC1034] and Section 2.1 of [RFC1123]), as
   they will still be exposed to DNS implementations.

   See [tor-address] and [tor-rendezvous] for the details of the
   creation and use of .onion names.

1.1.  Notational Conventions

   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   document are to be interpreted as described in [RFC2119].

2.  The ".onion" Special-Use Domain Name

   These properties have the following effects upon parties using or
   processing .onion names (as per [RFC6761]):

   1.  Users: Human users are expected to recognize .onion names as
       having different security properties (see Section 1), and also as
       being only available through software that is aware of onion

   2.  Application Software: Applications (including proxies) that
       implement the Tor protocol MUST recognize .onion names as special
       by either accessing them directly, or using a proxy (e.g., SOCKS
       [RFC1928]) to do so.  Applications that do not implement the Tor
       protocol SHOULD generate an error upon the use of .onion, and
       SHOULD NOT perform a DNS lookup.

   3.  Name Resolution APIs and Libraries: Resolvers MUST either respond
       to requests for .onion names by resolving them according to
       [tor-rendezvous] or by responding with NXDOMAIN.

   4.  Caching DNS Servers: Caching servers, where not explicitly
       adapted to interoperate with Tor, SHOULD NOT attempt to look up
       records for .onion names.  They MUST generate NXDOMAIN for all
       such queries.

   5.  Authoritative DNS Servers: Authoritative servers MUST respond to
       queries for .onion with NXDOMAIN.

Appelbaum & Muffett      Expires March 12, 2016                 [Page 3]
Internet-Draft                   .onion                   September 2015

   6.  DNS Server Operators: Operators MUST NOT configure an
       authoritative DNS server to answer queries for .onion.  If they
       do so, client software is likely to ignore any results (see

   7.  DNS Registries/Registrars: Registrars MUST NOT register .onion
       names; all such requests MUST be denied.

   Note that the restriction upon the registration of .onion names does
   not prohibit IANA from inserting a record into the root zone database
   to reserve the name.

   Likewise, it does not prevent non-DNS service providers (such as
   trust providers) from supporting .onion names in their applications.

3.  IANA Considerations

   This document registers "onion" in the registry of Special-Use Domain
   Names [RFC6761].  See Section 2 for the registration template.

4.  Security Considerations

   The security properties of .onion names can be compromised if, for

   o  The server "leaks" its identity in another way (e.g., in an
      application-level message), or

   o  The access protocol is implemented or deployed incorrectly, or

   o  The access protocol itself is found to have a flaw.

   Users must take special precautions to ensure that the .onion name
   they are communicating with is the intended one, as attackers may be
   able to find keys which produce service names that are visually or
   semantically similar to the desired service.  This risk is magnified
   because .onion names are typically not human-meaningful.  It can be
   mitigated by generating human meaningful .onion names (at
   considerable computing expense), or through users using bookmarks and
   other trusted stores when following links.

   Also, users need to understand the difference between a .onion name
   used and accessed directly via Tor-capable software, versus .onion
   subdomains of other top-level domain names and providers (e.g., the
   difference between example.onion and example.onion.tld).

   The cryptographic label for a .onion name is constructed by applying
   a function to the public key of the server, the output of which is

Appelbaum & Muffett      Expires March 12, 2016                 [Page 4]
Internet-Draft                   .onion                   September 2015

   rendered as a string and concatenated with the string ".onion".
   Dependent upon the specifics of the function used, an attacker may be
   able to find a key that produces a collision with the same .onion
   name with substantially less work than a cryptographic attack on the
   full strength key.  If this is possible the attacker may be able to
   impersonate the service on the network.

   A legacy client may inadvertently attempt to resolve a ".onion" name
   through the DNS.  This causes a disclosure that the client is
   attempting to use Tor to reach a specific service.  Malicious
   resolvers could be engineered to capture and record such leaks, which
   might have very adverse consequences for the well-being of the Tor
   user.  This issue is mitigated if the client's Tor software is
   updated to not leak such queries, or if the client's DNS software is
   updated to drop any request to the ".onion" TLD.

5.  References

5.1.  Normative References

              Dingledine, R., Mathewson, N., and P. Syverson, "Tor: the
              second-generation onion router", 2004,

   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/
              RFC2119, March 1997,

   [RFC6761]  Cheshire, S. and M. Krochmal, "Special-Use Domain Names",
              RFC 6761, DOI 10.17487/RFC6761, February 2013,

              Mathewson, N. and R. Dingledine, "Special Hostnames in
              Tor", September 2001, <

              Mathewson, N. and R. Dingledine, "Tor Rendezvous
              Specification", April 2014, <

Appelbaum & Muffett      Expires March 12, 2016                 [Page 5]
Internet-Draft                   .onion                   September 2015

5.2.  Informative References

   [RFC1034]  Mockapetris, P., "Domain names - concepts and facilities",
              STD 13, RFC 1034, DOI 10.17487/RFC1034, November 1987,

   [RFC1123]  Braden, R., Ed., "Requirements for Internet Hosts -
              Application and Support", STD 3, RFC 1123, DOI 10.17487/
              RFC1123, October 1989,

   [RFC1928]  Leech, M., Ganis, M., Lee, Y., Kuris, R., Koblas, D., and
              L. Jones, "SOCKS Protocol Version 5", RFC 1928, DOI
              10.17487/RFC1928, March 1996,

   [RFC3986]  Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
              Resource Identifier (URI): Generic Syntax", STD 66, RFC
              3986, DOI 10.17487/RFC3986, January 2005,

   [RFC7230]  Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
              Protocol (HTTP/1.1): Message Syntax and Routing", RFC
              7230, DOI 10.17487/RFC7230, June 2014,

Appendix A.  Acknowledgements

   Thanks to Roger Dingledine, Linus Nordberg, and Seth David Schoen for
   their input and review.

   This specification builds upon previous work by Christian Grothoff,
   Matthias Wachs, Hellekin O.  Wolf, Jacob Appelbaum, and Leif Ryge to
   register .onion in conjunction with other, similar Special-Use Top-
   Level Domain Names.

Authors' Addresses

   Jacob Appelbaum
   The Tor Project, Inc


   Alec Muffett


Appelbaum & Muffett      Expires March 12, 2016                 [Page 6]