Complete Tor Browser Guide

Go: open a terminal, then mkdir onionlab and cd onionlab. Nothing in this lab touches the Tor network — every check is arithmetic on the address itself.

Do: save this as onioncheck.py. A v3 onion address is base32 of a 32-byte public key, a 2-byte checksum, and a version byte:

import base64, hashlib, sys

def parts(addr):
    a = addr.lower().replace(".onion", "")
    if len(a) != 56:
        sys.exit(f"not a v3 onion address: {len(a)} characters, expected 56")
    raw = base64.b32decode(a.upper() + "=" * ((8 - len(a) % 8) % 8))
    return raw[:32], raw[32:34], raw[34:35]

def checksum(pub, ver):
    return hashlib.sha3_256(b".onion checksum" + pub + ver).digest()[:2]

addr = sys.argv[1]
pub, chk, ver = parts(addr)
want = checksum(pub, ver)
print(f"address  : {addr}")
print(f"version  : {ver.hex()}")
print(f"checksum : in address {chk.hex()}   computed {want.hex()}")
print("VALID — well-formed" if chk == want else "INVALID — this address is corrupt or mistyped")

Run it on the Tor Project's own address:

python3 onioncheck.py 2gzyxa5ihm7nsggfxnu52rck2vv4rvmdlkiu3zzui5du4xyclen53wid.onion

You should see: the checksum in the address and the one computed from its key agree:

address  : 2gzyxa5ihm7nsggfxnu52rck2vv4rvmdlkiu3zzui5du4xyclen53wid.onion
version  : 03
checksum : in address ddd9   computed ddd9
VALID — well-formed

Nothing was contacted. An onion address is not a name that gets looked up — it is the key, which is why there is no registrar, no certificate authority, and nobody to ask whether it is genuine.

If not: Incorrect padding means the address lost characters when copying — it must be exactly 56 characters before .onion. not a v3 onion address with a smaller number means you copied a short v2 address, which Tor removed support for in 2021.

Go: the same folder.

Do: run the checker again on the same address with a single character changed — the w near the end becomes an x:

python3 onioncheck.py 2gzyxa5ihm7nsggfxnu52rck2vv4rvmdlkiu3zzui5du4xyclen53xid.onion

You should see: the two checksums no longer agree:

address  : 2gzyxa5ihm7nsggfxnu52rck2vv4rvmdlkiu3zzui5du4xyclen53xid.onion
version  : 03
checksum : in address dddd   computed ddd9
INVALID — this address is corrupt or mistyped

This is the checksum doing its job: it catches accidents — a dropped character, a bad copy-paste, a misread from a screenshot. Tor Browser performs this same check and refuses to load an address that fails it, which is genuinely useful and is also the limit of what it can do.

If not: if it reports VALID, you did not actually change a character — compare the two addresses carefully, the difference is one letter four from the end.

Go: the same folder.

Do: save this as makeonion.py, then run it and feed the result straight back into your checker:

import base64, hashlib, os

# An onion address is a public key with a checksum stapled on. Anyone can make one.
pub = os.urandom(32)          # pretend this is a real ed25519 public key
ver = b"\x03"
chk = hashlib.sha3_256(b".onion checksum" + pub + ver).digest()[:2]
addr = base64.b32encode(pub + chk + ver).decode().lower().rstrip("=")
print(addr + ".onion")

Then:

python3 makeonion.py > fake.txt
cat fake.txt
python3 onioncheck.py "$(cat fake.txt)"

You should see: an address that has never existed, and it passes:

oeoyzmrrzfrighwatjnej4f5i7s3eurxlk2bitdnf6vei6rrpemt3pid.onion
address  : oeoyzmrrzfrighwatjnej4f5i7s3eurxlk2bitdnf6vei6rrpemt3pid.onion
version  : 03
checksum : in address 3dbd   computed 3dbd
VALID — well-formed

Yours will be a different address every run — it is generated from random bytes.

🔴 VALID does not mean trustworthy. It means the address is well-formed. Anyone can produce as many valid addresses as they like, in a fraction of a second, and every one of them will load in Tor Browser without a single warning.

If not: if the checker reports INVALID on your generated address, the address was truncated when writing to the file — run wc -c fake.txt, it should be 63 characters plus a newline.

Go: the same folder.

Do: almost nobody compares all 56 characters. They glance at the first few. Save this as vanity.py and ask it for an address starting with the same four characters as the real Tor Project one:

import base64, hashlib, os, sys, time

target = sys.argv[1].lower()
start = time.time()
tries = 0
while True:
    tries += 1
    pub = os.urandom(32)
    ver = b"\x03"
    chk = hashlib.sha3_256(b".onion checksum" + pub + ver).digest()[:2]
    addr = base64.b32encode(pub + chk + ver).decode().lower().rstrip("=")
    if addr.startswith(target):
        print(f"matched \'{target}\' after {tries:,} tries in {time.time()-start:.1f}s")
        print(addr + ".onion")
        break

Then run it:

python3 vanity.py 2gzy

You should see: a matching prefix in seconds:

matched '2gzy' after 695,714 tries in 3.8s
2gzy5nwbtyscfoqk4t6czy2va3lz5myndewjmfl7sxj6dhzc5zu2rlad.onion

Your address and timing will differ; a few seconds is typical for four characters.

🔴 Put them side by side. The real one is 2gzyxa5ihm7... and yours is 2gzy followed by something else entirely. Both are valid. Both load. Four characters cost a few seconds; six or seven are still cheap. The visual check almost everyone performs — recognising the start of a familiar address — is defeated for the price of a coffee break.

If not: if it runs for more than a minute, you asked for too many characters — each extra character multiplies the work by 32. Use four. Press Ctrl+C to stop it.

Go: a site you already trust over ordinary HTTPS — for example torproject.org, or the official site of whatever service you want the onion address for.

Do: get the onion address from that authenticated source and paste it into your checker rather than typing it. Many sites also publish an Onion-Location header, which Tor Browser turns into a “.onion available” button — that button is trustworthy for the same reason: the address arrived over a connection with a verified certificate.

python3 onioncheck.py <paste the address you copied>

You should see: VALID — well-formed, which now means something, because you already know where the address came from.

This step depends on your own browsing and was not re-run for this page; steps 1–4 above were, and they are what the reasoning rests on.

The checksum proves the address survived the journey intact. Only the source proves it is the right address. That ordering — authenticate first, verify integrity second — is the whole of it, and it is why bookmarking a verified onion address is worth more than any amount of squinting at the characters.

If not: if the address fails the check after you pasted it, you copied a line break or a trailing space — quote it: python3 onioncheck.py "…onion". If a site offers no onion address at all, no amount of searching for one is safe: unofficial mirrors are exactly the attack this lab describes.