A directory and guide for acces…

Onion Links V3: Address Format and Technical Specification

V3 onion addresses are 56-character identifiers encoded from a 32-byte ed25519 public key, 2-byte checksum, and version byte using base32 format.

Published: Updated: November 20, 202611 minute read

V3 onion links are 56-character addresses constructed as base32(PUBKEY | CHECKSUM | VERSION) + ".onion", where PUBKEY is a 32-byte ed25519 master public key, CHECKSUM is SHA3_256 truncated to 2 bytes, and VERSION is \x03 (1). These addresses replace older v2 onion services and support subdomain usage for virtual hosting (2).

What Are V3 Onion Addresses: Structure and Encoding

V3 onion addresses are 56-character identifiers that enable access to hidden services on the Tor network. Each address is built from three cryptographic components encoded into a human-readable string. The foundation is a 32-byte ed25519 master public key (KP_hs_id), which serves as the service's permanent cryptographic identity (1). This public key replaces the RSA-1024 keys used in older v2 onion addresses, providing stronger security and longer address length.

The address construction follows a specific formula: base32(PUBKEY | CHECKSUM | VERSION) + '.onion' (1). The PUBKEY is the 32-byte ed25519 master public key. The CHECKSUM is calculated as SHA3_256('.onion checksum' | PUBKEY | VERSION) and then truncated to exactly 2 bytes before insertion (1). The VERSION field is a single byte with default value \x03 (1). These three components are concatenated, then encoded using base32 to produce the 56-character string before '.onion'.

The checksum ensures address integrity. When you receive a v3 onion address, your Tor client recalculates the checksum from the embedded public key and version byte. If the calculated value doesn't match the checksum in the address, the client detects corruption or tampering. This two-byte checksum catches most typing errors and prevents connection attempts to malformed addresses.

The VERSION byte \x03 identifies the protocol generation (1). This byte allows future protocol upgrades while maintaining backward compatibility. When base32-encoded as part of the final characters, this version value typically causes v3 addresses to end with the letter 'd' before '.onion'.

For developers implementing Tor clients or onion service software, understanding this encoding is essential for address validation, key management, and descriptor handling. The ed25519 public key embedded in every v3 address directly determines the service's identity and descriptor location in the distributed hash table.

Why V3 Onion Addresses End in 'd': The Version Indicator

The characteristic 'd' at the end of v3 onion addresses before '.onion' results directly from the VERSION field encoding. This field is a one-byte value set to \x03 for all v3 addresses (1). When the address construction formula base32(PUBKEY | CHECKSUM | VERSION) + '.onion' encodes these three components together, the version byte occupies the final positions in the 56-character string (1).

Base32 encoding converts binary data into a 32-character alphabet (A-Z and 2-7). The byte value \x03 falls into a specific range that, when encoded as part of the trailing bits alongside the two-byte checksum, consistently produces the letter 'd' in the last character before '.onion' (1). This happens because the version byte is concatenated after the 32-byte public key and 2-byte checksum, placing it at the end of the binary sequence that gets base32-encoded.

You can verify this pattern by examining any legitimate v3 onion address. The 56-character identifier will always end with 'd' immediately before the '.onion' suffix. This visual marker helps distinguish v3 addresses from older v2 addresses, which were only 16 characters long and used different version indicators.

The version byte serves two technical purposes beyond creating this recognizable pattern. First, it allows Tor protocol developers to introduce future address formats without breaking existing services. A hypothetical v4 protocol could use \x04, producing different trailing characters. Second, it enables Tor clients to immediately identify the protocol version during address validation, before attempting descriptor fetches or connection establishment.

When you implement address parsing or validation logic, check both the 56-character length and the trailing 'd' as quick format indicators. However, always perform full checksum validation rather than relying solely on the version pattern, since address corruption could coincidentally preserve the 'd' character while breaking the cryptographic integrity (1).

V3 Onion Address Validation Requirements

When a Tor client receives a v3 onion address from you, it must validate the address before attempting to connect or fetch its descriptor (3). If validation fails, the client must refuse to connect (3). This mandatory validation process protects you from connection attempts to malformed, corrupted, or malicious addresses that could leak information or cause client errors.

The validation process checks three critical components. First, the client verifies the address length is exactly 56 characters before '.onion'. Second, it decodes the base32 string to extract the 32-byte public key, 2-byte checksum, and 1-byte version field (1). Third, it recalculates the checksum using the formula SHA3_256('.onion checksum' | PUBKEY | VERSION)[:2] and compares the result to the checksum embedded in the address (1).

If the recalculated checksum doesn't match the embedded value, the address is invalid. The client immediately stops processing and returns an error rather than attempting descriptor lookup. This prevents wasted network resources and protects against typos, truncated addresses, or intentional tampering. The two-byte checksum catches approximately 99.998% of random errors, though it cannot detect all deliberate forgeries.

The validation also confirms the VERSION byte is \x03, identifying the address as a legitimate v3 service (1). Clients reject addresses with unknown version values, ensuring they don't attempt connections using unsupported protocol versions. This check happens before any network activity, so invalid addresses never trigger descriptor fetches from the onion service directory.

For developers building Tor-compatible applications, implement validation before storing addresses in bookmarks, configuration files, or databases. Display clear error messages when validation fails, specifying whether the issue is length, encoding, checksum, or version. Never attempt to "correct" a failed address automatically, since this could connect users to unintended services.

Tor Browser performs this validation automatically when you enter an onion address in the URL bar or click a link. Command-line tools and custom clients must implement the same validation logic to maintain security guarantees. The validation requirement is part of the v3 protocol specification and applies to all Tor clients regardless of implementation (3).

V3 Subdomain Support for Virtual Hosting

V3 onion addresses support subdomain usage with the format [ignored].[onion_address].onion, where the 'ignored' portion is intended for virtual hosting (2). This capability allows a single v3 onion service to host multiple sites or services under different subdomains, similar to how clearnet web servers use virtual hosting to serve multiple domains from one IP address.

The subdomain portion before the 56-character onion address is not cryptographically validated or processed by the Tor protocol itself. When your Tor client connects to a subdomain-prefixed v3 address, it establishes a connection to the base onion service using only the 56-character address and '.onion' suffix. The subdomain string is passed to the destination onion service as part of the HTTP Host header or equivalent application-layer protocol field, allowing the service to route the request to the appropriate virtual host.

This design enables efficient resource usage for operators running multiple related services. Instead of generating separate ed25519 key pairs and maintaining distinct onion addresses for each service, you can deploy one onion service with internal routing logic that examines the Host header. For example, a service could use blog.[base-address].onion for a blog, forum.[base-address].onion for a discussion board, and shop.[base-address].onion for a marketplace, all resolving to the same hidden service endpoint.

The subdomain mechanism works at the application layer, not the Tor protocol layer. Your Tor client validates only the 56-character base address using the checksum and version checks described earlier (1). The subdomain prefix bypasses validation entirely, meaning you can use any string before the base address without triggering connection refusal. However, the destination service must be configured to recognize and route subdomain requests, or it will serve default content regardless of the subdomain used.

For developers implementing onion services with virtual hosting, configure your web server or application to inspect the Host header and route requests accordingly. Standard web server software like Nginx and Apache supports virtual hosting configuration that works identically for onion addresses and clearnet domains. Ensure your routing logic handles unexpected or malicious subdomain values safely, since clients can send arbitrary strings in the Host header.

The V3 Protocol Specification Background

The hidden service version 3 protocol is documented in the Tor Rendezvous Specification - Version 3, which replaced the earlier rend-spec.txt and originated as proposal 224-rend-spec-ng.txt (4). This specification defines the complete technical framework for v3 onion addresses, including how addresses are encoded, how clients validate them, how descriptors are published and retrieved, and how connections are established to hidden services.

The specification emerged from proposal 224, which addressed fundamental security and scalability limitations in the original hidden service protocol. The v2 protocol used RSA-1024 keys, which cryptographic research demonstrated were approaching the end of their practical security lifetime. The proposal introduced ed25519 elliptic curve cryptography for the master identity key, providing equivalent security with smaller key sizes and faster signature verification. This cryptographic upgrade directly determined the v3 address structure, since the 32-byte ed25519 public key became the foundation of the 56-character address format (1).

The Rendezvous Specification - Version 3 documents the address encoding formula, checksum calculation, and validation requirements that all Tor clients must implement (4). It specifies the mandatory validation step where clients must verify the checksum before attempting descriptor fetches (3). The specification also defines the descriptor format, introduction point protocol, and rendezvous protocol that enable clients to discover and connect to onion services without revealing their locations.

For developers building Tor-compatible software, this specification is the authoritative reference. It provides the exact byte-level formats, cryptographic primitives, and protocol state machines required for interoperability with the Tor network. The specification includes test vectors for address encoding, descriptor parsing, and circuit establishment that you can use to verify implementation correctness.

The transition from proposal 224 to the formal Rendezvous Specification - Version 3 involved extensive review, security analysis, and implementation testing (4). The specification continues to evolve through the Tor Project's proposal process, with amendments addressing implementation experience and emerging security considerations. When implementing v3 onion service support, always reference the current version of the specification rather than outdated proposal documents or informal descriptions.

V2 vs V3 Onion Address Comparison

FeatureV2 Onion AddressesV3 Onion Addresses
Address Length16 characters + '.onion'56 characters + '.onion'
Public Key CryptographyRSA-1024ed25519 (32-byte key)
Checksum AlgorithmNo documented dataSHA3-256 truncated to 2 bytes
Version ByteNo documented data\x03 (produces trailing 'd')
Protocol SpecificationOriginal rend-spec.txtRendezvous Spec v3 (proposal 224)
Subdomain SupportNo documented dataSupported ([ignored].[address].onion)
Validation RequirementNo documented dataMandatory before connection attempt
Deprecation StatusNo documented dataActive protocol

Q&A

How to access .onion links?

You access .onion links by installing Tor Browser or configuring a Tor client to route connections through the Tor network. When you enter a v3 onion address in Tor Browser, the client validates the 56-character address format and checksum before establishing an encrypted connection to the hidden service (3). Standard browsers cannot resolve .onion addresses because they require Tor's onion routing protocol to locate and connect to services without revealing their IP addresses.

What is the difference between V2 and V3 onion address?

V3 onion addresses are 56 characters long and use 32-byte ed25519 public keys, while v2 addresses were only 16 characters and used RSA-1024 keys (1). V3 addresses include a 2-byte SHA3-256 checksum and a version byte (\x03) that clients must validate before connecting (1) (3). V3 addresses support subdomain virtual hosting with the format [ignored].[onion_address].onion, which v2 did not provide (2).

Why do v3 onion addresses end in d?

V3 onion addresses characteristically end in 'd' because the VERSION byte value \x03 produces this character when base32-encoded in the final position of the 56-character address (1). The address format is base32(PUBKEY | CHECKSUM | VERSION) + '.onion', so the version byte appears at the end of the encoded string before '.onion' (1). This trailing 'd' serves as a quick visual indicator of the v3 protocol version, though you should always perform full checksum validation rather than relying solely on this pattern (1).

How to open V3 onion links?

You open v3 onion links by entering the full 56-character address into Tor Browser's URL bar or clicking a link while connected to the Tor network. The Tor client automatically validates the address checksum and version byte before attempting to fetch the service descriptor and establish a connection (3). If the address validation fails due to incorrect length, invalid base32 encoding, or checksum mismatch, the client refuses to connect and displays an error (3).

Are onion links safe?

Onion links provide cryptographic protection for connection routing and service authentication, but safety depends on the service operator's intentions and security practices. The v3 protocol validates address integrity through a 2-byte checksum that catches approximately 99.998% of random errors, preventing connections to corrupted addresses (1). However, the protocol cannot protect you from malicious services, social engineering, or illegal content—you must evaluate each service independently and follow security practices appropriate to your threat model.

Key Takeaways

  • V3 onion addresses are 56 characters long and constructed using base32(PUBKEY | CHECKSUM | VERSION) + '.onion', where PUBKEY is a 32-byte ed25519 master public key (1).

  • Mandatory validation before connection requires clients to verify the 2-byte SHA3-256 checksum and version byte (\x03) to prevent connecting to corrupted or invalid addresses (1) (3).

  • The characteristic trailing 'd' results from base32-encoding the version byte \x03 in the final position, serving as a visual indicator of the v3 protocol (1).

  • Subdomain support enables virtual hosting with the format [ignored].[onion_address].onion, allowing one service to host multiple sites while validation applies only to the 56-character base address (2).

  • Implement checksum validation in all custom clients using the exact formula from the Rendezvous Specification - Version 3 to maintain security guarantees and protocol compliance (4) (3).

To understand how Tor Browser handles v3 address validation automatically and explore practical access methods, read Dark Web Sites on Tor Browser: Access and Safety Guide.

References

[1] Encoding onion addresses [ONIONADDRESS] - Tor Specifications

[2] Special Hostnames in Tor - Tor Specifications

[3] rend-spec-v3.txt

[4] Tor Rendezvous Specification - Version 3 - Tor Specifications

Where to look next

These services are useful starting points for further research. Tools & services.