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::Footer as PlainFooter;
pub use md::Footer as MdFooter;
pub use vote::Footer as VoteFooter;
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_template_DirectorySignaturesHashesAccu 🔒: Bespoke derives applied to 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
ConsensusFooterFields: Fields in the footer of a consensus
ConsensusFooterFieldsConstructor: Constructor (required fields) for ConsensusFooterFields
ConsensusFooterFieldsNetdocParseAccumulator: Partially parsed ConsensusFooterFields
ConsensusMethod: A single consensus method
ConsensusMethods: A set of consensus methods
ConsensusSignatureToVerify 🔒: Signature information in a consensus, to be verified
DigestAlgoInSignature: algorithm field in a directory-signature item
DirSource: Description of an authority’s identity and address.
DirectorySignaturesHashesAccu: directory-signaturea hash algorithm argument
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.
NetworkStatusVersion: network-status-version version value
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
RecommendedTorVersions: List of recommended Tor versions
RelayWeightsItem: Relay weight information - w item in routerstatus
RouterStatusMdDigestsVote: m item in votes
SharedRandCommitV1: shared-rand-commit in a vote authority entry
SharedRandCommitV1Constructor: Constructor (required fields) for SharedRandCommitV1
SharedRandParticipate: shared-rand-participate in a vote authority entry
SharedRandParticipateConstructor: Constructor (required fields) for SharedRandParticipate
SharedRandStatus: A shared-random value produced by the directory authorities, along with meta-information about that value.
SharedRandStatuses: The two shared random values, shared-rand-*-value
SharedRandStatusesConstructor: Constructor (required fields) for SharedRandStatuses
SharedRandStatusesNetdocParseAccumulator: Partially parsed SharedRandStatuses
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
SignatureVerifiedIfIntended 🔒: Token indicating that signature verification has been done, if required
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
VoteStatusConsensus: The status value in a vote-status line in a consensus
VoteStatusVote: The vote value in a vote-status line in a vote

Enums§

ConsensusFlavor: A recognized ‘flavor’ of consensus document.
ConsensusVerifiabilityError: Error which will prevent us from attempting to verify signatures on a consensus
ConsensusVerifyFailed: Error encountered while verifying a consensus
DirectorySignatureHashAlgo: directory-signature hash algorithm argument
InvalidRecommendedTorVersions: Erroneous “recommended Tor versions” information
InvalidRelayWeights: Error processing a w line’s netparams into an effective relay weight
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
SharedRandCommit: shared-rand-commit in a vote authority entry
SoftwareVersion: A version as presented in a router status.
VerifyGeneralTrustedAuthorities 🔒: How verify_general should decide who is a trusted authority
VoteVerifyFailed: Error encountered while verifying a vote

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

Functions§

consensus_threshold: Return the minimum number of authorities that we need signatures from

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.