{"canonical_url":"https://engineer.company/glossary/onion/","content_markdown":"# Onion service\n\n## What it is\n\nAn onion service is a server that readers reach inside the Tor network by a name built from the\nserver's own public key, instead of a DNS name that points at an IP address. People often shorten\nit to an onion, one tor daemon can run several onion services side by side, and the specification\nstill uses the older name, hidden service.\n\nThe name is 56 characters of base32 followed by `.onion`. Decoded, it is 35 bytes: the service's\n32-byte ed25519 identity key, a two-byte checksum taken from a SHA3-256 hash of that key, and a\nversion byte set to 3. Because that byte comes last, every current address ends in the letter d.\nNobody chooses the label; it is the key written out. The version 2 names before it were 16\ncharacters cut from a SHA-1 hash of an RSA-1024 key, and tor dropped them in release\n0.4.6.1-alpha, in 2021.\n\nReaching the service takes two meeting places. The service picks a few relays as introduction\npoints, keeps circuits open to them, and uploads a signed descriptor listing them to directory\nrelays. The descriptor is filed under a blinded key that changes each period and its body is\nencrypted, so a relay storing it without knowing the address cannot read the list. A client that\nholds the address fetches the descriptor, checks the signature against the key in the name, picks\na relay as rendezvous point, and asks the service through an introduction point to meet there. The\nservice builds its own circuit to that relay and completes the handshake, and the relay joins the\ntwo circuits. The path crosses six relays, three chosen by each side, and neither end learns the\nother's IP address. An optional mode, now called restricted discovery and formerly client\nauthorization, also encrypts the descriptor for each authorised client's key, so only those\nclients learn where the introduction points are.\n\n## Why it matters\n\nThe name does the job that DNS and a certificate authority share for an ordinary site, and needs\nneither. Verifying the descriptor, and completing the handshake, tells the client that it is\ntalking to whoever holds the private key behind the address. RFC 7686, which reserves `.onion` as\na special-use domain name, describes such names as combining location and authentication, and\ndraws the consequence: an onion name cannot be registered, assigned, transferred or revoked.\nOwning one means controlling the key pair, nothing more.\n\nEncryption comes from the same design. Traffic to an onion service never leaves the Tor network,\nso there is no exit relay at the far end and no last stretch in plain text. Plain `http://` on an\nonion therefore carries a page encrypted end to end, to a host whose identity the client checked\nagainst the name it typed.\n\nThe service only ever dials out, to its introduction points and to each rendezvous point, so it\nneeds no open inbound port and works behind NAT. Adding an onion leaves the host's list of open\nports as it was.\n\nReaders still have to learn the address. A site can announce it with an `Onion-Location` response\nheader, and Tor Browser then shows a purple pill in the address bar leading to the onion copy of\nthe page. The Tor Project sets three conditions: the value is an `http:` or `https:` URL with an\nonion host, the page sending it arrived over HTTPS, and that page is not itself on an onion. A\nmeta tag can carry the same announcement where headers cannot be set, but without the path, so\nevery page points at one fixed URL.\n\n## What it looks like in practice\n\n[Publishing the company's onion mirror under a readable address](/portfolio/published-a-readable-tor-onion-mirror/)\nis written up step by step. The daemon comes from the distribution's own package, with its\noutbound proxy port switched off. The private key behind the address was generated off the\nhost and has never reached the repository or a laptop; the role declines to overwrite an identity\nit did not generate, so a key placed by hand is used as it is. The address is a declared value in\nthe inventory, and every converge asserts that the identity file on the host matches it, so a\nswapped key with a stale declaration stops the run. Both secret guards catch the key file, after a\nmeasurement showed that the obvious key-file pattern matched a deploy key and missed this one.\n\nA readable prefix can be found but never chosen. Each extra character multiplies the expected\nsearch by 32, so the eight letters of `engineer` take about 1.1 trillion keypairs on average.\nRetiring the random address the mirror first shipped with was a staged cutover, so the published\naddress kept answering throughout. One step looked final and was not: the key landed, the converge\nreported no change, and the new address stayed unpublished because nothing named its directory.\nThe role now fails on any identity on disk that no service names.\n\n[The credits page](/credits/) prints the full address,\n`engineer2ezpeji52ipphljcflzyhetvy5r6tnqubtq45nzlxxv6rsqd.onion`, beside the Gemini and Gopher\nones. The four front doors share one folder of files and one deploy, so none of them can drift\nfrom the others, and the ordinary site sends `Onion-Location` so Tor Browser offers the onion\nunprompted. What the reader's own network sees depends on the door: over Gopher, which page is\nread; over Gemini, which address was asked for; over the onion, neither. The readable prefix is a\nconvenience rather than a proof, so the whole address is the part to compare.\n\nThe address's structure can be checked offline. These lines decode it and recompute the checksum,\nand both comparisons print `True`:\n\n```python\nimport base64\nimport hashlib\n\nlabel = \"engineer2ezpeji52ipphljcflzyhetvy5r6tnqubtq45nzlxxv6rsqd\"\nraw = base64.b32decode(label.upper())\nkey, checksum, version = raw[:32], raw[32:34], raw[34:]\ndigest = hashlib.sha3_256(b\".onion checksum\" + key + version).digest()\nprint(version == b\"\\x03\", digest[:2] == checksum)\n```\n\nA valid checksum shows that the address is well formed, not whose it is. That part comes from\nreading it on the company's own HTTPS pages.\n\n## Where it goes wrong\n\n**The key is the only deed.** With no registrar behind the name, a lost private key means a lost\naddress, and a copied one lets someone else answer at it. The Tor Project's setup guide says to\nkeep the key files private and to back the key up if the service is meant to last. Treat it as a\nsigning key, not configuration.\n\n**Reading only the first letters.** RFC 7686 warns that an attacker can find keys whose names look\nlike the intended one, and that the risk is larger because the names mean nothing to a person. It\ncounts readable names, bought with considerable computing, as one remedy, but a prefix of eight\ncharacters leaves the other 48 as opaque as before. Compare the whole address, or arrive through a\nbookmark or a link on the site's own HTTPS pages.\n\n**The server names itself.** Tor hides where the service runs, but the software behind it can\nstill say. RFC 7686 lists a server leaking its identity in an application-level message among the\nways the protection fails, and an error page printing the machine's real hostname is one. The\nsetup guide also recommends passing traffic to the web server over a Unix socket rather than TCP,\nso the service does not leak onto the local network:\n\n```text\nHiddenServiceDir /var/lib/tor/my-website/\nHiddenServicePort 80 unix:/var/run/tor/my-website.sock\n```\n\nIt matters most where the location itself is the secret.\n\n**The name goes to DNS.** Software that does not speak Tor asks the ordinary resolver about an\nonion name, which tells the local network and the DNS provider which onion was wanted. RFC 7686\ntells such software to fail without the lookup, and DNS servers to answer that the name does not\nexist. Hand the name to the Tor client instead.\n\n**An `Onion-Location` pill that never shows.** A header set only on the plain-HTTP redirect breaks\nthe HTTPS condition, and one with a mistyped address sends readers nowhere. Check the header on\nthe final HTTPS response.\n\n## Further reading\n\n- [Tor Rendezvous Specification, version 3](https://spec.torproject.org/rend-spec/) — the whole\n  protocol: identity and blinded keys, descriptors, introduction and rendezvous.\n- [Encoding onion addresses](https://spec.torproject.org/rend-spec/encoding-onion-addresses.html)\n  — the formula that turns a public key into a 56-character name, with example addresses.\n- [How do Onion Services work?](https://community.torproject.org/onion-services/overview/) — a\n  walk through introduction points, descriptors and the rendezvous, step by step.\n- [Set up Your Onion Service](https://community.torproject.org/onion-services/setup/) — the torrc\n  lines, the files tor creates, and advice on keys and on location leaks.\n- [Onion-Location](https://community.torproject.org/onion-services/advanced/onion-location/) —\n  header and meta-tag setups for Apache, Nginx and Caddy, and the conditions the header must meet.\n- [RFC 7686](https://www.rfc-editor.org/rfc/rfc7686) — why `.onion` is reserved, and what\n  resolvers, DNS operators and registrars must do with it.\n\n\u003chttps://engineer.company/glossary/onion/\u003e\n","date_modified":"2026-11-12T05:34:23Z","description":"How an onion service works: a name encoding its public key, a rendezvous that hides both ends, and what an operator must guard when offering one.","formats":{"gemtext":"https://engineer.company/glossary/onion/index.gmi","gopher":"https://engineer.company/glossary/onion/gophermap","html":"https://engineer.company/glossary/onion/","json":"https://engineer.company/glossary/onion/index.json","markdown":"https://engineer.company/glossary/onion/index.md","pdf":"https://engineer.company/glossary/onion/index.pdf"},"kind":"page","language":"en","title":"What is an onion service?","url":"https://engineer.company/glossary/onion/","version":1}