tor_netdoc/doc.rs
1//! Individual document types that we can parse in Tor's meta-format.
2//!
3//! Right now, we recognize four kinds of documents.
4//!
5//! A [netstatus::MdConsensus] is a multi-signed document that the
6//! directory authorities use to tell clients and relays who is on the
7//! network. It contains information about each relay, and it links to
8//! additional microdescriptors ([microdesc::Microdesc]) that have
9//! more information about each relay.
10//!
11//! In order to validate a [netstatus::MdConsensus], you need to have
12//! the authority certificate ([authcert::AuthCert]) for the directory
13//! authorities that signed it.
14//!
15//! Finally, in order to use relays not listed in the consensus (such
16//! as bridges), clients use those relays' self-signed router
17//! descriptors ([routerdesc::RouterDesc]). These router descriptors
18//! are also uploaded to the authorities in order to tell them about
19//! relays and their status.
20//!
21//! All of these formats are described in
22//! [dir-spec.txt](https://spec.torproject.org/dir-spec).
23//!
24//! # Limitations
25//!
26//! Tor recognizes other kinds of documents that this crate doesn't
27//! parse yet. There are "ExtraInfo documents" that encode
28//! information about relays that almost nobody needs.
29//! Finally, there are the voting documents themselves that authorities
30//! use in order to calculate the consensus.
31
32use crate::util::intern::InternCache;
33
34pub mod authcert;
35#[cfg(feature = "hs-common")]
36pub mod hsdesc;
37pub mod microdesc;
38pub mod netstatus;
39
40#[cfg(any(doc, feature = "routerdesc"))]
41pub mod routerdesc;
42
43#[allow(missing_docs, clippy::missing_docs_in_private_items)]
44#[cfg(not(any(doc, feature = "routerdesc")))]
45pub mod routerdesc {
46 /// The digest of a RouterDesc document, as reported in a NS consensus.
47 pub type RdDigest = [u8; 20];
48}
49
50/// Cache of Protocols objects, for saving memory.
51//
52/// This only holds weak references to the objects, so we don't
53/// need to worry about running out of space because of stale entries.
54static PROTOVERS_CACHE: InternCache<tor_protover::Protocols> = InternCache::new();