Struct Microdescriptor

Source

pub struct Microdescriptor {
    pub onion_key: String,
    pub ntor_onion_key: Option<String>,
    pub or_addresses: Vec<(IpAddr, u16, bool)>,
    pub family: Vec<String>,
    pub exit_policy: MicroExitPolicy,
    pub exit_policy_v6: Option<MicroExitPolicy>,
    pub identifiers: HashMap<String, String>,
    pub protocols: HashMap<String, Vec<u32>>,
    /* private fields */
}

Expand description

A microdescriptor containing compact relay information for clients.

Microdescriptors are designed to minimize bandwidth for Tor clients. They contain only the information needed for circuit building, omitting details like contact info, platform, and full exit policies.

§Fields Overview

Field	Description
`onion_key`	RSA key for TAP handshake (legacy)
`ntor_onion_key`	Curve25519 key for ntor handshake
`exit_policy`	Compact exit policy (ports only)
`family`	Related relay fingerprints
`protocols`	Supported protocol versions

§Invariants

onion_key is always present (required field)
exit_policy defaults to “reject 1-65535” if not specified

§Example

use stem_rs::descriptor::{Microdescriptor, Descriptor};

let content = r#"onion-key
-----BEGIN RSA PUBLIC KEY-----
MIGJAoGBAMhPQtZPaxP3ukybV5LfofKQr20/ljpRk0e9IlGWWMSTkfVvBcHsa6IM
H2KE6s4uuPHp7FqhakXAzJbODobnPHY8l1E4efyrqMQZXEQk2IMhgSNtG6YqUrVF
CxdSKSSy0mmcBe2TOyQsahlGZ9Pudxfnrey7KcfqnArEOqNH09RpAgMBAAE=
-----END RSA PUBLIC KEY-----
p accept 80,443
"#;

let desc = Microdescriptor::parse(content).unwrap();
assert!(desc.exit_policy.is_accept);

§Thread Safety

Microdescriptor is Send and Sync as it contains only owned data.

Fields§

§onion_key: String

RSA onion key for TAP circuit handshake (PEM format).

This is the legacy key used for the original Tor handshake. Modern clients prefer the ntor handshake using ntor_onion_key.

§ntor_onion_key: Option<String>

Curve25519 onion key for ntor circuit handshake (base64).

This is the modern key used for the ntor handshake, which provides better security properties than the TAP handshake.

§or_addresses: Vec<(IpAddr, u16, bool)>

Additional addresses (IPv4 or IPv6) the relay listens on.

Each tuple is (address, port, is_ipv6). The a lines in the microdescriptor provide these additional addresses.

§family: Vec<String>

Fingerprints of related relays (same operator).

These are typically prefixed with $ and contain the full 40-character hex fingerprint.

§exit_policy: MicroExitPolicy

Compact IPv4 exit policy.

Unlike full exit policies, microdescriptor policies only specify which ports are accepted or rejected, not addresses.

§exit_policy_v6: Option<MicroExitPolicy>

Compact IPv6 exit policy.

Separate policy for IPv6 traffic, if different from IPv4.

§identifiers: HashMap<String, String>

Identity key digests by type.

Maps key type (e.g., “rsa1024”, “ed25519”) to the base64-encoded digest of that key.

§protocols: HashMap<String, Vec<u32>>

Supported protocol versions.

Maps protocol name to list of supported versions. Common protocols include “Link”, “Relay”, “HSDir”, etc.

Implementations§

Source §

impl Microdescriptor

Source

pub fn new(onion_key: String) -> Self

Creates a new microdescriptor with the given onion key.

This creates a descriptor with default values for optional fields. The exit policy defaults to rejecting all ports.

§Arguments

onion_key - The RSA onion key in PEM format

§Example

use stem_rs::descriptor::Microdescriptor;

let key = "-----BEGIN RSA PUBLIC KEY-----\n...\n-----END RSA PUBLIC KEY-----";
let desc = Microdescriptor::new(key.to_string());
assert!(desc.ntor_onion_key.is_none());
assert!(desc.family.is_empty());

Source

pub fn parse_with_annotations( content: &str, annotations: &[&str], ) -> Result<Self, Error>

Parses a microdescriptor with additional annotations.

This is useful when annotations are provided separately from the descriptor content (e.g., when reading from a cache file where annotations precede the descriptor).

§Arguments

content - The microdescriptor content
annotations - Additional annotation lines (with or without @ prefix)

§Errors

Returns Error::Parse if the content is malformed.

§Example

use stem_rs::descriptor::Microdescriptor;

let content = r#"onion-key
-----BEGIN RSA PUBLIC KEY-----
MIGJAoGBAMhPQtZPaxP3ukybV5LfofKQr20/ljpRk0e9IlGWWMSTkfVvBcHsa6IM
H2KE6s4uuPHp7FqhakXAzJbODobnPHY8l1E4efyrqMQZXEQk2IMhgSNtG6YqUrVF
CxdSKSSy0mmcBe2TOyQsahlGZ9Pudxfnrey7KcfqnArEOqNH09RpAgMBAAE=
-----END RSA PUBLIC KEY-----
"#;

let annotations = &["@last-listed 2023-01-01 00:00:00"];
let desc = Microdescriptor::parse_with_annotations(content, annotations).unwrap();

let anns = desc.get_annotations();
assert!(anns.contains_key("last-listed"));

Source

pub fn get_annotations(&self) -> HashMap<String, Option<String>>

Returns all annotations as a map.

Annotations are metadata lines starting with @ that may be present in CollecTor archives.

§Example

use stem_rs::descriptor::{Microdescriptor, Descriptor};

let content = r#"@last-listed 2023-01-01 00:00:00
onion-key
-----BEGIN RSA PUBLIC KEY-----
MIGJAoGBAMhPQtZPaxP3ukybV5LfofKQr20/ljpRk0e9IlGWWMSTkfVvBcHsa6IM
H2KE6s4uuPHp7FqhakXAzJbODobnPHY8l1E4efyrqMQZXEQk2IMhgSNtG6YqUrVF
CxdSKSSy0mmcBe2TOyQsahlGZ9Pudxfnrey7KcfqnArEOqNH09RpAgMBAAE=
-----END RSA PUBLIC KEY-----
"#;

let desc = Microdescriptor::parse(content).unwrap();
let annotations = desc.get_annotations();

if let Some(Some(date)) = annotations.get("last-listed") {
    println!("Last listed: {}", date);
}

Source

pub fn get_annotation_lines(&self) -> Vec<String>

Returns annotations formatted as lines with @ prefix.

This is useful for serializing annotations back to their original format.

§Example

use stem_rs::descriptor::{Microdescriptor, Descriptor};

let content = r#"@last-listed 2023-01-01 00:00:00
onion-key
-----BEGIN RSA PUBLIC KEY-----
MIGJAoGBAMhPQtZPaxP3ukybV5LfofKQr20/ljpRk0e9IlGWWMSTkfVvBcHsa6IM
H2KE6s4uuPHp7FqhakXAzJbODobnPHY8l1E4efyrqMQZXEQk2IMhgSNtG6YqUrVF
CxdSKSSy0mmcBe2TOyQsahlGZ9Pudxfnrey7KcfqnArEOqNH09RpAgMBAAE=
-----END RSA PUBLIC KEY-----
"#;

let desc = Microdescriptor::parse(content).unwrap();
for line in desc.get_annotation_lines() {
    println!("{}", line);
}