//! 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](https://spec.torproject.org/dir-spec).

//!

//! # 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.

mod dir_source;

mod rs;

pub mod md;

pub mod plain;

pub mod vote;

#[cfg(feature = "build_docs")]

mod build;

pub use proto_statuses_parse2_encode::ProtoStatusesNetdocParseAccumulator;

use crate::doc::authcert::EncodedAuthCert;

use crate::doc::authcert::{self, AuthCert, AuthCertKeyIds, AuthCertUnverified};

use crate::encode::{

    EncodeOrd, ItemArgument, ItemEncoder, ItemValueEncodable, NetdocEncodable, NetdocEncoder,

};

use crate::parse::keyword::Keyword;

use crate::parse::parser::{Section, SectionRules, SectionRulesBuilder};

use crate::parse::tokenize::{Item, ItemResult, NetDocReader};

use crate::parse2::{

    self, ArgumentError, ArgumentStream, ErrorProblem, IsStructural, ItemArgumentParseable,

    ItemStream, ItemValueParseable, KeywordRef, NetdocParseable, NetdocParseableUnverified,

    SignatureHashInputs, SignatureItemParseable, StopAt, UnparsedItem, VerifyFailed,

};

use crate::types::relay_flags::{self, DocRelayFlags};

use crate::types::{self, *};

use crate::util::PeekableIterator;

use crate::{Error, KeywordEncodable, NetdocErrorKind as EK, NormalItemArgument, Pos};

use std::collections::{BTreeSet, HashMap, HashSet};

use std::fmt::{self, Display};

use std::slice;

use std::str::FromStr;

use std::sync::Arc;

use std::time::{self, SystemTime};

use std::{net, result};

use tor_basic_utils::iter_join;

use tor_error::{Bug, HasKind, bad_api_usage, internal};

use tor_protover::Protocols;

use void::ResultVoidExt as _;

use derive_deftly::{Deftly, define_derive_deftly};

use digest::Digest;

use educe::Educe;

use itertools::Itertools;

use saturating_time::SaturatingTime as _;

use std::sync::LazyLock;

use tor_checkable::{ExternallySigned, TimeBound, timed::TimeRangeBound};

use tor_llcrypto as ll;

use tor_llcrypto::pk::rsa::RsaIdentity;

use serde::{Deserialize, Deserializer};

#[cfg(feature = "build_docs")]

pub use build::MdConsensusBuilder;

#[cfg(feature = "build_docs")]

pub use build::PlainConsensusBuilder;

#[cfg(feature = "build_docs")]

ns_export_each_flavor! {

    ty: RouterStatusBuilder;

}

ns_export_each_variety! {

    ty: Footer, RouterStatus, Preamble;

}

#[deprecated]

pub use PlainConsensus as NsConsensus;

#[deprecated]

pub use PlainRouterStatus as NsRouterStatus;

#[deprecated]

pub use UncheckedPlainConsensus as UncheckedNsConsensus;

#[deprecated]

pub use UnvalidatedPlainConsensus as UnvalidatedNsConsensus;

pub use rs::{RouterStatusMdDigestsVote, SoftwareVersion};

pub use dir_source::{

    ConsensusAuthoritySection, ConsensusAuthoritySectionConstructor, DirSource,

    DirSourceConstructor, SupersededAuthorityKey,

};

define_constant_string! {

    /// `network-status-version` version value

    ///

    /// This is the fixed string `3`.

    ///

    /// <https://spec.torproject.org/dir-spec/consensus-formats.html#item:network-status-version>

    //

    // IMO this is nicer than the formulation with an enum.

    // In practice we are not going to support other versions with the same parsing approach;

    // probably not even with the same code.

    NetworkStatusVersion = "3";

}

define_constant_string! {

    /// The `status` value in a `vote-status` line in a consensus

    ///

    /// <https://spec.torproject.org/dir-spec/consensus-formats.html#item:vote-status>

    VoteStatusConsensus = "consensus";

}

define_constant_string! {

    /// The `vote` value in a `vote-status` line in a vote

    ///

    /// <https://spec.torproject.org/dir-spec/consensus-formats.html#item:vote-status>

    VoteStatusVote = "vote";

}

/// `publiscation` field in routerstatus entry intro item other than in votes

///

/// Two arguments which are both ignored.

/// This used to be an ISO8601 timestamp in anomalous two-argument format.

///

/// Nowadays, according to the spec, it can be a dummy value.

/// So it can be a unit type.

///

/// <https://spec.torproject.org/dir-spec/consensus-formats.html#item:r>,

/// except in votes which use [`Iso8601TimeSp`] instead.

///

/// **Not the same as** the `published` item:

/// <https://spec.torproject.org/dir-spec/consensus-formats.html#item:published>

#[derive(Debug, Copy, Clone, Eq, PartialEq, Hash, Ord, PartialOrd, Default)]

#[allow(clippy::exhaustive_structs)]

pub struct IgnoredPublicationTimeSp;

/// The lifetime of a networkstatus document.

///

/// In a consensus, this type describes when the consensus may safely

/// be used.  In a vote, this type describes the proposed lifetime for a

/// consensus.

///

/// Aggregate of three netdoc preamble fields.

#[derive(Clone, Debug, PartialEq, Eq, Deftly)]

#[derive_deftly(Constructor, NetdocEncodableFields, NetdocParseableFields)]

#[derive_deftly(Lifetime)]

#[allow(clippy::exhaustive_structs)]

pub struct Lifetime {

    /// `valid-after` --- Time at which the document becomes valid

    ///

    /// <https://spec.torproject.org/dir-spec/consensus-formats.html#item:published>

    ///

    /// (You might see a consensus a little while before this time,

    /// since voting tries to finish up before the.)

    #[deftly(constructor)]

    #[deftly(netdoc(single_arg))]

    pub valid_after: Iso8601TimeSp,

    /// `fresh-until` --- Time after which there is expected to be a better version

    /// of this consensus

    ///

    /// <https://spec.torproject.org/dir-spec/consensus-formats.html#item:published>

    ///

    /// You can use the consensus after this time, but there is (or is

    /// supposed to be) a better one by this point.

    #[deftly(constructor)]

    #[deftly(netdoc(single_arg))]

    pub fresh_until: Iso8601TimeSp,

    /// `valid-until` --- Time after which this consensus is expired.

    ///

    /// <https://spec.torproject.org/dir-spec/consensus-formats.html#item:published>

    ///

    /// You should try to get a better consensus after this time,

    /// though it's okay to keep using this one if no more recent one

    /// can be found.

    #[deftly(constructor)]

    #[deftly(netdoc(single_arg))]

    pub valid_until: Iso8601TimeSp,

    #[doc(hidden)]

    #[deftly(netdoc(skip))]

    pub __non_exhaustive: (),

}

define_derive_deftly! {

    /// Bespoke derive for `Lifetime`, for `new` and accessors

    Lifetime:

    ${defcond FIELD not(approx_equal($fname, __non_exhaustive))}

    impl Lifetime {

        /// Construct a new Lifetime.

            // Make this now because otherwise literal `valid_after` here in the body

            // has the wrong span - the compiler refuses to look at the argument.

            // But we can refer to the field names.

            let self_ = Lifetime {

                $( ${when FIELD} $fname: $fname.into(), )

                __non_exhaustive: (),

            };

            if self_.valid_after < self_.fresh_until && self_.fresh_until < self_.valid_until {

                Ok(self_)

            } else {

                Err(EK::InvalidLifetime.err())

            }

        }

      $(

        ${when FIELD}

        ${fattrs doc}

            *self.$fname

        }

      )

        /// Return true if this consensus is officially valid at the provided time.

            *self.valid_after <= when && when <= *self.valid_until

        }

        /// Return the voting period implied by this lifetime.

        ///

        /// (The "voting period" is the amount of time in between when a consensus first

        /// becomes valid, and when the next consensus is expected to become valid)

            let valid_after = self.valid_after();

            let fresh_until = self.fresh_until();

            fresh_until

                .duration_since(valid_after)

                .expect("Mis-formed lifetime")

        }

    }

}

use derive_deftly_template_Lifetime;

/// A single consensus method

///

/// These are integers, but we don't do arithmetic on them.

///

/// As defined here:

/// <https://spec.torproject.org/dir-spec/consensus-formats.html#item:consensus-methods>

/// <https://spec.torproject.org/dir-spec/computing-consensus.html#flavor:microdesc>

///

/// As used in a `consensus-method` item:

/// <https://spec.torproject.org/dir-spec/consensus-formats.html#item:consensus-method>

#[derive(Debug, Clone, Default, Eq, PartialEq, Ord, PartialOrd, Hash, Copy)] //

#[derive(derive_more::From, derive_more::Into, derive_more::Display, derive_more::FromStr)]

#[allow(clippy::exhaustive_structs)] // we're v unlikely to want to change this to u16 or u64

pub struct ConsensusMethod(pub u32);

impl NormalItemArgument for ConsensusMethod {}

/// A set of consensus methods

///

/// Implements `ItemValueParseable` as required for `consensus-methods`,

/// <https://spec.torproject.org/dir-spec/consensus-formats.html#item:consensus-methods>

///

/// There is also [`consensus_methods_comma_separated`] for `m` lines in votes.

#[derive(Debug, Clone, Default, Eq, PartialEq, Ord, PartialOrd, Hash, Deftly)]

#[derive_deftly(ItemValueEncodable, ItemValueParseable)]

#[non_exhaustive]

pub struct ConsensusMethods {

    /// Consensus methods.

    pub methods: BTreeSet<ConsensusMethod>,

}

/// Module for use with parse2's `with`, to parse one argument of comma-separated consensus methods

///

/// As found in an `m` item in a vote:

/// <https://spec.torproject.org/dir-spec/consensus-formats.html#item:m>

pub mod consensus_methods_comma_separated {

    use super::*;

    use parse2::ArgumentError as AE;

    use std::result::Result;

    /// Parse

        }

    /// Encode

}

/// Contents of a `voting-delay` item in the network status preamble

///

/// <https://spec.torproject.org/dir-spec/consensus-formats.html#item:voting-delay>

#[derive(Debug, Clone, Eq, PartialEq, Hash, Copy, Deftly)]

#[derive_deftly(Constructor, ItemValueEncodable, ItemValueParseable)]

#[allow(clippy::exhaustive_structs)]

pub struct VotingDelay {

    /// VoteSeconds

    #[deftly(constructor)]

    pub vote_seconds: u32,

    /// DistSeconds

    #[deftly(constructor)]

    pub dist_seconds: u32,

    #[doc(hidden)]

    #[deftly(netdoc(skip))]

    pub __non_exhaustive: (),

}

/// A set of named network parameters.

///

/// These are used to describe current settings for the Tor network,

/// current weighting parameters for path selection, and so on.  They're

/// encoded with a space-separated K=V format.

///

/// A `NetParams<i32>` is part of the validated directory manager configuration,

/// where it is built (in the builder-pattern sense) from a transparent HashMap.

///

/// As found in `params` in a network status:

/// <https://spec.torproject.org/dir-spec/consensus-formats.html#item:params>

///

/// The same syntax is also used, and this type used for parsing, in various other places,

/// for example routerstatus entry `w` items (bandwidth weights):

/// <https://spec.torproject.org/dir-spec/consensus-formats.html#item:w>

//

// TODO DIRAUTH torspec#401 Replace `String` with a suitable newtype

// Currently:

//  - Our parser allows any keyword that makes it into a netdoc argument,

//    but it splits on the *first* `=` so a `NetParams<i32>` cannot parse a keyword with a `=`.

//  - We provide constructors that allow any `String`, even ones containing space, `=`,

//    newline, etc.

//  - Encoding throws `Bug` if the resulting document will be clearly garbage,

//    forbidding `=`, whitespace, and controls.  If the supplied keywords are bizarre,

//    it may generate surprising documents (eg, containing exciting Unicode).

#[derive(Debug, Clone, Educe, Eq, PartialEq)]

#[educe(Default)]

pub struct NetParams<T> {

    /// Map from keys to values.

    params: HashMap<String, T>,

}

impl<T> NetParams<T> {

    /// Create a new empty list of NetParams.

    #[allow(unused)]

    /// Retrieve a given network parameter, if it is present.

    /// Return an iterator over all key value pairs in an arbitrary order.

    /// Set or replace the value of a network parameter.

}

impl<K: Into<String>, T> FromIterator<(K, T)> for NetParams<T> {

        NetParams {

        }

}

impl<T> std::iter::Extend<(String, T)> for NetParams<T> {

}

impl<'de, T> Deserialize<'de> for NetParams<T>

where

    T: Deserialize<'de>,

{

    {

}

/// A list of subprotocol versions that implementors should/must provide.

///

/// This struct represents a pair of (optional) items:

/// `recommended-FOO-protocols` and `required-FOO-protocols`.

///

/// Each consensus has two of these: one for relays, and one for clients.

///

/// <https://spec.torproject.org/dir-spec/consensus-formats.html#item:required-relay-protocols>

#[derive(Debug, Clone, Default, PartialEq, serde::Serialize, serde::Deserialize)]

pub struct ProtoStatus {

    /// Set of protocols that are recommended; if we're missing a protocol

    /// in this list we should warn the user.

    ///

    /// `recommended-client-protocols` or `recommended-relay-protocols`

    recommended: Protocols,

    /// Set of protocols that are required; if we're missing a protocol

    /// in this list we should refuse to start.

    ///

    /// `required-client-protocols` or `required-relay-protocols`

    required: Protocols,

}

impl ProtoStatus {

    /// Check whether the list of supported protocols

    /// is sufficient to satisfy this list of recommendations and requirements.

    ///

    /// If any required protocol is missing, returns [`ProtocolSupportError::MissingRequired`].

    ///

    /// Otherwise, if no required protocol is missing, but some recommended protocol is missing,

    /// returns [`ProtocolSupportError::MissingRecommended`].

    ///

    /// Otherwise, if no recommended or required protocol is missing, returns `Ok(())`.

        // Required protocols take precedence, so we check them first.

}

/// A subprotocol that is recommended or required in the consensus was not present.

#[derive(Clone, Debug, thiserror::Error)]

#[cfg_attr(test, derive(PartialEq))]

#[non_exhaustive]

pub enum ProtocolSupportError {

    /// At least one required protocol was not in our list of supported protocols.

    #[error("Required protocols are not implemented: {0}")]

    MissingRequired(Protocols),

    /// At least one recommended protocol was not in our list of supported protocols.

    ///

    /// Also implies that no _required_ protocols were missing.

    #[error("Recommended protocols are not implemented: {0}")]

    MissingRecommended(Protocols),

}

impl ProtocolSupportError {

    /// Return true if the suggested behavior for this error is a shutdown.

}

impl HasKind for ProtocolSupportError {

}

/// A set of recommended and required protocols when running

/// in various scenarios.

///

/// Represents the collection of four items: `{recommended,required}-{client,relay}-protocols`.

///

/// <https://spec.torproject.org/dir-spec/consensus-formats.html#item:required-relay-protocols>

#[derive(Clone, Debug, Default, PartialEq, serde::Serialize, serde::Deserialize)]

pub struct ProtoStatuses {

    /// Lists of recommended and required subprotocol versions for clients

    client: ProtoStatus,

    /// Lists of recommended and required subprotocol versions for relays

    relay: ProtoStatus,

}

impl ProtoStatuses {

    /// Return the list of recommended and required protocols for running as a client.

    /// Return the list of recommended and required protocols for running as a relay.

}

/// List of recommended Tor versions

///

/// As seen in `client-versions` and `server-versions` in the preamble.

///

/// Technically these are supposed to be as according to

/// "`version-spec.txt`" but we actually allow anything that doesn't contain commas.

///

/// <https://spec.torproject.org/dir-spec/consensus-formats.html#item:client-versions>

/// <https://spec.torproject.org/dir-spec/consensus-formats.html#item:server-versions>

///

/// An empty set means no information, not no recommended versions.

//

// TODO should we have a CommaSeparated<T> type for arguments like this?

// But maybe we wouldn't be able to use it here anyway because of

// the special handling of the missing value.

//

// This is yet a third version number representation in arti!  Here it's just String.

// TODO unify RecommendedTorVersions, RelayPlatform, TorVersion

// When this is fixed, remove the workaround in netstatus::test::roundtrip_netstatus

#[derive(Clone, Debug, Default, Eq, PartialEq, Ord, PartialOrd)] //

#[derive(derive_more::Deref, derive_more::Into)]

pub struct RecommendedTorVersions(BTreeSet<String>);

/// Erroneous "recommended Tor versions" information

#[derive(Clone, Debug, Eq, PartialEq, thiserror::Error)]

#[non_exhaustive]

pub enum InvalidRecommendedTorVersions {

    /// Identical version appears twice

    #[error("version {_0:?} contains whitespace")]

    ContainsWhitespace(String),

    /// Identical version appears twice

    #[error("version {_0:?} is repeated")]

    Repeated(String),

}

impl RecommendedTorVersions {

    /// Return a `RecommendedTorVersions` that has no information

    /// Does this `RecommendedTorVersions` have any information?

    ///

    /// Ie, is it not empty.

    ///

    /// The opposite of [`BTreeSet::is_empty()`] (which available via deref).

    /// Construct a RecommendedTorVersions from a list of strings

    #[allow(clippy::should_implement_trait)] // we can't due to coherence

    {

        }

}

impl FromStr for RecommendedTorVersions {

    type Err = InvalidRecommendedTorVersions;

}

impl Display for RecommendedTorVersions {

}

impl NormalItemArgument for RecommendedTorVersions {}

impl ItemValueEncodable for RecommendedTorVersions {

}

impl ItemValueParseable for RecommendedTorVersions {

        const FIELD: &str = "versions";

}

/// A recognized 'flavor' of consensus document.

///

/// The enum is exhaustive because the addition/removal of a consensus flavor

/// should indeed be a breaking change, as it would inevitable require

/// interfacing code to think about the handling of it.

///

/// <https://spec.torproject.org/dir-spec/computing-consensus.html#flavors>

#[derive(Copy, Clone, Debug, Eq, PartialEq, Hash, Ord, PartialOrd)]

#[allow(clippy::exhaustive_enums)]

pub enum ConsensusFlavor {

    /// A "microdesc"-flavored consensus.  This is the one that

    /// clients and relays use today.

    Microdesc,

    /// A "networkstatus"-flavored consensus.  It's used for

    /// historical and network-health purposes.  Instead of listing

    /// microdescriptor digests, it lists digests of full relay

    /// descriptors.

    Plain,

}

impl ConsensusFlavor {

    /// Return the name of this consensus flavor.

        }

    /// Try to find the flavor whose name is `name`.

    ///

    /// For historical reasons, an unnamed flavor indicates an "Plain"

    /// document.

            }

        }

}

define_derive_deftly! {

    /// Bespoke derives applied to [`DirectorySignatureHashAlgo`]

    ///

    /// Generates:

    ///

    ///  * [`DirectorySignaturesHashesAccu`]

    ///  * [`DirectorySignaturesHashesAccu::update_from`]

    ///  * [`DirectorySignaturesHashesAccu::hash_slice_for_verification`]

    DirectorySignaturesHashesAccu:

    ${define FNAME ${paste ${snake_case $vname}} }

    /// `directory-signature`a hash algorithm argument

    #[derive(Clone, Copy, Default, Debug, Eq, PartialEq, Deftly)]

    #[derive_deftly(AsMutSelf)]

    #[non_exhaustive]

    pub struct DirectorySignaturesHashesAccu {

      $(

        ${vattrs doc}

        pub $FNAME: Option<[u8; ${vmeta(hash_len) as expr}]>,

      )

    }

    impl DirectorySignaturesHashesAccu {

        /// Calculate the hash for a signature item and update this accumulator

            &mut self,

            algo: &DigestAlgoInSignature,

            body: &SignatureHashInputs,

        ) {

            // Update the hash in self.$UPDATE according to algorithm $AGLO

            // (uses dynamic bindings of those parameters)

            ${define HASH {

                // Avoid recalculating if we don't need to

                    let mut h = tor_llcrypto::d::$ALGO::new();

                    h.update(body.body().body());

                    h.update(body.signature_item_kw_spc);

                    h.finalize().into()

                });

            }}

            match &**algo {

              $(

                Some(KeywordOrString::Known($vtype)) => {

                    ${define UPDATE $FNAME}

                    ${define ALGO $vname}

                    $HASH

                }

              )

                None => {

                    ${define UPDATE sha1}

                    ${define ALGO Sha1}

                    $HASH

                }

                Some(KeywordOrString::Unknown(..)) => {}

            }

        }

        /// Return the hash value for a specific algorithm, as a slice

        ///

        /// `None` if the value wasn't computed.

        /// That shouldn't happen.

            match &**algo {

              $(

                Some(KeywordOrString::Known($vtype)) => Some(self.$FNAME.as_ref()?),

              )

                None => Some(self.sha1.as_ref()?),

                Some(KeywordOrString::Unknown(..)) => None,

            }

        }

    }

}

/// `directory-signature` hash algorithm argument

#[derive(Clone, Copy, Debug, Eq, PartialEq, strum::Display, strum::EnumString, Deftly)]

#[derive_deftly(DirectorySignaturesHashesAccu)]

#[non_exhaustive]

#[strum(serialize_all = "snake_case")]

pub enum DirectorySignatureHashAlgo {

    /// SHA-1

    #[deftly(hash_len = "20")]

    Sha1,

    /// SHA-256

    #[deftly(hash_len = "32")]

    Sha256,

}

/// `algorithm` field in a `directory-signature` item

///

/// This is extremely bizarre: it's an *optional item at the start of the arguments*!

// TODO SPEC #350

///

/// So we parse it with some kind of nightmarish lookahead.

///

/// Additionally, to be able to convey the signatures accurately, without breaking them,

/// we must remember whether the argument was present.

///

/// <https://spec.torproject.org/dir-spec/consensus-formats.html#item:directory-signature>

#[derive(Debug, Clone, derive_more::Deref, derive_more::DerefMut)]

#[allow(clippy::exhaustive_structs)]

pub struct DigestAlgoInSignature(pub Option<KeywordOrString<DirectorySignatureHashAlgo>>);

impl ItemArgumentParseable for DigestAlgoInSignature {

            // Treat it as a fingerprint if it doesn't have any non-hex characters

            // (including lowercase ones).  If we reuse this item for new algorithms

            // they should have at least one letter g-z in their name.

        {

            // next argument looks enough like a fingerprint that we don't treat as an algo name

        } else {

        };

}

impl ItemArgument for DigestAlgoInSignature {

}

impl DigestAlgoInSignature {

    /// Return the actual algorithm

    ///

    /// This handles the defaulting, where an absent argument means `sha1`.

}

impl NormalItemArgument for DirectorySignatureHashAlgo {}

/// The signature of a single directory authority on a networkstatus document.

///

/// Implements `ItemValueParseable` which parses without hashing anything;

/// this is mostly useful for use by the `SignatureItemParseable` implementation.

#[derive(Debug, Clone, Deftly)]

#[derive_deftly(ItemValueEncodable, ItemValueParseable)]

#[non_exhaustive]

pub struct Signature {

    /// The name of the digest algorithm used to make the signature.

    ///

    /// Currently sha1 and sh256 are recognized.  Here we only support

    /// sha256.

    pub digest_algo: DigestAlgoInSignature,

    /// Fingerprints of the keys for the authority that made

    /// this signature.

    #[deftly(netdoc(with = authcert::keyids_directory_signature_args))]

    pub key_ids: AuthCertKeyIds,

    /// The signature itself.

    #[deftly(netdoc(object(label = "SIGNATURE"), with = types::raw_data_object))]

    pub signature: Vec<u8>,

}

impl SignatureItemParseable for Signature {

    type HashAccu = DirectorySignaturesHashesAccu;

}

/// A collection of signatures that can be checked on a networkstatus document

///

/// This is derived from the signatures section of a netstatus,

/// <https://spec.torproject.org/dir-spec/consensus-formats.html#section:signature>,

/// but it is not isomorphic to it, and is not directly parseable.

#[derive(Debug, Clone)]

#[non_exhaustive]

pub struct SignatureGroup {

    /// The document hashes of the signed part of the document

    ///

    /// The pre-parse2 parser always sets `hashes.sha1` and `hashes.sha1_unnamed`

    /// to the same value, which is wrong. which is

    /// [bug #2530](https://gitlab.torproject.org/tpo/core/arti/-/work_items/2530)

    pub hashes: DirectorySignaturesHashesAccu,

    /// The signatures listed on the document.

    pub signatures: Vec<Signature>,

}

/// Error which will prevent us from attempting to verify signatures on a consensus

///

/// This error occurs if we the consensus isn't signed by the right people,

/// or we are lacking authcerts.

///

/// Does not represent actual verification errors.

/// Those show up as `VerifyFailed`, typically [`ConsensusVerifyFailed::InvalidSignature`].

///

/// Can be converted to a `VerifyFailed`,

/// giving [`InsufficientTrustedSigners`](VerifyFailed::InsufficientTrustedSigners).

#[derive(Clone, Debug, thiserror::Error)]

#[allow(clippy::exhaustive_enums)]

pub enum ConsensusVerifiabilityError {

    /// Insufficient trusted signers

    #[error("consensus not signed by enough authorities")]

    InsufficientTrustedSigners,

    /// Insufficient trusted signers because we are missing authcerts

    #[error("missing auth certs mean we could not verify enough consensuis signatures (need at least {deficit} more, out of {} that are missing)", missing.len())]

    MissingAuthCerts {

        /// The number of additional useful authcerts that would be sufficient

        deficit: usize,

        /// All the authcerts that would be useful

        missing: HashSet<AuthCertKeyIds>,

    },

}

/// Error encountered while verifying a consensus

///

/// Thrown by

/// [`plain::NetworkStatusUnverified::verify`]

/// and

/// [`md::NetworkStatusUnverified::verify`].

///

/// Not used for problems with the validity period:

/// that's handled by `tor-checkable` and shows up as [`tor_checkable::TimeValidityError`].

///

/// Can be converted to a `VerifyFailed` (which, in effect, summarises the error).

#[derive(Clone, Debug, thiserror::Error)]

#[non_exhaustive]

pub enum ConsensusVerifyFailed {

    /// Certificates or signatures insufficient

    #[error("certs/sigs insufficient")]

    CertificationInsufficient(#[from] ConsensusVerifiabilityError),

    /// One or more signatures failed to verify

    #[error("invalid signature")]

    //

    // Not `#[from]` because we don't want to accidentally convert

    // ConsensusVerifiabilityError -> VerifyFailed -> ConsensusVerifyFailed

    // since that would give the wrong variant.

    InvalidSignature(#[source] VerifyFailed),

}

/// Error encountered while verifying a vote

///

/// Thrown by

/// [`vote::NetworkStatusUnverified::verify`].

///

/// Not used for problems with the validity period:

/// that's handled by `tor-checkable` and shows up as [`tor_checkable::TimeValidityError`].

///

/// Can be converted to a `VerifyFailed` (which, in effect, summarises the error).

#[derive(Clone, Debug, thiserror::Error)]

#[non_exhaustive]

pub enum VoteVerifyFailed {

    /// The document signature failed to verify

    #[error("invalid signature")]

    //

    // Not `#[from]` because we don't want to accidentally convert

    // VoteVerifyFailed::Something -> VerifyFailed -> VoteVerifyFailed

    // since that would give the wrong variant.

    InvalidSignature(#[source] VerifyFailed),

    /// Authcert couldn't be parsed

    #[error("unparseable authcert")]

    AuthCertParseError(#[source] parse2::ParseError),

    /// Authcert isn't valid for this vote's validity period

    #[error("authcert not valid for vote period")]

    AuthCertWrongValidity(#[source] tor_checkable::TimeValidityError),

    /// Authcert is for a different authority

    #[error("wrong authcert")]

    AuthCertWrongAuthority,

}

/// A shared random value produced by the directory authorities.

#[derive(

    Debug, Clone, Copy, Eq, PartialEq, derive_more::From, derive_more::Into, derive_more::AsRef,

)]

// (This doesn't need to use CtByteArray; we don't really need to compare these.)

pub struct SharedRandVal([u8; 32]);

/// A shared-random value produced by the directory authorities,

/// along with meta-information about that value.

#[derive(Debug, Clone, Deftly)]

#[non_exhaustive]

#[derive_deftly(ItemValueEncodable, ItemValueParseable)]

pub struct SharedRandStatus {

    /// How many authorities revealed shares that contributed to this value.

    pub n_reveals: u8,

    /// The current random value.

    ///

    /// The properties of the secure shared-random system guarantee

    /// that this value isn't predictable before it first becomes

    /// live, and that a hostile party could not have forced it to

    /// have any more than a small number of possible random values.

    pub value: SharedRandVal,

    /// The time when this SharedRandVal becomes (or became) the latest.

    ///

    /// (This is added per proposal 342, assuming that gets accepted.)

    pub timestamp: Option<Iso8601TimeNoSp>,

}

/// The two shared random values, `shared-rand-*-value`

///

/// As found in the consensus preamble

/// <https://spec.torproject.org/dir-spec/consensus-formats.html#item:shared-rand-current-value>

/// and a vote's authority section

/// <https://spec.torproject.org/dir-spec/consensus-formats.html#authority-item-shared-rand-value>

#[derive(Debug, Clone, Default, Deftly)]

#[derive_deftly(Constructor, NetdocEncodableFields, NetdocParseableFields)]

#[allow(clippy::exhaustive_structs)]

pub struct SharedRandStatuses {

    /// Global shared-random value for the previous shared-random period.

    pub shared_rand_previous_value: Option<SharedRandStatus>,

    /// Global shared-random value for the current shared-random period.

    pub shared_rand_current_value: Option<SharedRandStatus>,

    #[doc(hidden)]

    #[deftly(netdoc(skip))]

    pub __non_exhaustive: (),

}

/// Relay weight information - `w` item in routerstatus in consensuses

///

/// This is a combination of two representations of (subsets of) the same information,

/// from an optional `w` in the document.

///

///  * [`effective`](RelayWeightsItem::effective):

///

///    Always contains the effective weight, as [`RelayWeight`].

///    This is what is used by clients.

///    It does not record whether a `w` line was actually present.

///

///  * [`params`](RelayWeightsItem::params):

///

///    Can represent the presence and whole contents of the `w` line,

///    including all the known and unknown parameters.

///    This is within [`Unknown`], so it is only present with crate `feature = "retain-unknown"`,

///    and only some constructors/parsers record it.

///

/// # Parsing

///

/// Parsing is done with `NetdocParseableFields` rather than `ItemValueParseable`.

/// The `params` are [`Retained`](Unknown::Retained) if `retain_unknown_values` is

/// selected in [`parse2::ParseOptions`].

//

// We use NetdocParseableFields because the containing document, RouterStatus,

// contains `RelayWeightsItem` rather than `Option<RelayWeightsItem>`.

// The item parsing multiplicity machinery would see plain `RelayWeightsItem` as a required item.

//

// This representation also means so that if retaining unknown information is compiled out

// (ie, in clients) each routerstatus entry stored in memory does not need to record

// whether `w` was present, merely what the implications were.

//

// We can't use ItemValueParseable with #[deftly(netdoc(default))]

// because `RelayWeightsItem::default()` is a RelayWeightsItem that definitively

// contains no pazrameters, ie with `Unknown::Retained`,

// and is therefore only conditionally available.

/// # Encoding

///

/// Encoding requires knowing whether a `w` line is to be included, and its contents,

/// so is implemented only with if `effective` is `Unknown::Retained`.

/// The encoding impl is only compiled in with `"retain-unknown"`,

/// and throws [`Bug`] if applied to a `RelayWeightsItem` whose `params` are `Discarded`.

///

/// # Constructors

///

/// An "empty" `RelayWeightsItem` can be constructed with [`RelayWeightsItem::new_no_info`].

///

/// A `RelayWeightsItem` containing only the effective `RelayWeight`

/// can be constructed using [`RelayWeightsItem::from_effective`].

///

/// With `"retain-unknown"`:

/// a `RelayWeightsItem` can be constructed from a [`NetParams<u32>`] using `TryFrom`;

/// and, implements `Default`, which yields a `RelayWeightsItem`

/// representing the (known) absence of a `w` line.

//

// Fields are private to maintain the invariant.

#[derive(Debug, Clone)]

pub struct RelayWeightsItem {

    /// The effective relay weight

    effective: RelayWeight,

    /// The complete parameter set, if available and `w` was present.

    params: Unknown<Option<NetParams<u32>>>,

}

/// Relay weight information - `w` item in routerstatus in votes

#[derive(Debug, Clone, Deftly)]

#[derive_deftly(NetdocEncodableFields, NetdocParseableFields)]

#[allow(clippy::exhaustive_structs)] // this is always just this single item

pub struct VoteRelayWeightsItem {

    /// The parameters, uninterpreted.

    pub w: Option<NetParams<u32>>,

}

/// Recognized weight fields on a single relay in a consensus

///

/// The part of a `w` item that we understand as a client.

#[non_exhaustive]

#[derive(Debug, Clone, Copy)]

pub enum RelayWeight {

    /// An unmeasured weight for a relay.

    Unmeasured(u32),

    /// An measured weight for a relay.

    Measured(u32),

}

/// Error processing a `w` line's netparams into an effective relay weight

#[derive(Debug, Clone, thiserror::Error)]

#[non_exhaustive]

pub enum InvalidRelayWeights {

    /// Invalid value for `Unmeasured`

    #[error("invalid value for Unmeasured")]

    InvalidUnmeasured,

}

/// Authority entry in a consensus - deprecated compatibility type alias

#[deprecated = "renamed to ConsensusAuthorityEntry"]

pub type ConsensusVoterInfo = ConsensusAuthorityEntry;

/// Authority entry in a plain consensus - type alias provided for consistency

pub type PlainAuthorityEntry = ConsensusAuthorityEntry;

/// Authority entry in an md consensus - type alias provided for consistency

pub type MdAuthorityEntry = ConsensusAuthorityEntry;

/// An authority entry as found in a consensus

///

/// <https://spec.torproject.org/dir-spec/consensus-formats.html#section:authority-entry>

///

/// See also [`VoteAuthorityEntry`]

//

// We don't use the `each_variety` system for this because:

//  1. That avoids separating the two consensus authority entry types, which are identical

//  2. The only common fields are `dir-source` and `contact`, so there is little duplication

#[derive(Debug, Clone, Deftly)]

#[derive_deftly(Constructor, NetdocEncodable, NetdocParseable)]

#[allow(clippy::exhaustive_structs)]

pub struct ConsensusAuthorityEntry {

    /// Contents of the `dir-source` line about an authority

    #[deftly(constructor)]

    pub dir_source: DirSource,

    /// Human-readable contact information about the authority

    //

    // If more non-intro fields get added that are the same in votes and cosensuses,

    // consider using each_variety.rs or breaking those fields out into

    // `AuthorityEntryCommon` implementing `NetdocParseableFields`, or something.

    #[deftly(constructor)]

    pub contact: ContactInfo,

    /// Digest of the vote that the authority cast to contribute to

    /// this consensus.

    ///

    /// This is not a fixed-length, fixed-algorithm field.

    /// Bizarrely, the algorithm is supposed to be inferred from the length!

    /// <https://spec.torproject.org/dir-spec/consensus-formats.html#item:vote-digest>

    #[deftly(netdoc(single_arg))]

    #[deftly(constructor)]

    pub vote_digest: B16U,

    #[doc(hidden)]

    #[deftly(netdoc(skip))]

    pub __non_exhaustive: (),

}

/// An authority entry as found in a vote

///

/// <https://spec.torproject.org/dir-spec/consensus-formats.html#section:authority-entry>

///

/// See also [`ConsensusAuthorityEntry`]

#[derive(Debug, Clone, Deftly)]

#[derive_deftly(Constructor, NetdocEncodable, NetdocParseable)]

#[allow(clippy::exhaustive_structs)]

pub struct VoteAuthorityEntry {

    /// Contents of the `dir-source` line about an authority

    #[deftly(constructor)]

    pub dir_source: DirSource,

    /// Human-readable contact information about the authority

    #[deftly(constructor)]

    pub contact: ContactInfo,

    /// `legacy-dir-key` - superseded authority identity key

    ///

    /// <https://spec.torproject.org/dir-spec/consensus-formats.html#item:legacy-dir-key>

    #[deftly(netdoc(single_arg))]

    pub legacy_dir_key: Option<Fingerprint>,

    /// `shared-rand-participate` - Indicate shared random participation

    ///

    /// <https://spec.torproject.org/dir-spec/consensus-formats.html#item:shared-rand-participate>

    pub shared_rand_participate: Option<SharedRandParticipate>,

    /// `shared-rand-commit` - Shared random commitment

    ///

    /// <https://spec.torproject.org/dir-spec/consensus-formats.html#item:shared-rand-commit>

    pub shared_rand_commit: Vec<SharedRandCommit>,

    /// Global shared-random values

    #[deftly(netdoc(flatten))]

    pub shared_rand: SharedRandStatuses,

    #[doc(hidden)]

    #[deftly(netdoc(skip))]

    pub __non_exhaustive: (),

}

/// `shared-rand-participate` in a vote authority entry

///

/// <https://spec.torproject.org/dir-spec/consensus-formats.html#item:shared-rand-participate>

//

// We could have done `shared_rand_participate: Option<()>` in VoteAuthorityEntry,

// but then we might end up with variables of type `&Option<()>` etc.

// whose meaning has been detached from its type.

//

// TODO DIRAUTH rework this according to the API design conclusion from !3977 when there is one

#[derive(Debug, Clone, Deftly)]

#[derive_deftly(Constructor, ItemValueEncodable, ItemValueParseable)]

#[allow(clippy::exhaustive_structs)]

pub struct SharedRandParticipate {

    #[doc(hidden)]

    #[deftly(netdoc(skip))]

    pub __non_exhaustive: (),

}

/// `shared-rand-commit` in a vote authority entry

///

/// <https://spec.torproject.org/dir-spec/consensus-formats.html#item:shared-rand-commit>

#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Deftly)]

// If new protocols use this item with a different version, we'll call it an API break.

#[allow(clippy::exhaustive_enums)]

pub enum SharedRandCommit {

    /// Version 1, the only one supported

    V1(SharedRandCommitV1),

    /// Other versions.  Cannot be encoded.

    // It's not clear that future versions will use this version mechanism.  torspec#408.

    Unknown {},

}

/// `shared-rand-commit` in a vote authority entry

///

/// <https://spec.torproject.org/dir-spec/consensus-formats.html#item:shared-rand-commit>

///

/// Version and hash are not explicitly represented.  See torspec#407.

///

/// `ItemValueEncodable` and `ItemValueParseable` impls do not include the fixed arguments;

/// in a netdoc, this type should be used within `SharedRandCommit::V1`.

#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Deftly)]

#[derive_deftly(Constructor, ItemValueEncodable, ItemValueParseable)]

#[allow(clippy::exhaustive_structs)]

pub struct SharedRandCommitV1 {

    /// Authority id key, recapitulated.

    // TODO this field shouldn't here at all torspec#407

    #[deftly(constructor)]

    h_kp_auth_id_rsa: Fingerprint,

    /// Commitment

    ///

    /// `TIMESTAMP || SHA3_256(REVEAL)`, as per

    /// <https://spec.torproject.org/srv-spec/specification.html#COMMITREVEAL>

    //

    // TOOD we would like to replace this with a type that separates out the pieces!

    // But that would need a FixedB64 generic over some tor-bytes trait, or something.

    #[deftly(constructor)]

    commit: FixedB64<40>,

    /// Reveal

    ///

    /// `TIMESTAMP || random number`, as per

    /// <https://spec.torproject.org/srv-spec/specification.html#COMMITREVEAL>

    reveal: Option<FixedB64<40>>,

    #[doc(hidden)]

    #[deftly(netdoc(skip))]

    pub __non_exhaustive: (),

}

impl SharedRandCommitV1 {

    /// The fixed arguments that precede the actual value in `shared-rand-commit 1 ...`

    const FIXED_ARGUMENTS: &[&str] = &["1", "sha3-256"];

}

impl ItemValueEncodable for SharedRandCommit {

            }

        }

}

impl ItemValueParseable for SharedRandCommit {

        }

}

// For `ConsensusAuthoritySection`, see `dir_source.rs`.

define_derive_deftly! {