How V3 Tor Onion Addresses Are Generated

Version 3 (v3) Tor onion addresses are 56-character cryptographic identifiers derived directly from an asymmetric key pair. Unlike standard web domains that rely on centralized Domain Name System (DNS) servers, Tor onion addresses are self-authenticating. This article explains the underlying cryptography and the exact step-by-step process the Tor protocol uses to construct a v3 onion address from raw cryptographic keys.

The Cryptographic Foundation

A v3 onion address relies on modern elliptic-curve cryptography to guarantee security and privacy. The primary components involved in the generation process are:

• Ed25519: An Edwards-curve Digital Signature Algorithm used to generate the hidden service’s public and private key pair.
• SHA3-256: A secure cryptographic hash function used to calculate address checksums.
• Base32 Encoding: A binary-to-text encoding scheme that converts raw byte data into human-readable, lowercase alphanumeric strings (a-z and 2-7).

Step-by-Step Address Generation

Generating a v3 onion address involves five distinct steps:

1. Key Pair Creation

The process begins with generating a standard Ed25519 cryptographic key pair. This yields: * A private key kept secret by the service operator to sign descriptors and establish identity. * A public key consisting of exactly 32 bytes (256 bits).

2. Checksum Calculation

To prevent typos and routing errors, a two-byte checksum is generated. Tor computes a SHA3-256 hash across a specific concatenated byte sequence: * The constant prefix string: ".onion checksum" (15 bytes) * The 32-byte Ed25519 public key * The single-byte protocol version: 0x03

From the resulting 32-byte SHA3-256 digest, only the first two bytes are retained as the checksum.

3. Payload Assembly

The raw address payload is assembled by concatenating three specific fields in order: * Public Key: 32 bytes * Checksum: 2 bytes * Version Byte: 1 byte (0x03 representing v3)

This creates a fixed-size payload of exactly 35 bytes (\(32 + 2 + 1\)).

4. Base32 Encoding

The 35-byte assembled payload is encoded using standard Base32 (RFC 4648) without padding.

Because each Base32 character represents 5 bits of data, encoding 35 bytes (280 bits) yields exactly 56 characters: \[\frac{35 \text{ bytes} \times 8 \text{ bits/byte}}{5 \text{ bits/character}} = 56 \text{ characters}\]

5. Suffix Attachment

Finally, the standard top-level domain .onion is appended to the 56-character Base32 string, producing the complete 62-character address:

[56-character base32 string].onion

Key Security Advantages

Because the address contains the full public key, any Tor client connecting to a v3 service can verify that the descriptor received from the Tor network was signed by the holder of the corresponding private key. This structure eliminates the need for trusted certificate authorities, prevents impersonation attacks, and ensures that addresses cannot be intercepted or modified in transit.