Module descriptor

stem_rs

Module descriptor 

Source
Expand description

Descriptor parsing for Tor network documents.

This module provides types for parsing various Tor descriptor formats including server descriptors, microdescriptors, consensus documents, and hidden service descriptors.

§Overview

Tor relays and directory authorities publish various types of descriptors that describe the network topology, relay capabilities, and routing information. This module provides parsers for all major descriptor types:

§Descriptor Sources

Descriptors can be obtained from several sources:

  • Tor’s data directory: Cached files like cached-descriptors, cached-consensus
  • Directory authorities: Via the remote module’s download functions
  • CollecTor archives: Historical descriptors with @type annotations

§Type Annotations

Descriptors from CollecTor include a type annotation on the first line in the format @type <name> <major>.<minor>. The TypeAnnotation struct parses these annotations, and parse_file handles them automatically.

§Compression

Downloaded descriptors are often compressed. This module supports automatic decompression via auto_decompress for:

  • Plaintext - Uncompressed data
  • Gzip - Standard gzip compression (fully supported)
  • Zstd - Zstandard compression (detection only, requires external crate)
  • LZMA - LZMA/XZ compression (detection only, requires external crate)

§Digests

Descriptors have cryptographic digests used for identification and verification. The compute_digest function and Descriptor::digest method support:

With encodings:

§Example

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

// Parse a server descriptor from file contents
let content = std::fs::read("cached-descriptors").unwrap();
let descriptor: ServerDescriptor = parse_file(&content).unwrap();

// Access descriptor fields
println!("Nickname: {}", descriptor.nickname);
println!("Address: {}", descriptor.address);

// Compute the descriptor's digest
let digest = descriptor.digest(DigestHash::Sha1, DigestEncoding::Hex).unwrap();
println!("Digest: {}", digest);

§See Also

  • remote - Download descriptors from directory authorities
  • server - Server descriptor parsing
  • micro - Microdescriptor parsing
  • consensus - Network status document parsing
  • hidden - Hidden service descriptor parsing

§See Also

Re-exports§

pub use authority::DirectoryAuthority;
pub use authority::SharedRandomnessCommitment;
pub use bandwidth_file::BandwidthFile;
pub use bandwidth_file::BandwidthMeasurement;
pub use bandwidth_file::RecentStats;
pub use bandwidth_file::RelayFailures;
pub use certificate::Ed25519Certificate;
pub use certificate::Ed25519Extension;
pub use certificate::ExtensionFlag;
pub use certificate::ExtensionType;
pub use certificate::ED25519_HEADER_LENGTH;
pub use certificate::ED25519_KEY_LENGTH;
pub use certificate::ED25519_SIGNATURE_LENGTH;
pub use consensus::DocumentSignature;
pub use consensus::NetworkStatusDocument;
pub use consensus::SharedRandomness;
pub use extra_info::BandwidthHistory;
pub use extra_info::DirResponse;
pub use extra_info::DirStat;
pub use extra_info::ExtraInfoDescriptor;
pub use extra_info::PortKey;
pub use extra_info::Transport;
pub use hidden::AuthorizedClient;
pub use hidden::HiddenServiceDescriptorV2;
pub use hidden::HiddenServiceDescriptorV3;
pub use hidden::InnerLayer;
pub use hidden::IntroductionPointV2;
pub use hidden::IntroductionPointV3;
pub use hidden::LinkSpecifier;
pub use hidden::OuterLayer;
pub use key_cert::KeyCertificate;
pub use micro::Microdescriptor;
pub use remote::download_bandwidth_file;
pub use remote::download_consensus;
pub use remote::download_detached_signatures;
pub use remote::download_extrainfo_descriptors;
pub use remote::download_from_dirport;
pub use remote::download_key_certificates;
pub use remote::download_microdescriptors;
pub use remote::download_server_descriptors;
pub use remote::get_authorities;
pub use remote::Compression;
pub use remote::DirPort;
pub use remote::DownloadResult;
pub use router_status::MicrodescriptorHash;
pub use router_status::RouterStatusEntry;
pub use router_status::RouterStatusEntryType;
pub use server::ServerDescriptor;
pub use tordnsel::parse_exit_list;
pub use tordnsel::parse_exit_list_bytes;
pub use tordnsel::TorDNSEL;

Modules§

authority
Directory authority parsing for Tor network status documents.
bandwidth_file
Bandwidth Authority metrics file parsing.
certificate
Ed25519 certificate parsing for Tor descriptors.
consensus
Network status consensus document parsing.
extra_info
Extra-info descriptor parsing for Tor relay and bridge extra-info documents.
hidden
Hidden service descriptor parsing for Tor onion services.
key_cert
Key certificate parsing for Tor directory authorities.
micro
Microdescriptor parsing for Tor relay microdescriptors.
remote
Remote descriptor downloading from directory authorities and mirrors.
router_status
Router status entry parsing for Tor network status documents.
server
Server descriptor parsing for Tor relay descriptors.
tordnsel
TorDNSEL exit list parsing.

Structs§

TypeAnnotation
A type annotation from CollecTor descriptor archives.

Enums§

DescriptorType
Known descriptor types in the Tor network.
DigestEncoding
Encoding format for descriptor digests.
DigestHash
Hash algorithm used for computing descriptor digests.

Traits§

Descriptor
Trait for parsing and serializing Tor descriptors.

Functions§

auto_decompress
Automatically detects and decompresses content.
compute_digest
Computes a cryptographic digest of content.
decompress
Decompresses content using the specified compression format.
detect_compression
Detects the compression format of binary content.
parse_file
Parses a descriptor from file content with automatic decompression.
parse_file_with_annotation
Parses a descriptor from file content, returning the type annotation.
strip_type_annotation
Strips a type annotation from the beginning of descriptor content.