Module netstatus

Expand description

Parsing implementation for networkstatus documents.

In Tor, a networkstatus documents describes a complete view of the relays in the network: how many there are, how to contact them, and so forth.

A networkstatus document can either be a “votes” – an authority’s view of the network, used as input to the voting process – or a “consensus” – a combined view of the network based on multiple authorities’ votes, and signed by multiple authorities.

A consensus document can itself come in two different flavors: a plain (unflavoured) consensus has references to router descriptors, and a “microdesc”-flavored consensus (“md”) has references to microdescriptors.

To keep an up-to-date view of the network, clients download microdescriptor-flavored consensuses periodically, and then download whatever microdescriptors the consensus lists that the client doesn’t already have.

For full information about the network status format, see dir-spec.txt.

§Limitations

NOTE: The consensus format has changes time, using a “consensus-method” mechanism. This module is does not yet handle all all historical consensus-methods.

NOTE: This module does parse some fields that are not in current use, like relay nicknames, and the “published” times on microdescriptors. We should probably decide whether we actually want to do this.

TODO: This module doesn’t implement vote parsing at all yet.

TODO: This module doesn’t implement plain consensuses.

TODO: We need an object safe trait that combines the common operations found on netstatus documents, so we can store one in a Box<dyn CommonNs> or something similar; otherwise interfacing applications have a hard time to process netstatus documents in a flavor agnostic fashion.

TODO: More testing is needed!

TODO: There should be accessor functions for most of the fields here. As with the other tor-netdoc types, I’m deferring those till I know what they should be.

Re-exports§

pub use plain::RouterStatusBuilder as PlainRouterStatusBuilder;
pub use md::RouterStatusBuilder as MdRouterStatusBuilder;
pub use plain::RouterStatus as PlainRouterStatus;
pub use md::RouterStatus as MdRouterStatus;
pub use vote::RouterStatus as VoteRouterStatus;
pub use plain::Preamble as PlainPreamble;
pub use md::Preamble as MdPreamble;
pub use vote::Preamble as VotePreamble;
pub use PlainConsensus as NsConsensus;
pub use PlainRouterStatus as NsRouterStatus;
pub use UncheckedPlainConsensus as UncheckedNsConsensus;
pub use UnvalidatedPlainConsensus as UnvalidatedNsConsensus;

Modules§

build 🔒: Facilities to construct Consensus objects.
consensus_methods_comma_separated: Module for use with parse2’s with, to parse one argument of comma-separated consensus methods
dir_source 🔒: dir-source items, including the mutant -legacy version
encode_impls 🔒: encode impls for types in this modulea
md: Implementation for microdesc consensus documents.
parse2_impls 🔒: parse2 impls for types in this modulea
plain: Implementation for plain consensus documents.
proto_statuses_parse2_encode 🔒: ProtoStatuses parsing and encoding
rs 🔒: Routerstatus-specific parts of networkstatus parsing.
vote: Implementation for plain consensus documents.

Macros§

derive_deftly_driver_DirectorySignatureHashAlgo 🔒
derive_deftly_template_Lifetime 🔒: Bespoke derive for Lifetime, for new and accessors
derive_deftly_template_VoteAuthoritySection 🔒: Ad-hoc derive, impl NetdocParseable for VoteAuthoritySection

Structs§

ConsensusAuthorityEntry: An authority entry as found in a consensus
ConsensusAuthorityEntryConstructor: Constructor (required fields) for ConsensusAuthorityEntry
ConsensusAuthoritySection: Authority section as found in a consensus
ConsensusMethod: A single consensus method
ConsensusMethods: A set of consensus methods
DirSource: Description of an authority’s identity and address.
Footer: The signed footer of a consensus netstatus.
IgnoredPublicationTimeSp: publiscation field in routerstatus entry intro item other than in votes
Lifetime: The lifetime of a networkstatus document.
LifetimeConstructor: Constructor (required fields) for Lifetime
LifetimeNetdocParseAccumulator: Partially parsed Lifetime
MdConsensusBuilder: A builder object used to construct a consensus.
NetParams: A set of named network parameters.
PlainConsensusBuilder: A builder object used to construct a consensus.
ProtoStatus: A list of subprotocol versions that implementors should/must provide.
ProtoStatuses: A set of recommended and required protocols when running in various scenarios.
ProtoStatusesNetdocParseAccumulator: Partially parsed ProtoStatuses Partially parsed ProtoStatusesParseHelper
RouterStatusMdDigestsVote: m item in votes
SharedRandStatus: A shared-random value produced by the directory authorities, along with meta-information about that value.
SharedRandVal: A shared random value produced by the directory authorities.
Signature: The signature of a single directory authority on a networkstatus document.
SignatureGroup: A collection of signatures that can be checked on a networkstatus document
SupersededAuthorityKey: A dir-source line that is a “superseded authority key entry”
VoteAuthorityEntry: An authority entry as found in a vote
VoteAuthorityEntryConstructor: Constructor (required fields) for VoteAuthorityEntry
VoteAuthoritySection: An authority section in a vote
VoteAuthoritySectionConstructor: Constructor (required fields) for VoteAuthoritySection

Enums§

ConsensusFlavor: A recognized ‘flavor’ of consensus document.
DirectorySignatureHashAlgo: directory-signature hash algorithm argument
NetstatusKwd: Keywords that can be used in votes and consensuses.
ProtocolSupportError: A subprotocol that is recommended or required in the consensus was not present.
RelayWeight: Recognized weight fields on a single relay in a consensus
SigCheckResult 🔒: Result of checking a single authority signature.
SoftwareVersion: A version as presented in a router status.

Statics§

NS_FOOTER_RULES 🔒: Rules for parsing consensus fields from a footer.
NS_HEADER_RULES_COMMON_ 🔒: Shared parts of rules for all kinds of netstatus headers
NS_HEADER_RULES_CONSENSUS 🔒: Rules for parsing the header of a consensus.
NS_ROUTERSTATUS_RULES_COMMON_ 🔒: Shared rules for parsing a single routerstatus
NS_ROUTERSTATUS_RULES_MDCON 🔒: Rules for parsing a single routerstatus in a microdesc consensus
NS_ROUTERSTATUS_RULES_PLAIN 🔒: Rules for parsing a single routerstatus in an NS consensus
NS_VOTERINFO_RULES_CONSENSUS 🔒: Rules for parsing a single voter’s information in a consensus

Type Aliases§

ConsensusVoterInfoDeprecated: Authority entry in a consensus - deprecated compatibility type alias
MdAuthorityEntry: Authority entry in an md consensus - type alias provided for consistency
MdConsensus: A consensus document that lists relays along with their microdescriptor documents.
PlainAuthorityEntry: Authority entry in a plain consensus - type alias provided for consistency
PlainConsensus: A consensus document that lists relays along with their router descriptor documents.
UncheckedMdConsensus: An MdConsensus that has been parsed but not checked for signatures and timeliness.
UncheckedPlainConsensus: An PlainConsensus that has been parsed but not checked for signatures and timeliness.
UnvalidatedMdConsensus: An MdConsensus that has been parsed and checked for timeliness, but not for signatures.
UnvalidatedPlainConsensus: An PlainConsensus that has been parsed and checked for timeliness, but not for signatures.