Module hspath

Available on crate feature hs-common only.

Code for building paths for HS circuits.

The path builders defined here are used for creating hidden service circuit stems. A circuit stem is the beginning portion of a hidden service circuit, the structure of which depends on the types of vanguards, if any, that are in use.

There are two types of circuit stems:

• naive circuit stems, used for building circuits to a final hop that an adversary cannot easily control (for example if the target is randomly chosen by us)
• guarded circuit stems, used for building circuits to a final hop that an adversary can easily control (for example if the target was not chosen by us)

Circuit stems eventually become introduction, rendezvous, and HsDir circuits. For all circuit types except client rendezvous, the stems must first be extended by an extra hop:

 Client hsdir:  GUARDED -> HsDir
 Client intro:  GUARDED -> Ipt
 Client rend:   GUARDED
 Service hsdir: NAIVE   -> HsDir
 Service intro: NAIVE   -> Ipt
 Service rend:  GUARDED -> Rpt

Note: the client rendezvous case is an exception to this rule: the rendezvous point is selected by the client, so it cannot easily be controlled by an attacker.

This type of circuit would more accurately be described as a NAIVE circuit that gets extended by an extra hop if Full-Vanguards are in use (this is necessary to avoid using the L3 guard as a rendezvous point). However, for the sake of simplicity, we define these circuits in terms of GUARDED.

Note: in the client rendezvous case, the last node from the GUARDED circuit stem is the rendezvous point.

If vanguards are disabled, naive circuit stems (NAIVE), and guarded circuit stems (GUARDED) are the same, and are built using ExitPathBuilder’s path selection rules.

If vanguards are enabled, the path is built without applying family or same-subnet restrictions at all, the guard is not prohibited from appearing as either of the last two hops of the circuit, and the two circuit stem kinds are built differently depending on the type of vanguards that are in use:

• with lite vanguards enabled:

     NAIVE   = G -> L2 -> M
     GUARDED = G -> L2 -> M

• with full vanguards enabled:

     NAIVE   = G -> L2 -> L3
     GUARDED = G -> L2 -> L3 -> M

Modules

vanguards 🔒 vanguards

This module provides the PathBuilder helper for building vanguard TorPaths.

Structs

HsPathBuilder 🔒

A path builder for hidden service circuits.

VanguardHsPathBuilder 🔒 vanguards

A path builder for hidden service circuits that use vanguards.

Functions

hs_intermediate_hop_usage 🔒

Return the usage that we should use when selecting an intermediary hop (vanguard or middle) of an HS circuit or stem circuit.

hs_stem_terminal_hop_usage 🔒

Return the usage that we should use when selecting the last hop of a stem circuit.