directory

package
v0.0.0-...-397ee07 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 6, 2026 License: BSD-3-Clause Imports: 18 Imported by: 0

Documentation

Overview

Package directory provides Tor directory protocol functionality. This package handles fetching and parsing directory consensus documents and router descriptors.

Index

Constants

This section is empty.

Variables

View Source 
var DefaultAuthorities = []string{
	"http://194.109.206.212/tor/status-vote/current/consensus-microdesc",
	"http://131.188.40.189/tor/status-vote/current/consensus-microdesc",
	"http://128.31.0.34:9131/tor/status-vote/current/consensus-microdesc",
	"http://86.59.21.38/tor/status-vote/current/consensus-microdesc",
	"http://199.58.81.140/tor/status-vote/current/consensus-microdesc",
	"http://204.13.164.118:18080/tor/status-vote/current/consensus-microdesc",
}

DefaultAuthorities is the default directory authority addresses (hardcoded fallback directories) Using HTTP instead of HTTPS for better compatibility with IP-based authorities The Tor consensus is cryptographically signed, so transport encryption is not critical Using consensus-microdesc format (consensus-method 33) which includes "m" lines with microdescriptor digests

View Source 
var KnownAuthorities = []DirectoryAuthority{
	{
		Nickname: "moria1",
		V3Ident:  "F533C81CEF0BC0267857C99B2F471ADF249FA232",
		Address:  "128.31.0.39:9231",
	},
	{
		Nickname: "tor26",
		V3Ident:  "2F3DF9CA0E5D36F2685A2DA67184EB8DCB8CBA8C",
		Address:  "217.196.147.77:80",
	},
	{
		Nickname: "dizum",
		V3Ident:  "E8A9C45EDE6D711294FADF8E7951F4DE6CA56B58",
		Address:  "45.66.35.11:80",
	},
	{
		Nickname: "gabelmoo",
		V3Ident:  "ED03BB616EB2F60BEC80151114BB25CEF515B226",
		Address:  "131.188.40.189:80",
	},
	{
		Nickname: "dannenberg",
		V3Ident:  "0232AF901C31A04EE9848595AF9BB7620D4C5B2E",
		Address:  "193.23.244.244:80",
	},
	{
		Nickname: "maatuska",
		V3Ident:  "49015F787433103580E3B66A1707A00E60F2D15B",
		Address:  "171.25.193.9:443",
	},
	{
		Nickname: "longclaw",
		V3Ident:  "23D15D965BC35114467363C165C4F724B64B4F66",
		Address:  "199.58.81.140:80",
	},
	{
		Nickname: "bastet",
		V3Ident:  "27102BC123E7AF1D4741AE047E160C91ADC76B21",
		Address:  "204.13.164.118:80",
	},
	{
		Nickname: "faravahar",
		V3Ident:  "70849B868D606BAECFB6128C5E3D782029AA394F",
		Address:  "216.218.219.41:80",
	},
}

KnownAuthorities contains the list of official Tor directory authorities (SPEC-003) These authorities are responsible for creating and signing the network consensus The v3ident fingerprints are used to verify consensus signatures

IMPORTANT: This list should be updated if the Tor Project adds or removes authorities Current as of: January 2026 Reference: https://gitlab.torproject.org/tpo/core/tor/-/blob/HEAD/src/app/config/auth_dirs.inc

Functions

func ValidateConsensusMetadata 

func ValidateConsensusMetadata(meta *ConsensusMetadata) error

ValidateConsensusMetadata performs enhanced validation on consensus metadata (SPEC-003) Validates timing, signature count, and authority quorum requirements per dir-spec.txt §3.4 Current implementation validates signature presence and count. Future enhancement: cryptographic signature verification with authority public keys.

Types

type AuthorityCert 

type AuthorityCert struct {
	Identity   string         // SHA-1 fingerprint of authority's identity key
	SigningKey *rsa.PublicKey // RSA public key for signature verification
	ExpiresAt  time.Time      // Certificate expiration time
	FetchedAt  time.Time      // When this cert was fetched
}

AuthorityCert represents a cached directory authority signing certificate

type AuthorityCertCache 

type AuthorityCertCache struct {
	// contains filtered or unexported fields
}

AuthorityCertCache caches authority signing certificates for consensus verification

func (*AuthorityCertCache) Get 

func (c *AuthorityCertCache) Get(ctx context.Context, identity string, httpClient *http.Client, authorities []string) (*AuthorityCert, error)

Get retrieves a cached certificate or fetches it from authorities (SPEC-003)

type Client 

type Client struct {
	// contains filtered or unexported fields
}

Client provides directory protocol operations

func NewClient 

func NewClient(log *logger.Logger) *Client

NewClient creates a new directory client

func (*Client) FetchConsensus 

func (c *Client) FetchConsensus(ctx context.Context) ([]*Relay, error)

FetchConsensus fetches the network consensus from directory authorities and populates relay cryptographic keys from microdescriptors (SPEC-001)

func (*Client) FetchMicrodescriptors 

func (c *Client) FetchMicrodescriptors(ctx context.Context, relays []*Relay) error

FetchMicrodescriptors fetches microdescriptors for relays and populates their cryptographic keys (SPEC-001) This implements the microdescriptor fetching protocol per dir-spec.txt §3.3

func (*Client) VerifyConsensusSignatures 

func (c *Client) VerifyConsensusSignatures(ctx context.Context, consensusBody []byte, meta *ConsensusMetadata) error

VerifyConsensusSignatures verifies cryptographic signatures on a consensus document (SPEC-003) This implements RSA-PKCS1v15 signature verification per dir-spec.txt §3.4 The function verifies that at least minSignatureThreshold valid signatures are present

Parameters:

  • ctx: Context for certificate fetching
  • consensusBody: The signed portion of the consensus (from "network-status-version" to "directory-signature" lines, exclusive)
  • meta: Consensus metadata containing parsed signatures

Returns error if verification fails or if insufficient valid signatures are found

IMPLEMENTATION STATUS (SPEC-003):

  • ✅ Signature structure validation complete
  • ✅ Known authority verification complete
  • ✅ Quorum enforcement complete (5 of 9 authorities required)
  • ✅ RSA cryptographic verification complete
  • ✅ Authority certificate fetching and caching complete

Reference: dir-spec.txt §3.4 "Voting and consensus signature requirements"

type ConsensusMetadata 

type ConsensusMetadata struct {
	ValidAfter           time.Time
	FreshUntil           time.Time
	ValidUntil           time.Time
	Signatures           []*ConsensusSignature // Parsed authority signatures
	SignatureCount       int                   // Number of authority signatures
	AuthorityCount       int                   // Number of authorities in consensus
	NetworkStatusVersion int                   // Consensus format version
	Params               map[string]int        // Network-wide consensus parameters (dir-spec.txt §3.4.1)
}

ConsensusMetadata contains metadata about a consensus document (SPEC-003)

type ConsensusSignature 

type ConsensusSignature struct {
	Algorithm        string // Signature algorithm (e.g., "sha256")
	Identity         string // Authority identity key digest
	SigningKeyDigest string // Signing key digest
	Signature        string // Base64-encoded signature block
}

ConsensusSignature represents a directory authority signature (SPEC-003)

type DirectoryAuthority 

type DirectoryAuthority struct {
	Nickname string // Human-readable authority name
	V3Ident  string // SHA-1 fingerprint of authority's long-term v3 identity key (40 hex chars)
	Address  string // IP address and ports
}

DirectoryAuthority represents a known Tor directory authority (SPEC-003) These are the official Tor directory authorities as of January 2026 Source: https://gitlab.torproject.org/tpo/core/tor/-/blob/HEAD/src/app/config/auth_dirs.inc

type PaddingParams 

type PaddingParams struct {
	// Global padding settings
	GlobalAllowedCells int  // Maximum padding cells allowed globally
	PaddingDisabled    bool // Whether padding is disabled network-wide

	// APE (Adaptive Padding Engine) parameters
	APEBurstMin    int // Minimum cells in a burst (default: 2)
	APEBurstMax    int // Maximum cells in a burst (default: 10)
	APEGapMinMS    int // Minimum gap between bursts in milliseconds (default: 1500)
	APEGapMaxMS    int // Maximum gap between bursts in milliseconds (default: 9500)
	APECellDelayMS int // Delay between cells in a burst in milliseconds (default: 20)

	// Circuit setup padding parameters
	SetupBurstMin    int // Minimum cells in setup burst (default: 1)
	SetupBurstMax    int // Maximum cells in setup burst (default: 5)
	SetupGapMinMS    int // Minimum setup gap in milliseconds (default: 500)
	SetupGapMaxMS    int // Maximum setup gap in milliseconds (default: 2000)
	SetupCellDelayMS int // Setup cell delay in milliseconds (default: 50)
}

PaddingParams contains circuit padding parameters from consensus These parameters control padding machine behavior network-wide

func GetPaddingParams 

func GetPaddingParams(meta *ConsensusMetadata) *PaddingParams

GetPaddingParams extracts padding-related parameters from consensus metadata Returns parameters with spec-compliant defaults if not present in consensus

type Relay 

type Relay struct {
	Nickname        string
	Fingerprint     string
	Address         string
	ORPort          int
	DirPort         int
	Flags           []string
	Published       time.Time
	IdentityKey     []byte   // Ed25519 identity key (32 bytes) - SPEC-001
	NtorOnionKey    []byte   // Curve25519 ntor onion key (32 bytes) - SPEC-001
	MicrodescDigest string   // SHA256 digest of microdescriptor (base64) - SPEC-001
	Family          []string // Relay family members (fingerprints) - Path Selection Enhancement
	Bandwidth       uint64   // Advertised bandwidth in bytes/sec (from "w" line) - path-spec.txt §2.2
}

Relay represents a Tor relay from the consensus

func (*Relay) GetIdentityKey 

func (r *Relay) GetIdentityKey() []byte

GetIdentityKey returns the relay's Ed25519 identity key (SPEC-001)

func (*Relay) GetNtorOnionKey 

func (r *Relay) GetNtorOnionKey() []byte

GetNtorOnionKey returns the relay's Curve25519 ntor onion key (SPEC-001)

func (*Relay) HasFlag 

func (r *Relay) HasFlag(flag string) bool

HasFlag checks if a relay has a specific flag

func (*Relay) HasValidKeys 

func (r *Relay) HasValidKeys() bool

HasValidKeys returns true if the relay has both required cryptographic keys (SPEC-001)

func (*Relay) InSameFamily 

func (r *Relay) InSameFamily(other *Relay) bool

InSameFamily checks if this relay is in the same family as another relay Family relationships are bidirectional - both relays must list each other This implements family validation per path-spec.txt §2.2.1

func (*Relay) InSameSubnet 

func (r *Relay) InSameSubnet(other *Relay) bool

InSameSubnet checks if this relay shares a /16 subnet with another relay This is a heuristic for detecting relays operated by the same entity per path-spec.txt §2.2.1 "Do not use the same /16 subnet"

func (*Relay) IsExit 

func (r *Relay) IsExit() bool

IsExit returns true if the relay is an exit

func (*Relay) IsGuard 

func (r *Relay) IsGuard() bool

IsGuard returns true if the relay is a guard

func (*Relay) IsRunning 

func (r *Relay) IsRunning() bool

IsRunning returns true if the relay is running

func (*Relay) IsStable 

func (r *Relay) IsStable() bool

IsStable returns true if the relay is stable

func (*Relay) IsValid 

func (r *Relay) IsValid() bool

IsValid returns true if the relay is valid

func (*Relay) String 

func (r *Relay) String() string

String returns a string representation of the relay

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.