RFC 7686

Abstract

okay so this whole doc is basically about one thing: it registers the ".onion" Special-Use Domain Name 🧅✨ iconic, right?

Status of This Memo

this is an Internet Standards Track document 🎀

it's a product of the Internet Engineering Task Force (IETF), so it represents the consensus of the IETF community. it got public review and was approved for publication by the Internet Engineering Steering Group (IESG). if you want more on Internet Standards, check Section 2 of RFC 5741 💅

for the current status, any errata, and how to send feedback, go to http://www.rfc-editor.org/info/rfc7686 🌸

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 (http://trustee.ietf.org/license-info) as they stand on the publication date. please actually read those, bestie, because they spell out your rights and restrictions for this document 🙈 any Code Components pulled out of this doc must include Simplified BSD License text, as described in Section 4.e of the Trust Legal Provisions, and they come without warranty, as described in the Simplified BSD License 📜

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
Acknowledgements  . . . . . . . . . . . . . . . . . . . . . . . .   6
Authors' Addresses  . . . . . . . . . . . . . . . . . . . . . . .   7

---

1. Introduction ✨

okay so the Tor network [Dingledine2004] can host network services under the ".onion" Special-Use Top-Level Domain Name 🧅 these names work like any other domain name would, say in URLs [RFC3986], except they don't go through DNS infrastructure. instead, a .onion name maps to the identity of a given service, so it combines location and authentication in one go 💖

.onion names are used to reach end to end encrypted, secure, anonymized services. the identity and location of the server are hidden from the client, and the client's location is hidden from the server 🙈 the client's identity may or may not be revealed, depending on an optional cryptographic authentication process.

.onion names are self-authenticating. they're derived from the cryptographic keys the server uses, in a way the client can verify during connection establishment 🔐 which means the cryptographic label part of a .onion name isn't meant to be human-meaningful. it's giving math, not vibes 💀

the Tor network is designed so that no central controlling authority is in charge of routing or service publication. that means .onion names can't be registered, assigned, transferred, or revoked 😭 "ownership" of a .onion name comes purely from controlling the public/private key pair that the name is algorithmically derived from. main character energy, but make it cryptography 👑

so .onion names are "special" in the sense defined in Section 3 of [RFC6761]. they need hardware and software implementations to change how they handle the name, so the name gets the properties it's supposed to have (see Section 4). those differences are listed in Section 2 🦋

like other Top-Level Domain Names, .onion names can have any number of subdomain components. the Tor protocol doesn't care about that information, but application protocols like HTTP [RFC7230] can use it 🌈

also, .onion names are required to follow DNS name syntax (as defined in Section 3.5 of [RFC1034] and Section 2.1 of [RFC1123]), because they'll still be exposed to DNS implementations 🫶

for the details on how .onion names are created and used, see [tor-address] and [tor-rendezvous] ✨

1.1. Notational Conventions

the key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be read as described in [RFC2119] 📖

---

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

these properties affect anyone using or processing .onion names (as per [RFC6761]). here's the breakdown:

1. Users: human users are expected to recognize that .onion names have different security properties (see Section 1), and that they only work through software that knows about .onion names 🧚
2. Application Software: applications (including proxies) that implement the Tor protocol MUST recognize .onion names as special, either by accessing them directly or by going through a proxy (e.g., SOCKS [RFC1928]) 💅 applications that don't implement the Tor protocol SHOULD throw an error when they hit .onion, and they SHOULD NOT do a DNS lookup 🙈
3. Name Resolution APIs and Libraries: resolvers MUST either resolve .onion names according to [tor-rendezvous], or respond with NXDOMAIN [RFC1035] 🔥
4. Caching DNS Servers: unless they've been explicitly adapted to work with Tor, caching servers SHOULD NOT try to look up records for .onion names. they MUST return NXDOMAIN for all such queries 💀
5. Authoritative DNS Servers: authoritative servers MUST respond to queries for .onion with NXDOMAIN 👑
6. DNS Server Operators: operators MUST NOT configure an authoritative DNS server to answer queries for .onion. if they do, client software is likely to ignore whatever results come back (see above) 😭
7. DNS Registries/Registrars: registrars MUST NOT register .onion names, and every such request MUST be denied 🛑

note that the restriction on registering .onion names doesn't stop IANA from putting a record into the root zone database to reserve the name 🌈

and likewise, it doesn't stop non-DNS service providers (such as trust providers) from supporting .onion names in their applications 🦋

and that's the end of part 1, bestie! 💜 part 2 picks up with Section 3 (IANA Considerations) and keeps going from there 🎀

Acknowledgements 🫶

Huge thanks to Roger Dingledine, Linus Nordberg, and Seth David Schoen for their input and review. They really showed up for this one 💖

This spec is standing on the shoulders of giants 🦋 Christian Grothoff, Matthias Wachs, Hellekin O. Wolf, Jacob Appelbaum, and Leif Ryge did earlier work to register .onion alongside other similar Special-Use Top-Level Domain Names, and that groundwork is what made this possible ✨

---

Authors' Addresses 💌

Jacob Appelbaum 🧚 The Tor Project, Inc. & Technische Universiteit Eindhoven Email: jacob@appelbaum.net

Alec Muffett 🌸 Facebook Email: alecm@fb.com