Crate tor_protover

tor-protover

Implementation of Tor’s “subprotocol versioning” feature.

Overview

The Tor system is built out of numerous “subprotocols” that are versioned more or less independently. The tor-protover crate implements parsing and handling for these subprotocol versions, so that different Tor instances know which parts of the protocol they support.

Subprotocol versions are also used to determine which versions of the protocol are required to connect to the network (or just recommended).

For more details, see tor-spec.txt section 9.

This crate is part of Arti, a project to implement Tor in Rust. It’s unlikely to be of general interest unless you are writing a Tor implementation, or a program that needs to examine fine-grained details of the Tor network.

Design notes

We’re giving tor-protover its own crate within arti because it needs to be used to multiple higher level crates that do not themselves depend on one another. (For example, [tor-proto] needs to know which variant of a subprotocol can be used with a given relay, whereas [tor-netdoc] needs to parse lists of subprotocol versions from directory documents. Eventually, [arti-client] will need to check its own list of supported protocols against the required list in the consensus.)

License: MIT OR Apache-2.0

Modules

doc_changing

Documentation about changing lists of supported versions.

doc_supported

Documentation: when is a protocol “supported”?

named

Define protocol versions by name.

Structs

NamedSubver

A specific, named subversion of a protocol.

NumberedSubver

A subprotocol capability as represented by a (kind, version) tuple.

ProtoKind

A recognized subprotocol.

Protocols

A set of supported or required subprotocol versions.

SubprotocolEntry 🔒

Representation of a set of versions supported by a protocol.

Enums

ParseError

An error representing a failure to parse a set of protocol versions.

Protocol 🔒

Representation for a known or unknown protocol.

Constants

MAX_VER 🔒

Maximum allowable value for a protocol’s version field.

N_RECOGNIZED 🔒

How many recognized protocols are there?

Functions

bitrange 🔒

Helper: return a new u64 in which bits lo through hi inclusive are set to 1, and all the other bits are set to 0.

dumpmask 🔒

Given a bitmask, return a list of the bits set in the mask, as a String in the format expected by Tor consensus documents.

is_good_number 🔒

Helper: return true if the provided string is a valid “integer” in the form accepted by the protover spec. This is stricter than rust’s integer parsing format.