Module server

stem_rs::descriptor

Module server 

Source
Expand description

Server descriptor parsing for Tor relay descriptors.

This module provides parsing for server descriptors, which are the primary documents that Tor relays publish to describe themselves to the network. Server descriptors contain comprehensive metadata about a relay including its identity, network addresses, bandwidth capabilities, exit policy, and cryptographic keys.

§Overview

Server descriptors are published by relays to directory authorities and cached by clients. They contain:

  • Identity information: Nickname, fingerprint, contact info
  • Network addresses: IPv4/IPv6 addresses and ports (OR, SOCKS, Dir)
  • Bandwidth: Advertised and observed bandwidth values
  • Exit policy: Rules for what traffic the relay will exit
  • Cryptographic keys: Onion keys, signing keys, Ed25519 certificates
  • Protocol versions: Supported link and circuit protocol versions
  • Family: Related relays operated by the same entity

§Descriptor Format

Server descriptors follow a text-based format defined in the Tor directory protocol specification. The format consists of keyword-value lines, with some values spanning multiple lines (like PEM-encoded keys).

router <nickname> <address> <ORPort> <SOCKSPort> <DirPort>
platform Tor <version> on <OS>
published <YYYY-MM-DD HH:MM:SS>
fingerprint <40 hex chars with spaces>
bandwidth <avg> <burst> <observed>
onion-key
-----BEGIN RSA PUBLIC KEY-----
<base64 encoded key>
-----END RSA PUBLIC KEY-----
signing-key
-----BEGIN RSA PUBLIC KEY-----
<base64 encoded key>
-----END RSA PUBLIC KEY-----
accept|reject <exit policy rule>
router-signature
-----BEGIN SIGNATURE-----
<base64 encoded signature>
-----END SIGNATURE-----

§Example

use stem_rs::descriptor::{ServerDescriptor, Descriptor, DigestHash, DigestEncoding};

let content = r#"router example 192.168.1.1 9001 0 0
published 2023-01-01 00:00:00
bandwidth 1000000 2000000 500000
accept *:80
accept *:443
reject *:*
router-signature
-----BEGIN SIGNATURE-----
dGVzdA==
-----END SIGNATURE-----
"#;

let descriptor = ServerDescriptor::parse(content).unwrap();
println!("Relay: {} at {}", descriptor.nickname, descriptor.address);
println!("Bandwidth: {} bytes/sec observed", descriptor.bandwidth_observed);

// Check exit policy
if descriptor.exit_policy.can_exit_to("10.0.0.1".parse().unwrap(), 80) {
    println!("Allows HTTP traffic");
}

§Digest Computation

Server descriptor digests are computed over the content from the router line through the router-signature line (inclusive of the newline after router-signature). This is the signed portion of the descriptor.

§Bridge Descriptors

Bridge descriptors are similar to server descriptors but have some fields redacted for privacy. They use the bridge-server-descriptor type annotation and may have different bridge-distribution-request values.

§See Also

Structs§

ServerDescriptor
A server descriptor containing metadata about a Tor relay.