1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
|
# 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](https://spec.torproject.org/dir-spec/index.html).
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](https://gitlab.torproject.org/tpo/core/arti/), a project to
implement [Tor](https://www.torproject.org/) 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
|
