Module hidden 

Hidden service descriptor parsing for Tor onion services.

This module provides parsing for hidden service descriptors (v2 and v3) which describe onion services accessible through the Tor network. Unlike other descriptor types, these describe a hidden service rather than a relay. They’re created by the service itself and can only be fetched via relays with the HSDir flag.

Overview

Hidden services (also known as onion services) allow servers to receive incoming connections through the Tor network without revealing their IP address. Each hidden service publishes descriptors that contain the information clients need to connect.

Descriptor Versions

Version 2 (Deprecated)

Version 2 hidden service descriptors use RSA cryptography and have .onion addresses that are 16 characters long. These are being phased out in favor of v3 descriptors.

Key components:

• descriptor_id: Base32 hash identifying this descriptor
• permanent_key: RSA public key of the hidden service
• introduction_points: List of relays that can introduce clients

Version 3 (Current)

Version 3 hidden service descriptors use Ed25519/Curve25519 cryptography and have .onion addresses that are 56 characters long. They provide improved security through multiple encryption layers.

Key components:

• signing_cert: Ed25519 certificate for the descriptor
• superencrypted: Outer encryption layer containing client authorization
• Introduction points are in the inner encrypted layer

Encryption Layers (V3)

V3 descriptors have two encryption layers:

1. Outer Layer (OuterLayer): Contains client authorization data and the encrypted inner layer. Decrypted using the blinded public key and subcredential.

2. Inner Layer (InnerLayer): Contains the actual introduction points and service configuration. Requires the descriptor cookie for client-authorized services.

Security Considerations

• V2 descriptors are deprecated and should not be used for new services
• V3 descriptor decryption requires cryptographic keys not stored in the descriptor itself
• Introduction point information is sensitive and encrypted
• The .onion address encodes a checksum to prevent typos

Example

use stem_rs::descriptor::hidden::{HiddenServiceDescriptorV2, HiddenServiceDescriptorV3};
use stem_rs::descriptor::Descriptor;

// Parse a v2 descriptor
let v2_content = "rendezvous-service-descriptor ...";
// let desc_v2 = HiddenServiceDescriptorV2::parse(v2_content)?;

// Parse a v3 descriptor
let v3_content = "hs-descriptor 3\n...";
// let desc_v3 = HiddenServiceDescriptorV3::parse(v3_content)?;

// Convert between v3 address and identity key
let key = [0u8; 32];
let address = HiddenServiceDescriptorV3::address_from_identity_key(&key);
assert!(address.ends_with(".onion"));

See Also

• crate::descriptor: Base descriptor traits and utilities
• crate::descriptor::certificate: Ed25519 certificates used in v3 descriptors

See also

• Tor Rendezvous Specification v2 (deprecated)
• Tor Rendezvous Specification v3

Structs

AuthorizedClient

Client authorized to access a v3 hidden service.

HiddenServiceDescriptorV2

Version 2 hidden service descriptor.

HiddenServiceDescriptorV3

Version 3 hidden service descriptor.

InnerLayer

Inner encryption layer of a v3 hidden service descriptor.

IntroductionPointV2

Introduction point for a version 2 hidden service.

IntroductionPointV3

Introduction point for a version 3 hidden service.

OuterLayer

Outer encryption layer of a v3 hidden service descriptor.

Enums

LinkSpecifier

Link specifier for v3 introduction points.