Crate tor_netdoc 

tor-netdoc

Parse and represent directory objects used in Tor.

Overview

Tor has several “network documents” that it uses to convey information about relays on the network. They are documented in the Tor Directory Protocol Spec.

This crate has common code to parse, validate and encode the network document metaformat. It also has specific implementations for various document types.

This crate is part of Arti, a project to implement Tor in Rust.

Structure

The parts of the crate that new code should usually interface with are:

• encode: Support for encoding the metaformat.
• parse2: Support for parsing the metaformat.
• types: Type definitions for elements common across various documents.
• doc: Implementations for specific concrete document types.

Additionally, there is an older internal parse module based on different parsing principles.

Traits and derives

Each of encode and parse2 define:

• traits for encoding and parsing;
• derive macros allowing automatically generated encoders and parsers for document data structures which closely match the netdoc spec;
• helper types and traits.

Network document elements categories, and the corresponding traits, are:

• Whole network documents (possibly with signatures). NetdocParseable, NetdocSigned (for parsing), NetdocEncodable.

• Data structures containing sets of ordinary fields appearing within (“flattened” into) network documents: NetdocParseableFields, NetdocEncodableFields.

• The value for an individual Item. (The same value type may be used for multiple different Items with different keywords, depending the specific document format(s).) ItemValueParseable, SignatureItemParseable, ItemValueEncodable.

• An Argument (or several Arguments) found on an Item line. ItemArgumentParseable, ItemArgument (for encoding), NormalItemArgument.

• An Object (encoded as base-64 in PEM format). ItemObjectParseable, ItemObjectEncodable.

Design notes

The crate is derived into three main parts. In the (private) parse module, we have the generic code that we use to parse different kinds of network documents. In the types module we have implementations for parsing specific data structures that are used inside directory documents. Finally, the doc module defines the parsers for the documents themselves.

Features

routerdesc: enable support for the “router descriptor” document type, which is needed by bridge clients and relays.

plain-consensus: enable support for the “plain (unflavoured) consensus” document type, which some relays cache and serve.

hs-client: enable support for parsing hidden service descriptors.

hs-service: enable support for generating hidden service descriptors.

encode: enable support for encoding documents, in general.

There are also other features includijng experimental ones which aren’t documented here and shouldn’t be relied on.

Deprecated features

build_docs: enable code to construct the objects representing different network documents, with builder patterns.

Caveat haxxor: limitations and infelicities

TODO: This crate requires that all of its inputs be valid UTF-8: This is fine only if we assume that proposal 285 is implemented in mainline Tor.

TODO: This crate has several pieces that could probably be split out into other smaller cases, including handling for version numbers and exit policies.

TODO: Many parts of this crate that should eventually be public aren’t.

TODO: this crate needs far more tests!

License: MIT OR Apache-2.0

Re-exports

pub use encode::NetdocBuilder;encode

Modules

doc

Individual document types that we can parse in Tor’s meta-format.

encodeencode

Support for encoding the network document meta-format

parse2parse2

New netdoc parsing arrangements, with derive

types

Various types that can occur in parsed network documents.

Macros

derive_deftly_template_ItemValueEncodable

Derive ItemValueEncodable

derive_deftly_template_ItemValueParseable

Derive ItemValueParseable

derive_deftly_template_NetdocEncodable

Derive NetdocEncodable for a document (or sub-document)

derive_deftly_template_NetdocEncodableFields

Derive NetdocEncodableFields for a struct with individual items

derive_deftly_template_NetdocParseable

Derive NetdocParseable for a document (or sub-document)

derive_deftly_template_NetdocParseableFields

Derive NetdocParseableFields for a struct with individual items

derive_deftly_template_NetdocSigned

Derive FooSigned from Foo

stop_at

“Type alias” for StopAt<impl Fn(KeywordRef<'_>) -> Option<Stop>>

Structs

Error

An error that occurred while parsing a directory object of some kind.

Enums

AllowAnnotations

Indicates whether we should parse an annotated list of objects or a non-annotated list.

BuildError

An error that occurs while trying to construct a network document.

NetdocErrorKind

A variety of parsing error.

Pos

A position within a directory object. Used to tell where an error occurred.

Traits

KeywordEncodable

Keywords that can be encoded (written) into a (being-built) network document

NormalItemArgument

A “normally formatted” argument to a netdoc item

Functions

supported_protocols

Return a list of the protocols supported by this crate.

Type Aliases

BuildResult

Alias for the Result type returned by document-builder functions in this module.

Result

Alias for the Result type returned by most objects in this module.