Module pathverify

vanguards_rs

Module pathverify 

Source
Expand description

Path verification for ensuring circuits use configured vanguards.

This module verifies that Tor circuits are using the configured vanguard relays and have the expected path lengths for each circuit purpose.

§Overview

The path verifier monitors:

  • Layer 1 guards: Entry guard connections and usage
  • Layer 2 guards: Second-hop relay verification
  • Layer 3 guards: Third-hop relay verification
  • Path lengths: Expected hop counts for each circuit purpose

§Path Length Mappings

Circuit path lengths vary based on the vanguards mode and circuit purpose:

┌─────────────────────────────────────────────────────────────────────┐
│                    Path Length by Purpose                           │
├─────────────────────┬──────────────────┬───────────────────────────┤
│ Circuit Purpose     │ Full Vanguards   │ Vanguards-Lite            │
├─────────────────────┼──────────────────┼───────────────────────────┤
│ HS_VANGUARDS        │ 4 hops           │ 3 hops                    │
│ HS_CLIENT_HSDIR     │ 5 hops           │ 4 hops                    │
│ HS_CLIENT_INTRO     │ 5 hops           │ 4 hops                    │
│ HS_CLIENT_REND      │ 4 hops           │ 3 hops                    │
│ HS_SERVICE_HSDIR    │ 4 hops           │ 4 hops                    │
│ HS_SERVICE_INTRO    │ 4 hops           │ 4 hops                    │
│ HS_SERVICE_REND     │ 5 hops           │ 4 hops                    │
└─────────────────────┴──────────────────┴───────────────────────────┘

§Guard Layer Architecture

┌─────────────────────────────────────────────────────────────────────┐
│                    Vanguard Layer Structure                         │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  Client ──▶ Layer 1 ──▶ Layer 2 ──▶ Layer 3 ──▶ Destination     │
│             (Guard)     (Middle)    (Middle)                        │
│                                                                     │
│  Full Vanguards:                                                    │
│    • Layer 1: 2 guards (long-term)                                  │
│    • Layer 2: 4 guards (medium-term rotation)                       │
│    • Layer 3: 8 guards (short-term rotation)                        │
│                                                                     │
│  Vanguards-Lite:                                                    │
│    • Layer 1: 1 guard                                               │
│    • Layer 2: 4 guards (managed by Tor)                             │
│    • Layer 3: None                                                  │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

§What This Module Does NOT Do

  • Guard selection: Use crate::node_selection for selecting guards
  • Guard rotation: Use crate::vanguards for managing guard state
  • Circuit building: This module only verifies existing circuits

§See Also

Structs§

Layer1Guards
Layer 1 guard tracking.
Layer1Stats
Per-guard usage statistics.
PathVerify
Path verification state.

Constants§

ROUTELEN_FOR_PURPOSE
Expected path lengths for full vanguards mode.
ROUTELEN_FOR_PURPOSE_LITE
Expected path lengths for vanguards-lite mode.