//! Types used to parse arguments of entries in a directory document.

//!

//! There are some types that are pretty common, like "ISOTime",

//! "base64-encoded data", and so on.

//!

//! These types shouldn't be exposed outside of the netdoc crate.

pub use b16impl::*;

pub use b64impl::*;

pub use contact_info::*;

pub use curve25519impl::*;

pub use ed25519impl::*;

#[cfg(any(feature = "routerdesc", feature = "hs-common"))]

pub(crate) use edcert::*;

pub use fingerprint::*;

pub use hostname::*;

pub use rsa::*;

pub use timeimpl::*;

pub use nickname::{InvalidNickname, Nickname};

pub use boolean::NumericBoolean;

pub use fingerprint::{Base64Fingerprint, Fingerprint};

pub use identified_digest::{DigestName, IdentifiedDigest};

pub use ignored_impl::{Ignored, IgnoredItemOrObjectValue, NotPresent};

use crate::NormalItemArgument;

use crate::encode::{

    self,

    ItemArgument,

    ItemEncoder,

    ItemObjectEncodable,

    ItemValueEncodable,

    // `E` for "encode`; different from `parse2::MultiplicitySelector`

    MultiplicitySelector as EMultiplicitySelector,

    NetdocEncoder,

};

use crate::parse2::{

    self, ArgumentError, ArgumentStream, ItemArgumentParseable, ItemObjectParseable,

    ItemValueParseable, SignatureHashInputs, SignatureItemParseable, UnparsedItem,

    multiplicity::{

        ItemSetMethods,

        // `P2` for "parse2`; different from `encode::MultiplicitySelector`

        MultiplicitySelector as P2MultiplicitySelector,

        ObjectSetMethods,

    },

    sig_hashes::Sha1WholeKeywordLine,

};

use derive_deftly::{Deftly, define_derive_deftly, define_derive_deftly_module};

use digest::Digest as _;

use educe::Educe;

use std::cmp::{self, PartialOrd};

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

use std::iter;

use std::marker::PhantomData;

use std::ops::{Deref, DerefMut};

use std::result::Result as StdResult;

use std::str::FromStr;

use subtle::{Choice, ConstantTimeEq};

use tor_error::{Bug, ErrorReport as _, internal, into_internal};

use void::{ResultVoidExt as _, Void};

/// Describes a value that van be decoded from a bunch of bytes.

///

/// Used for decoding the objects between BEGIN and END tags.

pub(crate) trait FromBytes: Sized {

    /// Try to parse a value of this type from a byte slice

    fn from_bytes(b: &[u8], p: crate::Pos) -> crate::Result<Self>;

    /// Try to parse a value of this type from a vector of bytes,

    /// and consume that value

}

define_derive_deftly_module! {

    /// Implement conversion traits for a transparent newtype around bytes - shared code

    ///

    /// This is precisely `#[derive_deftly(Transparent)]`, but in the form of a deftly module,

    /// so that other derives (eg `BytesTransparent`) can re-use it.

    Transparent beta_deftly:

    // Expands to bullet points for "generated code", except omitting

    // `AsRef` & `AsMut` because some uses sites have additional impls of those,

    // which are best presented together in the docs.

  ${define TRANSPARENT_DOCS_IMPLS {

    ///  * impls of `Deref`, `DerefMut`

    ///  * impls of `From<field>` and "`Into`" (technically, `From<Self> for field`)

  }}

    // Expands to the implementations

  ${define TRANSPARENT_IMPLS {

  ${for fields {

    ${loop_exactly_1 "must be applied to a single-field struct"}

    impl<$tgens> From<$ftype> for $ttype {

            $vpat

        }

    }

    impl<$tgens> From<$ttype> for $ftype {

            self_.$fname

        }

    }

    impl<$tgens> Deref for $ttype {

        type Target = $ftype;

            &self.$fname

        }

    }

    impl<$tgens> DerefMut for $ttype {

            &mut self.$fname

        }

    }

    impl<$tgens> AsRef<$ftype> for $ttype {

            &self.$fname

        }

    }

    impl<$tgens> AsMut<$ftype> for $ttype {

            &mut self.$fname

        }

    }

  }}

  }}

}

define_derive_deftly! {

    use Transparent;

    /// Implement conversion traits for an arbitrary transparent newtype

    ///

    /// # Requirements

    ///

    ///  * Self should be a single-field struct

    ///  * Self should have no runtime invariants

    ///

    /// # Generated code

    ///

    $TRANSPARENT_DOCS_IMPLS

    ///  * impls of `AsMut<field>`, `AsRef<field>`

    ///

    /// # Guidelines

    ///

    ///  * the field should be `pub`, with `#[allow(clippy::exhaustive_structs)]`

    ///  * derive `Hash`, `Debug` and (usually) `Clone`

    ///  * consider deriving `PartialEq` and `Eq`

    ///    but for types containing bytes, use [`ConstantTimeEq`],

    ///    eg with [`#[derive_deftly(BytesTransparent)]`](derive_deftly_template_BytesTransparent)

    ///    (instead of `Transparent`).

    ///  * implement `FromStr`, `Display`, `NormalItemArgument`, as required

    Transparent for struct, beta_deftly:

    $TRANSPARENT_IMPLS

}

define_derive_deftly! {

    use Transparent;

    /// Implement `ConstantTimeEq`, `.as_bytes()`, etc., for a transparent newtype around bytes

    ///

    /// # Requirements

    ///

    ///  * Self should be a single-field struct

    ///  * Self should deref to `&[u8]` (and to `&mut [u8]`).

    ///  * (so Self should have no runtime invariants)

    ///

    /// # Generated code

    ///

    ///  * impls of `ConstantTimeEq`, `Eq`, `PartialEq`

    ///  * `as_bytes()` method

    ${TRANSPARENT_DOCS_IMPLS}

    ///  * impls of `AsMut<field>`, `AsRef<field>`, `AsRef<[u8]>`, `AsMut<[u8]>`

    ///

    // We could derive Debug here but then we have to deal with the Fixed's N

    // which gets quite fiddly.

    //

    /// # Guidelines

    ///

    ///  * derive `Hash` and write `#[allow(clippy::derived_hash_with_manual_eq)]`

    ///  * impl `FromStr` and `Display` (if required, which they usually will be)

    ///  * derive `derive_more::Debug` eg with `#[debug(r#"B64("{self}")"#)]`

    ///  * `impl NormalItemArgument` if appropriate (ie the representation has no spaces)

    BytesTransparent for struct, beta_deftly:

    $TRANSPARENT_IMPLS

    impl<$tgens> ConstantTimeEq for $ttype {

          $(

          )

    }

    $/// `$tname` is `Eq` via its constant-time implementation.

    impl<$tgens> PartialEq for $ttype {

    }

    impl<$tgens> Eq for $ttype {}

    impl<$tgens> $ttype {

        /// Return the byte array from this object.

          $(

          )

    }

    impl<$tgens> AsRef<[u8]> for $ttype {

          $(

          )

    }

    impl<$tgens> AsMut<[u8]> for $ttype {

          $(

          )

    }

}

/// Types for decoding base64-encoded values.

mod b64impl {

    use super::*;

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

    use base64ct::{Base64, Base64Unpadded, Encoding};

    use std::ops::RangeBounds;

    /// A byte array, encoded in base64 with optional padding.

    ///

    /// On output (`Display`), output is unpadded.

    #[derive(Clone, Hash, Deftly)]

    #[derive_deftly(BytesTransparent)]

    #[allow(clippy::derived_hash_with_manual_eq)]

    #[derive(derive_more::Debug)]

    #[debug(r#"B64("{self}")"#)]

    #[allow(clippy::exhaustive_structs)]

    pub struct B64(pub Vec<u8>);

    impl FromStr for B64 {

        type Err = Error;

            };

    }

    impl Display for B64 {

    }

    impl B64 {

        /// Return this object if its length is within the provided bounds

        /// object, or an error otherwise.

            } else {

            }

        /// Try to convert this object into an array of N bytes.

        ///

        /// Return an error if the length is wrong.

    }

    impl FromIterator<u8> for B64 {

    }

    impl NormalItemArgument for B64 {}

    /// A byte array encoded in a hexadecimal with a fixed length.

    #[derive(Clone, Hash, Deftly)]

    #[derive_deftly(BytesTransparent)]

    #[allow(clippy::derived_hash_with_manual_eq)]

    #[derive(derive_more::Debug)]

    #[debug(r#"FixedB64::<{N}>("{self}")"#)]

    #[allow(clippy::exhaustive_structs)]

    pub struct FixedB64<const N: usize>(pub [u8; N]);

    impl<const N: usize> Display for FixedB64<N> {

    }

    impl<const N: usize> FromStr for FixedB64<N> {

        type Err = Error;

    }

    impl<const N: usize> NormalItemArgument for FixedB64<N> {}

}

// ============================================================

/// Types for decoding hex-encoded values.

mod b16impl {

    use super::*;

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

    /// A byte array encoded in hexadecimal; prints in lowercase

    ///

    /// Both uppercase and lowercase are tolerated when parsing.

    #[derive(Clone, Hash, Deftly)]

    #[derive_deftly(BytesTransparent)]

    #[allow(clippy::derived_hash_with_manual_eq)]

    #[derive(derive_more::Debug)]

    #[debug(r#"B16("{self}")"#)]

    #[allow(clippy::exhaustive_structs)]

    pub struct B16(pub Vec<u8>);

    /// A byte array encoded in hexadecimal; prints in uppercase

    ///

    /// Both uppercase and lowercase are tolerated when parsing.

    #[derive(Clone, Hash, Deftly)]

    #[derive_deftly(BytesTransparent)]

    #[allow(clippy::derived_hash_with_manual_eq)]

    #[derive(derive_more::Debug)]

    #[debug(r#"B16U("{self}")"#)]

    #[allow(clippy::exhaustive_structs)]

    pub struct B16U(pub Vec<u8>);

    /// A fixed-length version of [`B16U`].

    #[derive(Clone, Hash, Deftly)]

    #[derive_deftly(BytesTransparent)]

    #[allow(clippy::derived_hash_with_manual_eq)]

    #[derive(derive_more::Debug)]

    #[debug(r#"FixedB16U("{self}")"#)]

    #[allow(clippy::exhaustive_structs)]

    pub struct FixedB16U<const N: usize>(pub [u8; N]);

    impl FromStr for B16 {

        type Err = Error;

    }

    impl FromStr for B16U {

        type Err = Error;

    }

    impl<const N: usize> FromStr for FixedB16U<N> {

        type Err = Error;

    }

    impl Display for B16 {

            // `hex` has `hex::encode` but that allocates a `String`, which this approach doesn't

            }

    }

    impl Display for B16U {

            // `hex` has `hex::encode_upper` but that allocates a `String`

            }

    }

    impl<const N: usize> Display for FixedB16U<N> {

            // TODO DIRAUTH combine this with the same code in `Display for B16U`

            // `hex` has `hex::encode_upper` but that allocates a `String`

            }

    }

    impl NormalItemArgument for B16 {}

    impl NormalItemArgument for B16U {}

    impl<const N: usize> NormalItemArgument for FixedB16U<N> {}

}

// ============================================================

/// Types for decoding curve25519 keys

mod curve25519impl {

    use super::*;

    use crate::{Error, NormalItemArgument, Result, types::misc::FixedB64};

    use tor_llcrypto::pk::curve25519::PublicKey;

    /// A Curve25519 public key, encoded in base64 with optional padding

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

    #[derive_deftly(Transparent)]

    #[allow(clippy::exhaustive_structs)]

    pub struct Curve25519Public(pub PublicKey);

    impl FromStr for Curve25519Public {

        type Err = Error;

    }

    impl Display for Curve25519Public {

    }

    impl NormalItemArgument for Curve25519Public {}

}

// ============================================================

/// Types for decoding ed25519 keys

mod ed25519impl {

    use super::*;

    use crate::{Error, NormalItemArgument, Result, types::misc::FixedB64};

    use derive_deftly::Deftly;

    use tor_llcrypto::pk::ed25519::{Ed25519Identity, Signature};

    /// An alleged ed25519 public key, encoded in base64 with optional

    /// padding.

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

    #[allow(clippy::exhaustive_structs)]

    pub struct Ed25519Public(pub Ed25519Identity);

    impl FromStr for Ed25519Public {

        type Err = Error;

    }

    impl Display for Ed25519Public {

    }

    impl NormalItemArgument for Ed25519Public {}

    impl From<Ed25519Public> for Ed25519Identity {

    }

    /// Helper that checks for the presence of `ed25519`.

    #[derive(Debug, Clone, PartialEq, Eq, derive_more::Display, derive_more::FromStr)]

    #[display(rename_all = "lowercase")]

    #[from_str(rename_all = "lowercase")]

    #[allow(clippy::exhaustive_enums)]

    pub enum Ed25519AlgorithmString {

        /// Ed25519 encoded as `ed25519`.

        Ed25519,

    }

    impl NormalItemArgument for Ed25519AlgorithmString {}

    /// An Ed25519 public key found in a micro descriptor `id` line.

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

    #[derive_deftly(ItemValueParseable)]

    #[non_exhaustive]

    pub struct Ed25519IdentityLine {

        /// Fixed magic identifier (`ed25519`) for this line.

        pub alg: Ed25519AlgorithmString,

        /// The actual Ed25519 identity.

        pub pk: Ed25519Public,

    }

    impl From<Ed25519Public> for Ed25519IdentityLine {

    }

    impl From<Ed25519Identity> for Ed25519IdentityLine {

    }

    impl ItemArgument for Signature {

    }

}

// ============================================================

/// Dummy types like [`Ignored`]

mod ignored_impl {

    use super::*;

    use crate::parse2::ErrorProblem as EP;

    /// Part of a network document, that isn't actually there.

    ///

    /// Used as a standin in `ns_type!` calls in various netstatus `each_variety.rs`.

    /// The effect is as if the field were omitted from the containing type.

    ///

    ///  * When used as item(s) (ie, a field type when deriving `NetdocParseable\[Fields\]`):

    ///    **ignores any number** of items with that field's keyword during parsing,

    ///    and emits none during encoding.

    ///

    ///    (To *reject* documents containing this item, use `Option<Void>`,

    ///    but note that the spec says unknown items should be ignored,

    ///    which would normally include items which are merely missing from one variety.)

    ///

    ///  * When used as an argument (ie, a field type when deriving `ItemValueParseable`,

    ///    or with `netdoc(single_arg)`  when deriving `NetdocParseable\[Fields\]`):

    ///    consumes **no arguments** during parsing, and emits none during encoding.

    ///

    ///  * When used as an object field (ie, `netdoc(object)` when deriving `ItemValueParseable`):

    ///    **rejects** an object - failing the parse if one is present.

    ///    (Functions similarly to `Option<Void>`, but prefer `NotPresent` as it's clearer.)

    ///

    /// There are bespoke impls of the multiplicity traits

    /// `ItemSetMethods` and `ObjectSetMethods`:

    /// don't wrap this type in `Option` or `Vec`.

    //

    // TODO we'll need to implement ItemArgument etc., for encoding, too.

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

    #[allow(clippy::exhaustive_structs)]

    #[derive(Deftly)]

    #[derive_deftly(NetdocParseableFields)]

    pub struct NotPresent;

    /// Ignored part of a network document.

    ///

    /// With `parse2`, can be used as an item, object, or even flattened-fields.

    ///

    /// When deriving `parse2` traits, and a field is absent in a particular netstatus variety,

    /// use `ns_type!` with [`NotPresent`], rather than `Ignored`.

    ///

    /// During encoding as an Items or Objects, will be entirely omitted,

    /// via the multiplicity arrangements.

    ///

    /// Cannot be encoded as an Argument: if this is not the last

    /// Argument, we need something to put into the output document to avoid generating

    /// a document with the arguments out of step.  If it *is* the last argument,

    /// it could simply be omitted, since additional arguments are in any case ignored.

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

    #[derive_deftly(ItemValueParseable, NetdocParseableFields)]

    #[allow(clippy::exhaustive_structs)]

    pub struct Ignored;

    /// An Item or Object that would be ignored during parsing and is omitted during encoding

    ///

    /// This is the "single" item type for encoding multiplicity for Items or Objects,

    /// for [`Ignored`].

    ///

    /// This type is uninhabited.

    pub struct IgnoredItemOrObjectValue(Void);

    impl ItemSetMethods for P2MultiplicitySelector<NotPresent> {

        type Each = Ignored;

        type Field = NotPresent;

    }

    impl ItemArgumentParseable for NotPresent {

    }

    impl ObjectSetMethods for P2MultiplicitySelector<NotPresent> {

        type Field = NotPresent;

        type Each = Void;

    }

    impl<'f> encode::MultiplicityMethods<'f> for EMultiplicitySelector<NotPresent> {

        type Field = NotPresent;

        type Each = Void;

    }

    impl encode::OptionalityMethods for EMultiplicitySelector<NotPresent> {

        type Field = NotPresent;

        type Each = Void;

    }

    impl FromStr for Ignored {

        type Err = Void;

    }

    impl ItemArgumentParseable for Ignored {

    }

    impl ItemObjectParseable for Ignored {

            // allow any label

    }

    impl ObjectSetMethods for P2MultiplicitySelector<Ignored> {

        type Field = Ignored;

        type Each = Ignored;

    }

    impl<'f> encode::MultiplicityMethods<'f> for EMultiplicitySelector<Ignored> {

        type Field = Ignored;

        type Each = IgnoredItemOrObjectValue;

    }

    impl encode::OptionalityMethods for EMultiplicitySelector<Ignored> {

        type Field = Ignored;

        type Each = IgnoredItemOrObjectValue;

    }

    impl ItemValueEncodable for IgnoredItemOrObjectValue {

        }

    }

    impl ItemObjectEncodable for IgnoredItemOrObjectValue {

        }

        }

    }

}

// ============================================================

/// Information about unknown values, which may have been retained as a `T`

///

/// Won't grow additional variants - but, `Retained` is only included conditionally.

///

/// Also used in the form `Unknown<()>` to indicate whether unknown values *should* be retained.

///

/// ### Example

///

/// ```

/// # {

/// #![cfg(feature = "retain-unknown")]

///

/// use tor_netdoc::types::Unknown;

///

/// let mut unk: Unknown<Vec<String>> = Unknown::new_retained_default();

/// unk.with_mut_unknown(|u| u.push("something-we-found".into()));

/// assert_eq!(unk.into_retained().unwrap(), ["something-we-found"]);

/// # }

/// ```

///

/// ### Equality comparison, semantics

///

/// Two `Unknown` are consider equal if both have the same record of unknown values,

/// or if neither records unknown values at all.

///

/// `Unknown` is not `Eq` or `Ord` because we won't want to relate a `Discarded`

/// to a `Retained`.  That would be a logic error.  `partial_cmp` gives `None` for this.

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

#[non_exhaustive]

pub enum Unknown<T> {

    /// The parsing discarded unknown values and they are no longer available.

    Discarded(PhantomData<T>),

    /// The document parsing retained (or should retain) unknown values.

    #[cfg(feature = "retain-unknown")]

    Retained(T),

}

impl<T> Unknown<T> {

    /// Create an `Unknown` which specifies that values were discarded (or should be)

    /// Map the `Retained`, if there is one

    /// Map the `Retained`, fallibly

            #[cfg(feature = "retain-unknown")]

        })

    /// Obtain an `Unknown` containing (maybe) a reference

            #[cfg(feature = "retain-unknown")]

        }

    /// Obtain the `Retained` data

    ///

    /// Treats lack of retention as an internal error.

    #[cfg(feature = "retain-unknown")]

        }

    /// Start recording unknown information, with a default value for `T`

    #[cfg(feature = "retain-unknown")]

    {

    /// Update the `Retained`, if there is one

    ///

    /// Intended for use in parsing, when we encounter an unknown value.

    ///

    /// Not provided in `try_` form.  If you think you need this, instead, unconditionally

    /// parse and verify the unknown value, and then conditionally insert it with this function.

    /// Don't parse it conditionally - that would skip some validation.

            #[cfg(feature = "retain-unknown")]

        }

}

impl<T: PartialOrd> PartialOrd for Unknown<T> {

        use Unknown::*;

            #[cfg(feature = "retain-unknown")]

            #[cfg(feature = "retain-unknown")]

        }

}

// ============================================================

/// A sequence of `T` items, with their order retained

///

/// Normally when a `Vec<T>` appears in a network document,

/// we expect the items to be sortable - they must impl [`EncodeOrd`](encode::EncodeOrd).

/// When encoding, the output is always sorted.

///

/// *This* type retains the ordering.

///

/// Implements the [`encode`] and [`parse2`] item multiplicity traits.

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

#[educe(Default)]

#[derive_deftly(Transparent)]

#[allow(clippy::exhaustive_structs)]

pub struct RetainedOrderVec<T>(pub Vec<T>);

// ============================================================

/// Types for decoding times and dates

mod timeimpl {

    use super::*;

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

    use std::time::SystemTime;

    use time::{

        OffsetDateTime, PrimitiveDateTime, format_description::FormatItem,

        macros::format_description,

    };

    /// A wall-clock time, encoded in Iso8601 format with an intervening

    /// space between the date and time.

    ///

    /// (Example: "2020-10-09 17:38:12")

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

    #[derive_deftly(Transparent)]

    #[allow(clippy::exhaustive_structs)]

    pub struct Iso8601TimeSp(pub SystemTime);

    /// Formatting object for parsing the space-separated Iso8601 format.

    const ISO_8601SP_FMT: &[FormatItem] =

        format_description!("[year]-[month]-[day] [hour]:[minute]:[second]");

    impl FromStr for Iso8601TimeSp {

        type Err = Error;

    }

    /// Formats a SystemTime according to the given format description

    ///

    /// Also converts any time::error::format to fmt::Error

    /// so that it can be unwrapped in the Display trait impl

    impl Display for Iso8601TimeSp {

    }

    /// A wall-clock time, encoded in ISO8601 format without an intervening

    /// space.

    ///

    /// This represents a specific UTC instant (ie an instant in global civil time).

    /// But it may not be able to represent leap seconds.

    ///

    /// The timezone is not included in the string representation; `+0000` is implicit.

    ///

    /// (Example: "2020-10-09T17:38:12")

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

    #[derive_deftly(Transparent)]

    #[allow(clippy::exhaustive_structs)]

    pub struct Iso8601TimeNoSp(pub SystemTime);

    /// Formatting object for parsing the space-separated Iso8601 format.

    const ISO_8601NOSP_FMT: &[FormatItem] =

        format_description!("[year]-[month]-[day]T[hour]:[minute]:[second]");

    impl FromStr for Iso8601TimeNoSp {

        type Err = Error;

    }

    impl Display for Iso8601TimeNoSp {

    }

    impl crate::NormalItemArgument for Iso8601TimeNoSp {}

}

/// Types for decoding RSA keys

mod rsa {

    use super::*;

    use crate::{NetdocErrorKind as EK, Pos, Result};

    use std::ops::RangeBounds;

    use tor_llcrypto::pk::rsa::PublicKey;

    use tor_llcrypto::{d::Sha1, pk::rsa::KeyPair};

    /// The fixed exponent which we require when parsing any RSA key in a netdoc

    //

    // TODO this value is duplicated a lot in the v1 parser

    pub(crate) const RSA_FIXED_EXPONENT: u32 = 65537;

    /// The fixed exponent which we require when parsing any RSA key in a netdoc

    //

    // TODO this value is duplicated a lot in the v1 parser

    pub(crate) const RSA_MIN_BITS: usize = 1024;

    /// RSA public key, partially processed by `crate::paarse`.

    ///

    /// As parsed from a base64-encoded object.

    /// They key's properties (exponent and size) haven't been checked.

    #[allow(non_camel_case_types)]

    #[derive(Clone, Debug)]

    pub(crate) struct RsaPublicParse1Helper(PublicKey, Pos);

    /// RSA signature using SHA-1 as per "Signing documents" in dir-spec

    ///

    /// <https://spec.torproject.org/dir-spec/netdoc.html#signing>

    ///

    /// Used for

    /// [`AuthCert::dir-key-certification`](crate::doc::authcert::AuthCert::dir-key-certification),

    /// for example.

    ///

    /// # Caveats

    ///

    /// This type MUST NOT be used for anomalous signatures

    /// such as

    /// [`AuthCert::dir_key_crosscert`](crate::doc::authcert::AuthCert::dir_key_crosscert);

    /// in that case because `dir_key_crosscert`'s

    /// set of allowed object labels includes `ID SIGNATURE` whereas this type

    /// is always `SIGNATURE`

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

    #[derive_deftly(ItemValueParseable, ItemValueEncodable)]

    #[deftly(netdoc(no_extra_args, signature(hash_accu = Sha1WholeKeywordLine)))]

    #[non_exhaustive]

    pub struct RsaSha1Signature {

        /// The bytes of the signature (base64-decoded).

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

        pub signature: Vec<u8>,

    }

    impl From<RsaPublicParse1Helper> for PublicKey {

    }

    impl super::FromBytes for RsaPublicParse1Helper {

    }

    impl RsaPublicParse1Helper {

        /// Give an error if the exponent of this key is not 'e'

            } else {

            }

        /// Give an error if the length of this key's modulus, in

        /// bits, is not contained in 'bounds'

            } else {

            }

        /// Give an error if the length of this key's modulus, in

        /// bits, is not exactly `n`.

    }

    impl RsaSha1Signature {

        /// Make a signature according to "Signing documents" in the netdoc spec

        ///

        /// <https://spec.torproject.org/dir-spec/netdoc.html#signing>

        ///

        /// `NetdocEncoder` should have had the body of the document

        /// (everything except the signatures) already encoded.

        ///

        /// `item_keyword` is the keyword for the signature item.

        /// This is needed because different documents use different keywords,

        /// and the keyword is covered by the signature (an annoying is a layering violation).

        /// See <https://gitlab.torproject.org/tpo/core/torspec/-/issues/322>.

        ///

        /// # Example

        ///

        /// ```

        /// use derive_deftly::Deftly;

        /// use tor_error::Bug;

        /// use tor_llcrypto::pk::rsa;

        /// use tor_netdoc::derive_deftly_template_NetdocEncodable;

        /// use tor_netdoc::encode::{NetdocEncodable, NetdocEncoder};

        /// use tor_netdoc::types::RsaSha1Signature;

        ///

        /// #[derive(Deftly, Default)]

        /// #[derive_deftly(NetdocEncodable)]

        /// pub struct Document {

        ///     pub document_intro_keyword: (),

        /// }

        /// #[derive(Deftly)]

        /// #[derive_deftly(NetdocEncodable)]

        /// pub struct DocumentSignatures {

        ///     pub document_signature: RsaSha1Signature,

        /// }

        /// impl Document {

        ///     pub fn encode_sign(&self, k: &rsa::KeyPair) -> Result<String, Bug> {

        ///         let mut encoder = NetdocEncoder::new();

        ///         self.encode_unsigned(&mut encoder)?;

        ///         let document_signature =

        ///             RsaSha1Signature::new_sign_netdoc(k, &encoder, "document-signature")?;

        ///         let sigs = DocumentSignatures { document_signature };

        ///         sigs.encode_unsigned(&mut encoder)?;

        ///         let encoded = encoder.finish()?;

        ///         Ok(encoded)

        ///     }

        /// }

        ///

        /// # fn main() -> Result<(), anyhow::Error> {

        /// let k = rsa::KeyPair::generate(&mut tor_basic_utils::test_rng::testing_rng())?;

        /// let doc = Document::default();

        /// let encoded = doc.encode_sign(&k)?;

        /// assert!(encoded.starts_with(concat!(

        ///     "document-intro-keyword\n",

        ///     "document-signature\n",

        ///     "-----BEGIN SIGNATURE-----\n",

        /// )));

        /// # Ok(())

        /// # }

        /// ```

    }

}

/// Types for decoding Ed25519 certificates

#[cfg(any(feature = "routerdesc", feature = "hs-common"))]

mod edcert {

    use crate::{NetdocErrorKind as EK, Pos, Result};

    use tor_cert::{CertType, Ed25519Cert, KeyUnknownCert};

    #[cfg(feature = "routerdesc")]

    use tor_llcrypto::pk::ed25519;

    /// An ed25519 certificate as parsed from a directory object, with

    /// signature not validated.

    #[derive(Debug, Clone)]

    pub(crate) struct UnvalidatedEdCert(KeyUnknownCert, Pos);

    impl super::FromBytes for UnvalidatedEdCert {

    }

    impl UnvalidatedEdCert {

        /// Give an error if this certificate's type is not `desired_type`.

        /// Give an error if this certificate's subject_key is not `pk`

        #[cfg(feature = "routerdesc")]

        /// Consume this object and return the inner Ed25519 certificate.

    }

}

/// Digest identifiers, and digests in the form `ALGORITHM=BASE64U`

///

/// As found in a vote's `m` line.

// TODO Use FixedB64 here.

mod identified_digest {

    use super::*;

    define_derive_deftly! {

        /// impl `FromStr` and `Display` for an enum with unit variants but also "unknown"

        ///

        /// Expected input: an enum whose variants are either

        ///  * unit variants, perhaps with `#[deftly(string_repr = "string")]`

        ///  * singleton tuple variant, containing `String` (or near equivalent)

        ///

        /// If `#[deftly(string_repro)]` is not specified,

        /// the default is snake case of the variant name.

        //

        // This macro may seem overkill, but open-coding these impls gives opportunities

        // for mismatches between FromStr, Display, and the variant name.

        //

        // TODO consider putting this in tor-basic-utils (maybe with a better name),

        // or possibly asking if derive_more want their FromStr to have this.

        StringReprUnitsOrUnknown for enum, expect items, beta_deftly:

        ${define STRING_REPR {

            ${vmeta(string_repr)

              as str,

              default { ${concat ${snake_case $vname}} }

            }

        }}

        impl FromStr for $ttype {

            type Err = Void;

                $(

                    ${when v_is_unit}

                    if s == $STRING_REPR {

                        return Ok($vtype)

                    }

                )

                $(

                    ${when not(v_is_unit)} // anything else had better be Unknown

                    // not using `return ..;` makes this a syntax error if there are several.

                    Ok($vtype { 0: s.into() })

                )

            }

        }

        impl Display for $ttype {

                let s: &str = match self {

                    $(

                        ${when v_is_unit}

                        $vtype => $STRING_REPR,

                    )

                    $(

                        ${when not(v_is_unit)}

                        $vpat => f_0,

                    )

                };

                Display::fmt(s, f)

            }

        }

    }

    /// The name of a digest algorithm.

    ///

    /// Can represent an unrecognised algorithm, so it's parsed and reproduced.

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

    #[derive_deftly(StringReprUnitsOrUnknown)]

    #[non_exhaustive]

    pub enum DigestName {

        /// SHA-256

        Sha256,

        /// Unknown

        Unknown(String),

    }

    /// A single digest made with a nominated digest algorithm, `ALGORITHM=DIGEST`

    #[derive(Debug, Clone, Eq, PartialEq, Hash, derive_more::Display)]

    #[display("{alg}={value}")]

    #[non_exhaustive]

    pub struct IdentifiedDigest {

        /// The algorithm name.

        alg: DigestName,

        /// The digest value.

        ///

        /// Invariant: length is correct for `alg`, assuming `alg` is known.

        value: B64,

    }

    impl NormalItemArgument for DigestName {}

    impl NormalItemArgument for IdentifiedDigest {}

    /// Invalid syntax parsing an `IdentifiedDigest`

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

    #[error("invalid syntax, expected ALGORITHM=DIGEST: {0}")]

    pub struct IdentifiedDigestParseError(String);

    impl FromStr for IdentifiedDigest {

        type Err = IdentifiedDigestParseError;

                    Some({

                        use DigestName::*;

                        }

                    })

                })() {

            })()

    }