Skip to main content

tor_netdoc/types/
misc.rs

1//! Types used to parse arguments of entries in a directory document.
2//!
3//! There are some types that are pretty common, like "ISOTime",
4//! "base64-encoded data", and so on.
5
6pub use b16impl::*;
7pub use b64impl::*;
8pub use contact_info::*;
9pub use curve25519impl::*;
10pub use ed25519impl::*;
11pub use edcert::*;
12pub use fingerprint::*;
13pub use hostname::*;
14pub use rsa::*;
15pub use timeimpl::*;
16
17pub use nickname::{InvalidNickname, Nickname};
18
19pub use boolean::NumericBoolean;
20
21pub use fingerprint::{Base64Fingerprint, Fingerprint};
22
23pub use identified_digest::{DigestName, IdentifiedDigest};
24
25pub use ignored_impl::{
26    Ignored, IgnoredItemOrObjectValue, ItemPresent, NoMoreArguments, NotPresent,
27    NotPresentEachValue,
28};
29
30use crate::NormalItemArgument;
31use crate::encode::{
32    self,
33    ItemArgument,
34    ItemEncoder,
35    ItemObjectEncodable,
36    ItemValueEncodable,
37    // `E` for "encode`; different from `parse2::MultiplicitySelector`
38    MultiplicitySelector as EMultiplicitySelector,
39    NetdocEncoder,
40};
41use crate::parse2::{
42    self, ArgumentError, ArgumentStream, ItemArgumentParseable, ItemObjectParseable,
43    ItemValueParseable, SignatureHashInputs, UnparsedItem,
44    multiplicity::{
45        ArgumentSetMethods,
46        ItemSetMethods,
47        // `P2` for "parse2`; different from `encode::MultiplicitySelector`
48        MultiplicitySelector as P2MultiplicitySelector,
49        ObjectSetMethods,
50    },
51    sig_hashes::Sha1WholeKeywordLine,
52};
53
54use derive_deftly::{Deftly, define_derive_deftly, define_derive_deftly_module};
55use digest::Digest as _;
56use educe::Educe;
57use std::cmp::{self, Ordering, PartialOrd};
58use std::fmt::{self, Display};
59use std::iter;
60use std::marker::PhantomData;
61use std::ops::{Deref, DerefMut};
62use std::result::Result as StdResult;
63use std::str::FromStr;
64use subtle::{Choice, ConstantTimeEq};
65use tor_error::{Bug, ErrorReport as _, internal, into_internal};
66use void::{ResultVoidExt as _, Void};
67
68/// Describes a value that van be decoded from a bunch of bytes.
69///
70/// Used for decoding the objects between BEGIN and END tags.
71pub(crate) trait FromBytes: Sized {
72    /// Try to parse a value of this type from a byte slice
73    fn from_bytes(b: &[u8], p: crate::Pos) -> crate::Result<Self>;
74    /// Try to parse a value of this type from a vector of bytes,
75    /// and consume that value
76    fn from_vec(v: Vec<u8>, p: crate::Pos) -> crate::Result<Self> {
77        Self::from_bytes(&v[..], p)
78    }
79}
80
81define_derive_deftly_module! {
82    /// Implement conversion traits for a transparent newtype around bytes - shared code
83    ///
84    /// This is precisely `#[derive_deftly(Transparent)]`, but in the form of a deftly module,
85    /// so that other derives (eg `BytesTransparent`) can re-use it.
86    Transparent beta_deftly:
87
88    // Expands to bullet points for "generated code", except omitting
89    // `AsRef` & `AsMut` because some uses sites have additional impls of those,
90    // which are best presented together in the docs.
91  ${define TRANSPARENT_DOCS_IMPLS {
92    ///  * impls of `Deref`, `DerefMut`
93    ///  * impls of `From<field>` and "`Into`" (technically, `From<Self> for field`)
94  }}
95
96    // Expands to the implementations
97  ${define TRANSPARENT_IMPLS {
98
99  ${for fields {
100    ${loop_exactly_1 "must be applied to a single-field struct"}
101
102    ${impl From<$ftype>} {
103        fn from($fpatname: $ftype) -> $ttype {
104            $vpat
105        }
106    }
107
108    // TODO: This implementation is probably a bug, as it forbids to derive
109    // Transparent on types like `struct Foo<T>(T)`, namely `T` not being
110    // covered by something else, like `PhantomData<T>` or `Vec<T>`.
111    ${impl From<$ttype> for $ftype} {
112        fn from(self_: $ttype) -> $ftype {
113            self_.$fname
114        }
115    }
116
117    ${impl Deref} {
118        type Target = $ftype;
119        fn deref(&self) -> &$ftype {
120            &self.$fname
121        }
122    }
123
124    ${impl DerefMut} {
125        fn deref_mut(&mut self) -> &mut $ftype {
126            &mut self.$fname
127        }
128    }
129
130    ${impl AsRef<$ftype>} {
131        fn as_ref(&self) -> &$ftype {
132            &self.$fname
133        }
134    }
135
136    ${impl AsMut<$ftype>} {
137        fn as_mut(&mut self) -> &mut $ftype {
138            &mut self.$fname
139        }
140    }
141  }}
142  }}
143}
144
145define_derive_deftly! {
146    use Transparent;
147
148    /// Implement conversion traits for an arbitrary transparent newtype
149    ///
150    /// # Requirements
151    ///
152    ///  * Self should be a single-field struct
153    ///  * Self should have no runtime invariants
154    ///
155    /// # Generated code
156    ///
157    $TRANSPARENT_DOCS_IMPLS
158    ///  * impls of `AsMut<field>`, `AsRef<field>`
159    ///
160    /// # Guidelines
161    ///
162    ///  * the field should be `pub`, with `#[allow(clippy::exhaustive_structs)]`
163    ///  * derive `Hash`, `Debug` and (usually) `Clone`
164    ///  * consider deriving `PartialEq` and `Eq`
165    ///    but for types containing bytes, use [`ConstantTimeEq`],
166    ///    eg with [`#[derive_deftly(BytesTransparent)]`](derive_deftly_template_BytesTransparent)
167    ///    (instead of `Transparent`).
168    ///  * implement `FromStr`, `Display`, `NormalItemArgument`, as required
169    Transparent for struct, beta_deftly:
170
171    $TRANSPARENT_IMPLS
172}
173
174define_derive_deftly! {
175    use Transparent;
176
177    /// Implement `ConstantTimeEq`, `.as_bytes()`, etc., for a transparent newtype around bytes
178    ///
179    /// # Requirements
180    ///
181    ///  * Self should be a single-field struct
182    ///  * Self should deref to `&[u8]` (and to `&mut [u8]`).
183    ///  * (so Self should have no runtime invariants)
184    ///
185    /// # Generated code
186    ///
187    ///  * impls of `ConstantTimeEq`, `Eq`, `PartialEq`, `Ord`, `PartialOrd`
188    ///  * `as_bytes()` method
189    ${TRANSPARENT_DOCS_IMPLS}
190    ///  * impls of `AsMut<field>`, `AsRef<field>`, `AsRef<[u8]>`, `AsMut<[u8]>`
191    ///
192    // We could derive Debug here but then we have to deal with the Fixed's N
193    // which gets quite fiddly.
194    //
195    /// # Guidelines
196    ///
197    ///  * derive `Hash` and write `#[allow(clippy::derived_hash_with_manual_eq)]`
198    ///  * impl `FromStr` and `Display` (if required, which they usually will be)
199    ///  * derive `derive_more::Debug` eg with `#[debug(r#"B64("{self}")"#)]`
200    ///  * `impl NormalItemArgument` if appropriate (ie the representation has no spaces)
201    BytesTransparent for struct, beta_deftly:
202
203    $TRANSPARENT_IMPLS
204
205    ${impl ConstantTimeEq} {
206        fn ct_eq(&self, other: &$ttype) -> Choice {
207          $(
208            self.$fname.ct_eq(&other.$fname)
209          )
210        }
211    }
212    $/// `$tname` is `Eq` via its constant-time implementation.
213    ${impl PartialEq} {
214        fn eq(&self, other: &$ttype) -> bool {
215            self.ct_eq(other).into()
216        }
217    }
218    ${impl Eq} {}
219    ${impl PartialOrd} {
220        fn partial_cmp(&self, other: &Self) -> Option<Ordering> {
221            Some(self.cmp(other))
222        }
223    }
224    ${impl Ord} {
225        fn cmp(&self, other: &Self) -> Ordering {
226          $(
227            self.$fname.cmp(&other.$fname)
228          )
229        }
230    }
231
232    $impl {
233        /// Return the byte array from this object.
234        pub fn as_bytes(&self) -> &[u8] {
235          $(
236            &self.$fname[..]
237          )
238        }
239    }
240
241    ${impl AsRef<[u8]>} {
242        fn as_ref(&self) -> &[u8] {
243          $(
244            self.$fname.as_ref()
245          )
246        }
247    }
248
249    ${impl AsMut<[u8]>} {
250        fn as_mut(&mut self) -> &mut [u8] {
251          $(
252            self.$fname.as_mut()
253          )
254        }
255    }
256}
257
258define_derive_deftly! {
259    /// Implement useful methods for a fixed-size byte array wrapper
260    ///
261    /// Typically used in conjunction with deriving `BytesTransparent`.
262    ///
263    /// # Requirements
264    ///
265    ///  * Self must be a single-field struct wrapping a byte array
266    ///
267    /// # Generated code
268    ///
269    ///  * `Self::from_byte_slice`
270    FixedBytes beta_deftly:
271
272    $impl {
273        $/// Construct a `$$ttype` from a byte slice
274        $///
275        $/// Copies the contents.  Returns `None` if the length is wrong.
276        //
277        // Provided because the alternative involving constructors, try_into(),
278        // etc., is very clumsy.
279        pub fn from_byte_slice(slice: &[u8]) -> Option<Self> {
280            let array: &[u8; _] = slice.try_into().ok()?;
281
282            Some(Self { $(
283                ${loop_exactly_1 "must be applied to a single-field struct"}
284                $fname: *array,
285            ) })
286        }
287    }
288}
289
290/// Types for decoding base64-encoded values.
291mod b64impl {
292    use super::*;
293    use crate::{Error, NetdocErrorKind as EK, Pos, Result};
294    use base64ct::{Base64, Base64Unpadded, Encoding};
295    use std::ops::RangeBounds;
296
297    /// A byte array, encoded in base64 with optional padding.
298    ///
299    /// On output (`Display`), output is unpadded.
300    #[derive(Clone, Hash, Deftly)]
301    #[derive_deftly(BytesTransparent)]
302    #[allow(clippy::derived_hash_with_manual_eq)]
303    #[derive(derive_more::Debug)]
304    #[debug(r#"B64("{self}")"#)]
305    #[allow(clippy::exhaustive_structs)]
306    pub struct B64(pub Vec<u8>);
307
308    impl FromStr for B64 {
309        type Err = Error;
310        fn from_str(s: &str) -> Result<Self> {
311            let v: core::result::Result<Vec<u8>, base64ct::Error> = match s.len() % 4 {
312                0 => Base64::decode_vec(s),
313                _ => Base64Unpadded::decode_vec(s),
314            };
315            let v = v.map_err(|_| {
316                EK::BadArgument
317                    .with_msg("Invalid base64")
318                    .at_pos(Pos::at(s))
319            })?;
320            Ok(B64(v))
321        }
322    }
323
324    impl Display for B64 {
325        fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
326            Display::fmt(&Base64Unpadded::encode_string(&self.0), f)
327        }
328    }
329
330    impl B64 {
331        /// Return this object if its length is within the provided bounds
332        /// object, or an error otherwise.
333        pub(crate) fn check_len<B: RangeBounds<usize>>(self, bounds: B) -> Result<Self> {
334            if bounds.contains(&self.0.len()) {
335                Ok(self)
336            } else {
337                Err(EK::BadObjectVal.with_msg("Invalid length on base64 data"))
338            }
339        }
340
341        /// Try to convert this object into an array of N bytes.
342        ///
343        /// Return an error if the length is wrong.
344        pub(crate) fn into_array<const N: usize>(self) -> Result<[u8; N]> {
345            self.0
346                .try_into()
347                .map_err(|_| EK::BadObjectVal.with_msg("Invalid length on base64 data"))
348        }
349    }
350
351    impl FromIterator<u8> for B64 {
352        fn from_iter<T: IntoIterator<Item = u8>>(iter: T) -> Self {
353            Self(iter.into_iter().collect())
354        }
355    }
356
357    impl NormalItemArgument for B64 {}
358
359    /// A byte array encoded in base64 with a fixed length.
360    ///
361    /// As with [`B64`], padding is optional when parsing, but omitted when encoding.
362    #[derive(Clone, Hash, Deftly)]
363    #[derive_deftly(BytesTransparent, FixedBytes)]
364    #[allow(clippy::derived_hash_with_manual_eq)]
365    #[derive(derive_more::Debug)]
366    #[debug(r#"FixedB64::<{N}>("{self}")"#)]
367    #[allow(clippy::exhaustive_structs)]
368    pub struct FixedB64<const N: usize>(pub [u8; N]);
369
370    impl<const N: usize> Display for FixedB64<N> {
371        fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
372            Display::fmt(&B64(self.0.to_vec()), f)
373        }
374    }
375
376    impl<const N: usize> FromStr for FixedB64<N> {
377        type Err = Error;
378        fn from_str(s: &str) -> Result<Self> {
379            Ok(Self(B64::from_str(s)?.0.try_into().map_err(|_| {
380                EK::BadArgument
381                    .at_pos(Pos::at(s))
382                    .with_msg("invalid length")
383            })?))
384        }
385    }
386
387    impl<const N: usize> NormalItemArgument for FixedB64<N> {}
388}
389
390// ============================================================
391
392/// Types for decoding hex-encoded values.
393mod b16impl {
394    use super::*;
395    use crate::{Error, NetdocErrorKind as EK, Pos, Result};
396
397    /// A byte array encoded in hexadecimal; prints in lowercase
398    ///
399    /// Both uppercase and lowercase are tolerated when parsing.
400    #[derive(Clone, Hash, Deftly)]
401    #[derive_deftly(BytesTransparent)]
402    #[allow(clippy::derived_hash_with_manual_eq)]
403    #[derive(derive_more::Debug)]
404    #[debug(r#"B16("{self}")"#)]
405    #[allow(clippy::exhaustive_structs)]
406    pub struct B16(pub Vec<u8>);
407
408    /// A byte array encoded in hexadecimal; prints in uppercase
409    ///
410    /// Both uppercase and lowercase are tolerated when parsing.
411    #[derive(Clone, Hash, Deftly)]
412    #[derive_deftly(BytesTransparent)]
413    #[allow(clippy::derived_hash_with_manual_eq)]
414    #[derive(derive_more::Debug)]
415    #[debug(r#"B16U("{self}")"#)]
416    #[allow(clippy::exhaustive_structs)]
417    pub struct B16U(pub Vec<u8>);
418
419    /// A fixed-length version of [`B16U`].
420    #[derive(Clone, Hash, Deftly)]
421    #[derive_deftly(BytesTransparent, FixedBytes)]
422    #[allow(clippy::derived_hash_with_manual_eq)]
423    #[derive(derive_more::Debug)]
424    #[debug(r#"FixedB16U("{self}")"#)]
425    #[allow(clippy::exhaustive_structs)]
426    pub struct FixedB16U<const N: usize>(pub [u8; N]);
427
428    impl FromStr for B16 {
429        type Err = Error;
430        fn from_str(s: &str) -> Result<Self> {
431            let bytes = hex::decode(s).map_err(|_| {
432                EK::BadArgument
433                    .at_pos(Pos::at(s))
434                    .with_msg("invalid hexadecimal")
435            })?;
436            Ok(B16(bytes))
437        }
438    }
439
440    impl FromStr for B16U {
441        type Err = Error;
442        fn from_str(s: &str) -> Result<Self> {
443            Ok(B16U(B16::from_str(s)?.0))
444        }
445    }
446
447    impl<const N: usize> FromStr for FixedB16U<N> {
448        type Err = Error;
449        fn from_str(s: &str) -> Result<Self> {
450            Ok(Self(B16U::from_str(s)?.0.try_into().map_err(|_| {
451                EK::BadArgument
452                    .at_pos(Pos::at(s))
453                    .with_msg("invalid length")
454            })?))
455        }
456    }
457
458    /// Write `b` to `f` in hex uppercase
459    // `hex` has `hex::encode_upper` but that allocates a `String`
460    fn write_b16u(b: &[u8], f: &mut fmt::Formatter) -> fmt::Result {
461        for c in b {
462            write!(f, "{c:02X}")?;
463        }
464        Ok(())
465    }
466
467    impl Display for B16 {
468        fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
469            // `hex` has `hex::encode` but that allocates a `String`, which this approach doesn't
470            for c in self.as_bytes() {
471                write!(f, "{c:02x}")?;
472            }
473            Ok(())
474        }
475    }
476
477    impl Display for B16U {
478        fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
479            write_b16u(self.as_bytes(), f)
480        }
481    }
482
483    impl<const N: usize> Display for FixedB16U<N> {
484        fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
485            write_b16u(self.as_bytes(), f)
486        }
487    }
488
489    impl NormalItemArgument for B16 {}
490    impl NormalItemArgument for B16U {}
491    impl<const N: usize> NormalItemArgument for FixedB16U<N> {}
492}
493
494// ============================================================
495
496/// Types for decoding curve25519 keys
497mod curve25519impl {
498    use super::*;
499
500    use crate::{Error, NormalItemArgument, Result, types::misc::FixedB64};
501    use tor_llcrypto::pk::curve25519::PublicKey;
502
503    /// A Curve25519 public key, encoded in base64 with optional padding
504    #[derive(Debug, Clone, PartialEq, Eq, Hash, Deftly)]
505    // Sadly not Ord because x25519_dalek::PublicKey isn't
506    #[derive_deftly(Transparent)]
507    #[allow(clippy::exhaustive_structs)]
508    pub struct Curve25519Public(pub PublicKey);
509
510    impl FromStr for Curve25519Public {
511        type Err = Error;
512        fn from_str(s: &str) -> Result<Self> {
513            let pk: FixedB64<32> = s.parse()?;
514            let pk: [u8; 32] = pk.into();
515            Ok(Curve25519Public(pk.into()))
516        }
517    }
518
519    impl Display for Curve25519Public {
520        fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
521            FixedB64::from(self.0.to_bytes()).fmt(f)
522        }
523    }
524
525    impl NormalItemArgument for Curve25519Public {}
526}
527
528// ============================================================
529
530/// Types for decoding ed25519 keys
531mod ed25519impl {
532    use super::*;
533
534    use crate::{Error, NormalItemArgument, Result, types::misc::FixedB64};
535    use derive_deftly::Deftly;
536    use tor_llcrypto::pk::ed25519::{Ed25519Identity, Signature};
537
538    /// An alleged ed25519 public key, encoded in base64 with optional
539    /// padding.
540    #[derive(Debug, Copy, Clone, PartialEq, Eq, Ord, PartialOrd, Hash, Deftly)]
541    #[derive_deftly(Transparent)]
542    #[allow(clippy::exhaustive_structs)]
543    pub struct Ed25519Public(pub Ed25519Identity);
544
545    impl FromStr for Ed25519Public {
546        type Err = Error;
547        fn from_str(s: &str) -> Result<Self> {
548            let pk: FixedB64<32> = s.parse()?;
549            Ok(Ed25519Public(Ed25519Identity::new(pk.into())))
550        }
551    }
552
553    impl Display for Ed25519Public {
554        fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
555            let pk: [u8; 32] = self.0.into();
556            let pk = FixedB64::from(pk);
557            pk.fmt(f)
558        }
559    }
560
561    impl NormalItemArgument for Ed25519Public {}
562
563    /// Helper that checks for the presence of `ed25519`.
564    #[derive(Debug, Clone, PartialEq, Eq, Ord, PartialOrd, Hash)] //
565    #[derive(derive_more::Display, derive_more::FromStr)]
566    #[display(rename_all = "lowercase")]
567    #[from_str(rename_all = "lowercase")]
568    #[allow(clippy::exhaustive_enums)]
569    pub enum Ed25519AlgorithmString {
570        /// Ed25519 encoded as `ed25519`.
571        Ed25519,
572    }
573
574    impl NormalItemArgument for Ed25519AlgorithmString {}
575
576    /// Ed25519 public key in the form `<keyword> id <base64>`
577    ///
578    ///  * `id` in microdescriptors:
579    ///    <https://spec.torproject.org/dir-spec/computing-microdescriptors.html>
580    ///
581    ///  * `identity-ed25519` in routerdescs:
582    ///    <https://spec.torproject.org/dir-spec/server-descriptor-format.html#item:identity-ed25519>
583    ///
584    ///  * `id` in votes' routerstatus entries:
585    ///    <https://spec.torproject.org/dir-spec/consensus-formats.html#item:id>
586    #[derive(Debug, Clone, PartialEq, Eq, Ord, PartialOrd, Hash, Deftly)]
587    #[derive_deftly(ItemValueEncodable, ItemValueParseable)]
588    #[non_exhaustive]
589    pub struct Ed25519IdentityLine {
590        /// Fixed magic identifier (`ed25519`) for this line.
591        pub alg: Ed25519AlgorithmString,
592
593        /// The actual Ed25519 identity.
594        pub pk: Ed25519Public,
595    }
596
597    impl From<Ed25519Public> for Ed25519IdentityLine {
598        fn from(pk: Ed25519Public) -> Self {
599            Self {
600                alg: Ed25519AlgorithmString::Ed25519,
601                pk,
602            }
603        }
604    }
605
606    impl From<Ed25519Identity> for Ed25519IdentityLine {
607        fn from(pk: Ed25519Identity) -> Self {
608            Ed25519Public(pk).into()
609        }
610    }
611
612    impl ItemArgument for Signature {
613        fn write_arg_onto(&self, out: &mut ItemEncoder) -> StdResult<(), Bug> {
614            FixedB64::from(self.to_bytes()).write_arg_onto(out)
615        }
616    }
617}
618
619// ============================================================
620
621/// Dummy types like [`Ignored`]
622mod ignored_impl {
623    use super::*;
624
625    use crate::parse2::ErrorProblem as EP;
626    use ArgumentError as AE;
627
628    /// Part of a network document, that isn't actually there.
629    ///
630    /// Used as a standin in `ns_type!` calls in various netstatus `each_variety.rs`.
631    /// The effect is as if the field were omitted from the containing type.
632    ///
633    ///  * When used as item(s) (ie, a field type when deriving `NetdocParseable\[Fields\]`):
634    ///    **ignores any number** of items with that field's keyword during parsing,
635    ///    and emits none during encoding.
636    ///
637    ///    (To *reject* documents containing this item, use `Option<Void>`,
638    ///    but note that the spec says unknown items should be ignored,
639    ///    which would normally include items which are merely missing from one variety.)
640    ///
641    ///  * When used as an argument (ie, a field type when deriving `ItemValueParseable`,
642    ///    or with `netdoc(single_arg)`  when deriving `NetdocParseable\[Fields\]`):
643    ///    consumes **no arguments** during parsing, and emits none during encoding.
644    ///
645    ///  * When used as an object field (ie, `netdoc(object)` when deriving `ItemValueParseable`):
646    ///    **rejects** an object - failing the parse if one is present.
647    ///    (Functions similarly to `Option<Void>`, but prefer `NotPresent` as it's clearer.)
648    ///
649    ///  * When used as a sub-document (ie, `netdoc(flatten)` when deriving a document trait),
650    ///    it recognises, and encodes as, no fields.
651    ///
652    /// There are bespoke impls of the multiplicity traits
653    /// `ItemSetMethods` and `ObjectSetMethods`:
654    /// don't wrap this type in `Option` or `Vec`.
655    //
656    // TODO we'll need to implement ItemArgument etc., for encoding, too.
657    #[derive(Debug, Copy, Clone, Eq, PartialEq, Hash, Ord, PartialOrd, Default)]
658    #[allow(clippy::exhaustive_structs)]
659    #[derive(Deftly)]
660    #[derive_deftly(NetdocEncodableFields, NetdocParseableFields)]
661    pub struct NotPresent;
662
663    /// An individual value that is not present - placeholder type
664    ///
665    /// This is the "single" item type for encoding multiplicity
666    /// (for Items, Arguments or Objects), for [`NotPresent`].
667    ///
668    /// It should not be used directly.
669    ///
670    /// During parsing, each "not present" item is ignored,
671    /// but the multiplicity arrangements involve parsing each value
672    /// and then passing the item value to [`ItemSetMethods::accumulate`]
673    /// where (for [`NotPresentEachValue`]) it is discarded.
674    /// Therefore this type must be inhabited; the item parser discards the unparsed item.
675    ///
676    /// During parsing of arguments, parsing is driven by
677    /// [our `ArgumentSetMethods::parse_with`][`P2MultiplicitySelector::<NotPresent>::parse_with)
678    /// which doesn't need to call any parser.
679    /// So the [`ItemArgumentParseable`] implementation always throws an error.
680    ///
681    /// During parsing of objects, rejection is done by
682    /// [`NotPresentEachValue::check_label`] (and `from_bytes`).
683    ///
684    /// For encoding, there is only one multiplicity system which
685    /// will never call any encoding function, so the encoding functions all throw `Bug`.
686    ///
687    /// This type has a similar role to `IgnoredItemOrObjectValue`,
688    /// but `NotPresentEachValue` is different in detail,
689    /// and (unlike `Ignored`) must support arguments, not just items and objects.
690    #[derive(Debug, Clone, Deftly)]
691    #[non_exhaustive]
692    #[derive_deftly(ItemValueParseable, NetdocParseableFields)]
693    pub struct NotPresentEachValue;
694
695    /// Ignored part of a network document.
696    ///
697    /// With `parse2`, can be used as an item, object, or even flattened-fields.
698    ///
699    /// When deriving `parse2` traits, and a field is absent in a particular netstatus variety,
700    /// use `ns_type!` with [`NotPresent`], rather than `Ignored`.
701    ///
702    /// During encoding as an Items or Objects, will be entirely omitted,
703    /// via the multiplicity arrangements.
704    ///
705    /// Cannot be encoded as an Argument: if this is not the last
706    /// Argument, we need something to put into the output document to avoid generating
707    /// a document with the arguments out of step.  If it *is* the last argument,
708    /// it could simply be omitted, since additional arguments are in any case ignored.
709    #[derive(Debug, Copy, Clone, Eq, PartialEq, Hash, Ord, PartialOrd, Default, Deftly)]
710    #[derive_deftly(ItemValueParseable, NetdocParseableFields)]
711    #[allow(clippy::exhaustive_structs)]
712    pub struct Ignored;
713
714    /// An Item or Object that would be ignored during parsing and is omitted during encoding
715    ///
716    /// This is the "single" item type for encoding multiplicity for Items or Objects,
717    /// for [`Ignored`].
718    ///
719    /// It should not be used directly.
720    ///
721    /// This type is uninhabited.
722    pub struct IgnoredItemOrObjectValue(Void);
723
724    /// Indicates that no further arguments are allowed in a network document Item line
725    ///
726    /// Unlike [`NotPresent`], this fails during parsing if there are any more arguments.
727    ///
728    /// Should appear only at the end of the argument list.
729    #[derive(Debug, Copy, Clone, Eq, PartialEq, Hash, Ord, PartialOrd, Default)]
730    #[allow(clippy::exhaustive_structs)]
731    pub struct NoMoreArguments;
732
733    /// An item that only matters in terms of presence of absence.
734    ///
735    /// Useful for items such as `tunnelled-dir-server` where the mere presence
736    /// implies a truthful value.
737    ///
738    /// This wrapper implements [`ItemValueParseable`] and [`ItemValueEncodable`]
739    /// rejecting all arguments and objects and just expecting/emitting the
740    /// keyword (or not).
741    ///
742    /// # Examples
743    ///
744    /// The following shows an except from a hypothetical netdoc with a
745    /// [`ItemPresent`] item.
746    ///
747    /// ```
748    /// use derive_deftly::Deftly;
749    /// use tor_netdoc::types::*;
750    /// use tor_netdoc::parse2::*;
751    /// use tor_netdoc::*;
752    ///
753    /// #[derive(Debug, Default)]
754    /// struct Hello;
755    ///
756    /// #[derive(Deftly, Debug)]
757    /// #[derive_deftly(NetdocParseable)]
758    /// struct TestDoc {
759    ///     intro: Ignored,
760    ///     hello: Option<ItemPresent<Hello>>,
761    /// }
762    ///
763    /// // hello is not present.
764    /// let doc = parse_netdoc::<TestDoc>(&ParseInput::new("intro\n", "")).unwrap();
765    /// assert!(doc.hello.is_none());
766    ///
767    /// // hello is present.
768    /// let doc = parse_netdoc::<TestDoc>(&ParseInput::new("intro\nhello\n", "")).unwrap();
769    /// assert!(doc.hello.is_some());
770    ///
771    /// // hello has arguments which are ignored.
772    /// let doc = parse_netdoc::<TestDoc>(&ParseInput::new("intro\nhello world\n", "")).unwrap();
773    /// assert!(doc.hello.is_some());
774    ///
775    /// // hello is present twice which is not allowed.
776    /// let doc = parse_netdoc::<TestDoc>(&ParseInput::new("intro\nhello\nhello\n", "")).unwrap_err();
777    /// ```
778    //
779    // We cannot derive Transparent here, because it is not possible to
780    // implement `From<ItemPresent<T>> for T` due to orphan rule.
781    //
782    // Otherwise, a downstream crate could for example implement
783    // `From<ItemPresent<U>> for U` with `U` being a locally defined type,
784    // leading to a conflicting implementation.  A solution would be to cover
785    // `T` behind another generic type such as `PhantomData`, as this can't be
786    // a type in a downstream crate, but that level of indirection feels wrong.
787    #[derive(Debug, Copy, Clone, Default, Ord, PartialOrd, Eq, PartialEq, Hash)]
788    //
789    #[derive(
790        derive_more::From,
791        derive_more::Deref,
792        derive_more::DerefMut,
793        derive_more::AsRef,
794        derive_more::AsMut,
795    )]
796    #[allow(clippy::exhaustive_structs)]
797    pub struct ItemPresent<T: Default>(pub T);
798
799    impl ItemSetMethods for P2MultiplicitySelector<NotPresent> {
800        type Each = NotPresentEachValue;
801        type Field = NotPresent;
802        fn can_accumulate(self, _acc: &Option<NotPresent>) -> Result<(), EP> {
803            Ok(())
804        }
805        fn accumulate(self, _: &mut Option<NotPresent>, _: NotPresentEachValue) -> Result<(), EP> {
806            Ok(())
807        }
808        fn finish(self, _acc: Option<NotPresent>, _: &'static str) -> Result<NotPresent, EP> {
809            Ok(NotPresent)
810        }
811        fn debug_core(self) -> &'static str {
812            "Ignored"
813        }
814    }
815
816    impl ItemValueEncodable for NotPresentEachValue {
817        fn write_item_value_onto(&self, _out: ItemEncoder) -> Result<(), Bug> {
818            Err(internal!("NotPresentEachValue as ItemValueEncodable"))
819        }
820    }
821
822    impl ArgumentSetMethods for P2MultiplicitySelector<NotPresent> {
823        type Each = NotPresentEachValue;
824        type Field = NotPresent;
825
826        fn parse_with<P>(self, _: &mut ArgumentStream<'_>, _: P) -> Result<Self::Field, AE>
827        where
828            P: for<'s> Fn(&mut ArgumentStream<'s>) -> Result<Self::Each, AE>,
829        {
830            Ok(NotPresent)
831        }
832
833        fn debug_core(self) -> &'static str {
834            "NotPresent"
835        }
836    }
837    impl ItemArgument for NotPresentEachValue {
838        fn write_arg_onto(&self, _out: &mut ItemEncoder) -> Result<(), Bug> {
839            Err(internal!("NotPresentEachValue as ItemArgument"))
840        }
841    }
842    impl ItemArgumentParseable for NotPresentEachValue {
843        fn from_args<'s>(_: &mut ArgumentStream<'s>) -> Result<Self, ArgumentError> {
844            // Not quite the right error, but we don't have an ArgumentError::Internal
845            Err(AE::Unexpected)
846        }
847    }
848
849    impl ItemObjectEncodable for NotPresentEachValue {
850        fn label(&self) -> &str {
851            "INTERNAL ERROR"
852        }
853        fn write_object_onto(&self, _b: &mut Vec<u8>) -> Result<(), Bug> {
854            Err(internal!("NotPresentEachValue as ItemObjectEncodable"))
855        }
856    }
857
858    impl ObjectSetMethods for P2MultiplicitySelector<NotPresent> {
859        type Field = NotPresent;
860        type Each = NotPresentEachValue;
861        fn resolve_option(self, _found: Option<NotPresentEachValue>) -> Result<NotPresent, EP> {
862            Ok(NotPresent)
863        }
864        fn debug_core(self) -> &'static str {
865            "NotPresent"
866        }
867    }
868    impl ItemObjectParseable for NotPresentEachValue {
869        fn check_label(_label: &str) -> Result<(), EP> {
870            Err(EP::ObjectUnexpected)
871        }
872        fn from_bytes(_input: &[u8]) -> Result<Self, EP> {
873            Err(EP::ObjectUnexpected)
874        }
875    }
876
877    impl<'f> encode::MultiplicityMethods<'f> for EMultiplicitySelector<NotPresent> {
878        type Field = NotPresent;
879        type Each = NotPresentEachValue;
880        fn iter_ordered(self, _: &'f Self::Field) -> impl Iterator<Item = &'f Self::Each> {
881            iter::empty()
882        }
883    }
884
885    impl encode::OptionalityMethods for EMultiplicitySelector<NotPresent> {
886        type Field = NotPresent;
887        type Each = NotPresentEachValue;
888        fn as_option<'f>(self, _: &'f Self::Field) -> Option<&'f Self::Each> {
889            None
890        }
891    }
892
893    impl FromStr for Ignored {
894        type Err = Void;
895        fn from_str(_s: &str) -> Result<Ignored, Void> {
896            Ok(Ignored)
897        }
898    }
899
900    impl ItemArgumentParseable for Ignored {
901        fn from_args(_: &mut ArgumentStream) -> Result<Ignored, ArgumentError> {
902            Ok(Ignored)
903        }
904    }
905
906    impl ItemObjectParseable for Ignored {
907        fn check_label(_label: &str) -> Result<(), EP> {
908            // allow any label
909            Ok(())
910        }
911        fn from_bytes(_input: &[u8]) -> Result<Self, EP> {
912            Ok(Ignored)
913        }
914    }
915
916    impl ObjectSetMethods for P2MultiplicitySelector<Ignored> {
917        type Field = Ignored;
918        type Each = Ignored;
919        fn resolve_option(self, _found: Option<Ignored>) -> Result<Ignored, EP> {
920            Ok(Ignored)
921        }
922        fn debug_core(self) -> &'static str {
923            "Ignored"
924        }
925    }
926
927    impl<'f> encode::MultiplicityMethods<'f> for EMultiplicitySelector<Ignored> {
928        type Field = Ignored;
929        type Each = IgnoredItemOrObjectValue;
930        fn iter_ordered(self, _: &'f Self::Field) -> impl Iterator<Item = &'f Self::Each> {
931            iter::empty()
932        }
933    }
934
935    impl encode::OptionalityMethods for EMultiplicitySelector<Ignored> {
936        type Field = Ignored;
937        type Each = IgnoredItemOrObjectValue;
938        fn as_option<'f>(self, _: &'f Self::Field) -> Option<&'f Self::Each> {
939            None
940        }
941    }
942
943    impl ItemValueEncodable for IgnoredItemOrObjectValue {
944        fn write_item_value_onto(&self, _: ItemEncoder) -> Result<(), Bug> {
945            void::unreachable(self.0)
946        }
947    }
948
949    impl ItemObjectEncodable for IgnoredItemOrObjectValue {
950        fn label(&self) -> &str {
951            void::unreachable(self.0)
952        }
953        fn write_object_onto(&self, _: &mut Vec<u8>) -> Result<(), Bug> {
954            void::unreachable(self.0)
955        }
956    }
957
958    impl ItemArgumentParseable for NoMoreArguments {
959        fn from_args(args: &mut ArgumentStream) -> Result<NoMoreArguments, ArgumentError> {
960            Ok(args.reject_extra_args()?)
961        }
962    }
963
964    impl ItemArgument for NoMoreArguments {
965        fn write_arg_onto(&self, _: &mut ItemEncoder) -> Result<(), Bug> {
966            Ok(())
967        }
968    }
969
970    impl<T: Default> ItemValueParseable for ItemPresent<T> {
971        fn from_unparsed(item: UnparsedItem<'_>) -> StdResult<Self, EP> {
972            item.check_no_object()?;
973            Ok(Self::default())
974        }
975    }
976
977    impl<T: Default> ItemValueEncodable for ItemPresent<T> {
978        fn write_item_value_onto(&self, out: ItemEncoder) -> StdResult<(), Bug> {
979            out.finish();
980            Ok(())
981        }
982    }
983}
984
985// ============================================================
986
987/// Information about unknown values, which may have been retained as a `T`
988///
989/// Won't grow additional variants - but, `Retained` is only included conditionally.
990///
991/// Also used in the form `Unknown<()>` to indicate whether unknown values *should* be retained.
992///
993/// ### Example
994///
995/// ```
996/// # {
997/// #![cfg(feature = "retain-unknown")]
998///
999/// use tor_netdoc::types::Unknown;
1000///
1001/// let mut unk: Unknown<Vec<String>> = Unknown::new_retained_default();
1002/// unk.with_mut_unknown(|u| u.push("something-we-found".into()));
1003/// assert_eq!(unk.into_retained().unwrap(), ["something-we-found"]);
1004/// # }
1005/// ```
1006///
1007/// ### Equality comparison, semantics
1008///
1009/// Two `Unknown` are consider equal if both have the same record of unknown values,
1010/// or if neither records unknown values at all.
1011///
1012/// `Unknown` is not `Eq` or `Ord` because we won't want to relate a `Discarded`
1013/// to a `Retained`.  That would be a logic error.  `partial_cmp` gives `None` for this.
1014#[derive(Debug, PartialEq, Clone, Copy, Hash)]
1015#[allow(clippy::exhaustive_enums)] // this isn't going to change
1016pub enum Unknown<T> {
1017    /// The parsing discarded unknown values and they are no longer available.
1018    Discarded(PhantomData<T>),
1019
1020    /// The document parsing retained (or should retain) unknown values.
1021    #[cfg(feature = "retain-unknown")]
1022    Retained(T),
1023}
1024
1025impl<T> Unknown<T> {
1026    /// Create an `Unknown` which specifies that values were discarded (or should be)
1027    pub fn new_discard() -> Self {
1028        Unknown::Discarded(PhantomData)
1029    }
1030
1031    /// Map the `Retained`, if there is one
1032    pub fn map<U>(self, f: impl FnOnce(T) -> U) -> Unknown<U> {
1033        self.try_map(move |t| Ok::<_, Void>(f(t))).void_unwrap()
1034    }
1035
1036    /// Map the `Retained`, fallibly
1037    pub fn try_map<U, E>(self, f: impl FnOnce(T) -> Result<U, E>) -> Result<Unknown<U>, E> {
1038        Ok(match self {
1039            Unknown::Discarded(_) => Unknown::Discarded(PhantomData),
1040            #[cfg(feature = "retain-unknown")]
1041            Unknown::Retained(t) => Unknown::Retained(f(t)?),
1042        })
1043    }
1044
1045    /// Obtain an `Unknown` containing (maybe) a reference
1046    pub fn as_ref(&self) -> Unknown<&T> {
1047        match self {
1048            Unknown::Discarded(_) => Unknown::Discarded(PhantomData),
1049            #[cfg(feature = "retain-unknown")]
1050            Unknown::Retained(t) => Unknown::Retained(t),
1051        }
1052    }
1053
1054    /// Return the retained unknown data, giving `None` if none was saved
1055    ///
1056    /// This is the function for disregarding the possible previously existence
1057    /// of now-discarded unknown (unrecognised) information.
1058    ///
1059    /// Use [`into_retained`](Self::into_retained) if it would be a bug
1060    /// if unrecognised information had been previously discarded.
1061    pub fn only_known(self) -> Option<T> {
1062        match self {
1063            Unknown::Discarded(_) => None,
1064            #[cfg(feature = "retain-unknown")]
1065            Unknown::Retained(t) => Some(t),
1066        }
1067    }
1068
1069    /// Obtain the `Retained` data
1070    ///
1071    /// Treats lack of retention as an internal error.
1072    pub fn into_retained(self) -> Result<T, Bug> {
1073        match self {
1074            Unknown::Discarded(_) => Err(internal!("Unknown::retained but data not collected")),
1075            #[cfg(feature = "retain-unknown")]
1076            Unknown::Retained(t) => Ok(t),
1077        }
1078    }
1079
1080    /// Start recording unknown information, with a default value for `T`
1081    #[cfg(feature = "retain-unknown")]
1082    pub fn new_retained_default() -> Self
1083    where
1084        T: Default,
1085    {
1086        Unknown::Retained(T::default())
1087    }
1088
1089    /// Update the `Retained`, if there is one
1090    ///
1091    /// Intended for use in parsing, when we encounter an unknown value.
1092    ///
1093    /// Not provided in `try_` form.  If you think you need this, instead, unconditionally
1094    /// parse and verify the unknown value, and then conditionally insert it with this function.
1095    /// Don't parse it conditionally - that would skip some validation.
1096    pub fn with_mut_unknown(&mut self, f: impl FnOnce(&mut T)) {
1097        match self {
1098            Unknown::Discarded(_) => {}
1099            #[cfg(feature = "retain-unknown")]
1100            Unknown::Retained(t) => f(t),
1101        }
1102    }
1103}
1104
1105impl<T: PartialOrd> PartialOrd for Unknown<T> {
1106    fn partial_cmp(&self, other: &Self) -> Option<cmp::Ordering> {
1107        use Unknown::*;
1108        match (self, other) {
1109            (Discarded(_), Discarded(_)) => Some(cmp::Ordering::Equal),
1110            #[cfg(feature = "retain-unknown")]
1111            (Discarded(_), Retained(_)) | (Retained(_), Discarded(_)) => None,
1112            #[cfg(feature = "retain-unknown")]
1113            (Retained(a), Retained(b)) => a.partial_cmp(b),
1114        }
1115    }
1116}
1117
1118// ============================================================
1119
1120/// A finite floating point number
1121///
1122/// Suitable for `stats` items in voites' routerstatus entries:
1123/// <https://spec.torproject.org/dir-spec/consensus-formats.html#item:stats>
1124///
1125/// Invariants:
1126///
1127///  * Is finite.  (So not NaN or Inf.)  Might be denormal.
1128///
1129/// String representation:
1130///
1131///  * Parses any valid C-like notation.
1132///
1133///  * Never uses exponential notation to display.
1134///
1135///  * Output can be rather large, up to 326 characters!
1136///    This is a spec bug.  The spec forbids us from using exponential notation.
1137///    <https://gitlab.torproject.org/tpo/core/torspec/-/work_items/416>
1138///
1139/// We may to change this in the future to use exponentials notation for output.
1140/// See <https://gitlab.torproject.org/tpo/core/torspec/-/work_items/416>
1141///
1142/// Comparison and ordering:
1143///
1144/// Implements `Eq` and `Ord` according to *mathematical* equality and ordering.
1145/// In particular, `-0.0` compares equal to `0.0`.
1146/// Therefore, does not implement `Hash`.
1147//
1148// TODO torspec#416 Consider replacing our F64Finite with finite f64 newtype from some crate
1149//
1150// What a palaver!
1151//
1152// This type is here rather than in rs.rs, in case similar things appears in other documents.
1153#[derive(Debug, Copy, Clone, PartialEq, PartialOrd)] //
1154#[derive(derive_more::Deref, derive_more::Into, derive_more::Display)]
1155pub struct F64Finite(f64);
1156
1157/// Error converting an [`F64Finite`] from an `f64`: the value wasn't finite
1158#[derive(Clone, Debug, Eq, PartialEq, thiserror::Error, amplify::Getters)]
1159#[error("FP value {} ({bits:#x}) is not finite", f64::from_bits(self.bits))]
1160pub struct F64FiniteError {
1161    /// The raw bits (as from [`f64::to_bits`])
1162    //
1163    // We store it this way rather than as `f64` so that `Eq` etc. make sense.
1164    bits: u64,
1165}
1166
1167impl TryFrom<f64> for F64Finite {
1168    type Error = F64FiniteError;
1169
1170    fn try_from(v: f64) -> Result<Self, F64FiniteError> {
1171        v.is_finite()
1172            .then_some(F64Finite(v))
1173            .ok_or_else(|| F64FiniteError { bits: v.to_bits() })
1174    }
1175}
1176
1177/// Error parsing [`F64Finite`] from a string
1178#[derive(Clone, Debug, Eq, PartialEq, thiserror::Error)]
1179#[non_exhaustive]
1180pub enum F64FiniteParseError {
1181    /// Syntax error
1182    #[error("syntax error")]
1183    Syntax(#[from] std::num::ParseFloatError),
1184
1185    /// Value is not finite
1186    #[error("bad value")]
1187    NotFinite(#[from] F64FiniteError),
1188}
1189
1190impl FromStr for F64Finite {
1191    type Err = F64FiniteParseError;
1192
1193    fn from_str(s: &str) -> StdResult<Self, F64FiniteParseError> {
1194        Ok(s.parse::<f64>()?.try_into()?)
1195    }
1196}
1197
1198impl Eq for F64Finite {}
1199
1200#[allow(clippy::derive_ord_xor_partial_ord)]
1201impl Ord for F64Finite {
1202    fn cmp(&self, other: &F64Finite) -> cmp::Ordering {
1203        self.0
1204            .partial_cmp(&other.0)
1205            .expect("finite f64 partial_cmp gave None")
1206    }
1207}
1208
1209impl NormalItemArgument for F64Finite {}
1210
1211// ============================================================
1212
1213/// Known keyword (enum) value, or arbitrary string
1214///
1215/// `T` should be a `Copy` enum with unit variants.
1216/// It should have appropriate `FromStr` and `Display`,
1217/// as well as [`NormalItemArgument`], impls.
1218///
1219/// Then `KeywordOrString` will implement the same traits.
1220///
1221/// Unlike [`Unknown`], unknown values are always retained as strings.
1222//
1223// `RelayFlags` has machinery for parsing flags and retaining unknown values,
1224// but it uses `Unknown` to maybe discard unknown flags,
1225// and it is generally quite a lot more complicated.
1226#[derive(Debug, PartialEq, Clone, Hash)]
1227#[allow(clippy::exhaustive_enums)] // this isn't going to change
1228pub enum KeywordOrString<T: Copy> {
1229    /// Known and recognised `T`
1230    Known(T),
1231
1232    /// Unknown value in arbitrary syntax
1233    Unknown(String),
1234}
1235
1236impl<T: Copy + NormalItemArgument> NormalItemArgument for KeywordOrString<T> {}
1237
1238impl<T: Copy + Display> Display for KeywordOrString<T> {
1239    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
1240        match self {
1241            KeywordOrString::Known(t) => Display::fmt(t, f),
1242            KeywordOrString::Unknown(s) => Display::fmt(s, f),
1243        }
1244    }
1245}
1246
1247impl<T: Copy + FromStr> FromStr for KeywordOrString<T> {
1248    type Err = Void;
1249    fn from_str(s: &str) -> Result<Self, Void> {
1250        Ok(match s.parse() {
1251            Ok(y) => KeywordOrString::Known(y),
1252            Err(_) => KeywordOrString::Unknown(s.to_owned()),
1253        })
1254    }
1255}
1256
1257// ============================================================
1258
1259/// A sequence of `T` items, with their order retained
1260///
1261/// Normally when a `Vec<T>` appears in a network document,
1262/// we expect the items to be sortable - they must impl [`EncodeOrd`](encode::EncodeOrd).
1263/// When encoding, the output is always sorted.
1264///
1265/// *This* type retains the ordering.
1266///
1267/// Implements the [`encode`] and [`parse2`] item multiplicity traits.
1268#[derive(Debug, Clone, Hash, Deftly, Eq, PartialEq, Ord, PartialOrd, Educe)]
1269#[educe(Default)]
1270#[derive_deftly(Transparent)]
1271#[allow(clippy::exhaustive_structs)]
1272pub struct RetainedOrderVec<T>(pub Vec<T>);
1273
1274// ============================================================
1275
1276/// Types for decoding times and dates
1277mod timeimpl {
1278    use super::*;
1279    use crate::{Error, NetdocErrorKind as EK, Pos, Result};
1280    use std::time::SystemTime;
1281    use time::{
1282        OffsetDateTime, PrimitiveDateTime, format_description::FormatItem,
1283        macros::format_description,
1284    };
1285
1286    /// A wall-clock time, encoded in Iso8601 format with an intervening
1287    /// space between the date and time.
1288    ///
1289    /// (Example: "2020-10-09 17:38:12")
1290    #[derive(Debug, Copy, Clone, Ord, PartialOrd, Eq, PartialEq, Hash, Deftly)]
1291    #[derive_deftly(Transparent)]
1292    #[allow(clippy::exhaustive_structs)]
1293    pub struct Iso8601TimeSp(pub SystemTime);
1294
1295    /// Formatting object for parsing the space-separated Iso8601 format.
1296    const ISO_8601SP_FMT: &[FormatItem] =
1297        format_description!("[year]-[month]-[day] [hour]:[minute]:[second]");
1298
1299    impl FromStr for Iso8601TimeSp {
1300        type Err = Error;
1301        fn from_str(s: &str) -> Result<Iso8601TimeSp> {
1302            let d = PrimitiveDateTime::parse(s, &ISO_8601SP_FMT).map_err(|e| {
1303                EK::BadArgument
1304                    .at_pos(Pos::at(s))
1305                    .with_msg(format!("invalid time: {}", e))
1306            })?;
1307            Ok(Iso8601TimeSp(d.assume_utc().into()))
1308        }
1309    }
1310
1311    /// Formats a SystemTime according to the given format description
1312    ///
1313    /// Also converts any time::error::format to fmt::Error
1314    /// so that it can be unwrapped in the Display trait impl
1315    fn fmt_with(
1316        t: SystemTime,
1317        format_desc: &[FormatItem],
1318    ) -> core::result::Result<String, fmt::Error> {
1319        OffsetDateTime::from(t)
1320            .format(format_desc)
1321            .map_err(|_| fmt::Error)
1322    }
1323
1324    impl Display for Iso8601TimeSp {
1325        fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
1326            write!(f, "{}", fmt_with(self.0, ISO_8601SP_FMT)?)
1327        }
1328    }
1329
1330    /// A wall-clock time, encoded in ISO8601 format without an intervening
1331    /// space.
1332    ///
1333    /// This represents a specific UTC instant (ie an instant in global civil time).
1334    /// But it may not be able to represent leap seconds.
1335    ///
1336    /// The timezone is not included in the string representation; `+0000` is implicit.
1337    ///
1338    /// # Example
1339    ///
1340    /// ```
1341    /// use tor_netdoc::types::Iso8601TimeNoSp;
1342    ///
1343    /// let s = "2020-10-09T17:38:12";
1344    /// let t: Iso8601TimeNoSp = s.parse().unwrap();
1345    /// assert_eq!(t.to_string(), s);
1346    /// ```
1347    #[derive(Debug, Copy, Clone, Ord, PartialOrd, Eq, PartialEq, Hash, Deftly)]
1348    #[derive_deftly(Transparent)]
1349    #[allow(clippy::exhaustive_structs)]
1350    pub struct Iso8601TimeNoSp(pub SystemTime);
1351
1352    /// Formatting object for parsing the space-separated Iso8601 format.
1353    const ISO_8601NOSP_FMT: &[FormatItem] =
1354        format_description!("[year]-[month]-[day]T[hour]:[minute]:[second]");
1355
1356    impl FromStr for Iso8601TimeNoSp {
1357        type Err = Error;
1358        fn from_str(s: &str) -> Result<Iso8601TimeNoSp> {
1359            let d = PrimitiveDateTime::parse(s, &ISO_8601NOSP_FMT).map_err(|e| {
1360                EK::BadArgument
1361                    .at_pos(Pos::at(s))
1362                    .with_msg(format!("invalid time: {}", e))
1363            })?;
1364            Ok(Iso8601TimeNoSp(d.assume_utc().into()))
1365        }
1366    }
1367
1368    impl Display for Iso8601TimeNoSp {
1369        fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
1370            write!(f, "{}", fmt_with(self.0, ISO_8601NOSP_FMT)?)
1371        }
1372    }
1373
1374    impl crate::NormalItemArgument for Iso8601TimeNoSp {}
1375}
1376
1377/// Types for decoding RSA keys
1378mod rsa {
1379    use super::*;
1380    use crate::{NetdocErrorKind as EK, Pos, Result};
1381    use std::ops::RangeBounds;
1382    use tor_llcrypto::pk::rsa::PublicKey;
1383    use tor_llcrypto::{d::Sha1, pk::rsa::KeyPair};
1384
1385    /// The fixed exponent which we require when parsing any RSA key in a netdoc
1386    //
1387    // TODO this value is duplicated a lot in the v1 parser
1388    pub(crate) const RSA_FIXED_EXPONENT: u32 = 65537;
1389
1390    /// The fixed exponent which we require when parsing any RSA key in a netdoc
1391    //
1392    // TODO this value is duplicated a lot in the v1 parser
1393    pub(crate) const RSA_MIN_BITS: usize = 1024;
1394
1395    /// RSA public key, partially processed by `crate::paarse`.
1396    ///
1397    /// As parsed from a base64-encoded object.
1398    /// They key's properties (exponent and size) haven't been checked.
1399    #[allow(non_camel_case_types)]
1400    #[derive(Clone, Debug)]
1401    pub(crate) struct RsaPublicParse1Helper(PublicKey, Pos);
1402
1403    /// RSA signature using SHA-1 as per "Signing documents" in dir-spec
1404    ///
1405    /// <https://spec.torproject.org/dir-spec/netdoc.html#signing>
1406    ///
1407    /// Used for
1408    /// [`AuthCert::dir-key-certification`](crate::doc::authcert::AuthCert::dir-key-certification),
1409    /// for example.
1410    ///
1411    /// # Caveats
1412    ///
1413    /// This type MUST NOT be used for anomalous signatures
1414    /// such as
1415    /// [`AuthCert::dir_key_crosscert`](crate::doc::authcert::AuthCert::dir_key_crosscert);
1416    /// in that case because `dir_key_crosscert`'s
1417    /// set of allowed object labels includes `ID SIGNATURE` whereas this type
1418    /// is always `SIGNATURE`
1419    #[derive(Debug, Clone, PartialEq, Eq, Deftly)]
1420    #[derive_deftly(ItemValueParseable, ItemValueEncodable)]
1421    #[deftly(netdoc(no_extra_args, signature(hash_accu = Sha1WholeKeywordLine)))]
1422    #[non_exhaustive]
1423    pub struct RsaSha1Signature {
1424        /// The bytes of the signature (base64-decoded).
1425        #[deftly(netdoc(object(label = "SIGNATURE"), with = crate::types::raw_data_object))]
1426        pub signature: Vec<u8>,
1427    }
1428
1429    impl From<RsaPublicParse1Helper> for PublicKey {
1430        fn from(k: RsaPublicParse1Helper) -> PublicKey {
1431            k.0
1432        }
1433    }
1434    impl super::FromBytes for RsaPublicParse1Helper {
1435        fn from_bytes(b: &[u8], pos: Pos) -> Result<Self> {
1436            let key = PublicKey::from_der(b)
1437                .ok_or_else(|| EK::BadObjectVal.with_msg("unable to decode RSA public key"))?;
1438            Ok(RsaPublicParse1Helper(key, pos))
1439        }
1440    }
1441    impl RsaPublicParse1Helper {
1442        /// Give an error if the exponent of this key is not 'e'
1443        pub(crate) fn check_exponent(self, e: u32) -> Result<Self> {
1444            if self.0.exponent_is(e) {
1445                Ok(self)
1446            } else {
1447                Err(EK::BadObjectVal
1448                    .at_pos(self.1)
1449                    .with_msg("invalid RSA exponent"))
1450            }
1451        }
1452        /// Give an error if the length of this key's modulus, in
1453        /// bits, is not contained in 'bounds'
1454        pub(crate) fn check_len<B: RangeBounds<usize>>(self, bounds: B) -> Result<Self> {
1455            if bounds.contains(&self.0.bits()) {
1456                Ok(self)
1457            } else {
1458                Err(EK::BadObjectVal
1459                    .at_pos(self.1)
1460                    .with_msg("invalid RSA length"))
1461            }
1462        }
1463        /// Give an error if the length of this key's modulus, in
1464        /// bits, is not exactly `n`.
1465        pub(crate) fn check_len_eq(self, n: usize) -> Result<Self> {
1466            self.check_len(n..=n)
1467        }
1468    }
1469
1470    impl RsaSha1Signature {
1471        /// Make a signature according to "Signing documents" in the netdoc spec
1472        ///
1473        /// <https://spec.torproject.org/dir-spec/netdoc.html#signing>
1474        ///
1475        /// `NetdocEncoder` should have had the body of the document
1476        /// (everything except the signatures) already encoded.
1477        ///
1478        /// `item_keyword` is the keyword for the signature item.
1479        /// This is needed because different documents use different keywords,
1480        /// and the keyword is covered by the signature (an annoying is a layering violation).
1481        /// See <https://gitlab.torproject.org/tpo/core/torspec/-/issues/322>.
1482        ///
1483        /// # Example
1484        ///
1485        /// ```
1486        /// use derive_deftly::Deftly;
1487        /// use tor_error::Bug;
1488        /// use tor_llcrypto::pk::rsa;
1489        /// use tor_netdoc::derive_deftly_template_NetdocEncodable;
1490        /// use tor_netdoc::encode::{NetdocEncodable, NetdocEncoder};
1491        /// use tor_netdoc::types::RsaSha1Signature;
1492        ///
1493        /// #[derive(Deftly, Default)]
1494        /// #[derive_deftly(NetdocEncodable)]
1495        /// pub struct Document {
1496        ///     pub document_intro_keyword: (),
1497        /// }
1498        /// #[derive(Deftly)]
1499        /// #[derive_deftly(NetdocEncodable)]
1500        /// pub struct DocumentSignatures {
1501        ///     pub document_signature: RsaSha1Signature,
1502        /// }
1503        /// impl Document {
1504        ///     pub fn encode_sign(&self, k: &rsa::KeyPair) -> Result<String, Bug> {
1505        ///         let mut encoder = NetdocEncoder::new();
1506        ///         self.encode_unsigned(&mut encoder)?;
1507        ///         let document_signature =
1508        ///             RsaSha1Signature::new_sign_netdoc(k, &encoder, "document-signature")?;
1509        ///         let sigs = DocumentSignatures { document_signature };
1510        ///         sigs.encode_unsigned(&mut encoder)?;
1511        ///         let encoded = encoder.finish()?;
1512        ///         Ok(encoded)
1513        ///     }
1514        /// }
1515        ///
1516        /// # fn main() -> Result<(), anyhow::Error> {
1517        /// let k = rsa::KeyPair::generate(&mut tor_basic_utils::test_rng::testing_rng())?;
1518        /// let doc = Document::default();
1519        /// let encoded = doc.encode_sign(&k)?;
1520        /// assert!(encoded.starts_with(concat!(
1521        ///     "document-intro-keyword\n",
1522        ///     "document-signature\n",
1523        ///     "-----BEGIN SIGNATURE-----\n",
1524        /// )));
1525        /// # Ok(())
1526        /// # }
1527        /// ```
1528        pub fn new_sign_netdoc(
1529            private_key: &KeyPair,
1530            encoder: &NetdocEncoder,
1531            item_keyword: &str,
1532        ) -> StdResult<Self, Bug> {
1533            let mut h = Sha1::new();
1534            h.update(encoder.text_sofar()?);
1535            h.update(item_keyword);
1536            h.update("\n");
1537            let h = h.finalize();
1538            let signature = private_key
1539                .sign(&h)
1540                .map_err(into_internal!("RSA signing failed"))?;
1541            Ok(RsaSha1Signature { signature })
1542        }
1543    }
1544}
1545
1546/// Types for decoding Ed25519 certificates
1547mod edcert {
1548    use std::result::Result as StdResult;
1549    use std::time::SystemTime;
1550
1551    use crate::types::EmbeddedCert;
1552    use crate::{
1553        NetdocErrorKind as EK, Pos, Result,
1554        parse2::{ErrorProblem, VerifyFailed},
1555        types::EmbeddableCertObject,
1556    };
1557    use tor_cert::{CertType, CertifiedKey, Ed25519Cert, KeyUnknownCert};
1558    use tor_checkable::signed::SignatureGated;
1559    use tor_checkable::timed::TimeRangeBound;
1560    use tor_checkable::{SelfSigned, TimeBound};
1561    use tor_error::{Bug, into_internal};
1562    use tor_llcrypto::pk::ed25519::{self, Ed25519PublicKey, ValidatableEd25519Signature};
1563
1564    /// An ed25519 certificate as parsed from a directory object, with
1565    /// signature not validated.
1566    #[derive(Debug, Clone)]
1567    pub(crate) struct UnvalidatedEdCert(KeyUnknownCert, Pos);
1568
1569    impl super::FromBytes for UnvalidatedEdCert {
1570        fn from_bytes(b: &[u8], p: Pos) -> Result<Self> {
1571            let cert = Ed25519Cert::decode(b).map_err(|e| {
1572                EK::BadObjectVal
1573                    .at_pos(p)
1574                    .with_msg("Bad certificate")
1575                    .with_source(e)
1576            })?;
1577
1578            Ok(Self(cert, p))
1579        }
1580        fn from_vec(v: Vec<u8>, p: Pos) -> Result<Self> {
1581            Self::from_bytes(&v[..], p)
1582        }
1583    }
1584    impl UnvalidatedEdCert {
1585        /// Give an error if this certificate's type is not `desired_type`.
1586        pub(crate) fn check_cert_type(self, desired_type: CertType) -> Result<Self> {
1587            if self.0.peek_cert_type() != desired_type {
1588                return Err(EK::BadObjectVal.at_pos(self.1).with_msg(format!(
1589                    "bad certificate type {} (wanted {})",
1590                    self.0.peek_cert_type(),
1591                    desired_type
1592                )));
1593            }
1594            Ok(self)
1595        }
1596        /// Give an error if this certificate's subject_key is not `pk`
1597        pub(crate) fn check_subject_key_is(self, pk: &ed25519::Ed25519Identity) -> Result<Self> {
1598            if self.0.peek_subject_key().as_ed25519() != Some(pk) {
1599                return Err(EK::BadObjectVal
1600                    .at_pos(self.1)
1601                    .with_msg("incorrect subject key"));
1602            }
1603            Ok(self)
1604        }
1605        /// Consume this object and return the inner Ed25519 certificate.
1606        pub(crate) fn into_unchecked(self) -> KeyUnknownCert {
1607            self.0
1608        }
1609    }
1610
1611    /// An Ed25519 identity certificate.
1612    ///
1613    /// This is a certificate of [`CertType::IDENTITY_V_SIGNING`] where the
1614    /// relay's long-term ed25519 identity key signs the relay's medium-term
1615    /// ed25519 signing key, used for signing almost all other certifications
1616    /// associated with a given relay.
1617    #[derive(Debug, Clone, PartialEq, Eq)]
1618    #[allow(clippy::exhaustive_structs)]
1619    pub struct Ed25519IdentityCert {
1620        /// The long-term ed25519 identity key of the relay
1621        pub id_ed25519: ed25519::Ed25519Identity,
1622        /// The medium-term ed25519 signing key of the relay.
1623        pub sign_ed25519: ed25519::Ed25519Identity,
1624    }
1625
1626    impl EmbeddableCertObject<KeyUnknownCert> for Ed25519IdentityCert {
1627        const LABEL: &str = "ED25519 CERT";
1628    }
1629
1630    impl Ed25519IdentityCert {
1631        /// Verifies the validity of an [`Ed25519IdentityCert`].
1632        ///
1633        /// # Requirements
1634        ///
1635        /// 1. MUST have the identity key in the `signed-with-ed25519-key` extension.
1636        /// 2. MUST have a valid signature by the identity key.
1637        /// 3. MUST be of [`CertType::IDENTITY_V_SIGNING`].
1638        /// 4. Certified key MUST BE of [`tor_cert::CertifiedKey::Ed25519`].
1639        /// 5. Both keys MUST be valid mappings to a [`ed25519::PublicKey`].
1640        pub fn verify(cert: KeyUnknownCert) -> StdResult<TimeRangeBound<Self>, VerifyFailed> {
1641            let cert = cert
1642                // 1. MUST have the identity key in the `signed-with-ed25519-key` extension.
1643                .should_have_signing_key()
1644                .map_err(|_| VerifyFailed::ParseEmbedded(ErrorProblem::ObjectInvalidData))?
1645                // 2. MUST have a valid signature by the identity key.
1646                .check_signature()?
1647                // Okay to call because we create TimeRangeBound later.
1648                // TODO DIRAUTH: Use TimeRangeBound instead.
1649                .dangerously_assume_timely();
1650
1651            // 3. MUST be of [`CertType::IDENTITY_V_SIGNING`].
1652            if cert.cert_type() != CertType::IDENTITY_V_SIGNING {
1653                return Err(VerifyFailed::ParseEmbedded(ErrorProblem::ObjectInvalidData));
1654            }
1655
1656            // Bug is alright because .should_have_signing_key() assured us.
1657            let id_ed25519 = *cert.signing_key().ok_or(VerifyFailed::Bug)?;
1658
1659            // 4. Certified key MUST BE of [`tor_cert::CertifiedKey::Ed25519`].
1660            let sign_ed25519 = *cert
1661                .subject_key()
1662                .as_ed25519()
1663                .ok_or(VerifyFailed::ParseEmbedded(ErrorProblem::ObjectInvalidData))?;
1664
1665            // 5. Both keys MUST be valid mappings to a [`ed25519::PublicKey`].
1666            // Unsure if this check is required or implied by (2) but defensive
1667            // programming does not hurt.
1668            if ed25519::PublicKey::try_from(id_ed25519).is_err()
1669                || ed25519::PublicKey::try_from(sign_ed25519).is_err()
1670            {
1671                return Err(VerifyFailed::ParseEmbedded(ErrorProblem::ObjectInvalidData));
1672            }
1673
1674            Ok(TimeRangeBound::new(
1675                Self {
1676                    id_ed25519,
1677                    sign_ed25519,
1678                },
1679                ..cert.expiry(),
1680            ))
1681        }
1682
1683        /// Creates a new signed [`Ed25519IdentityCert`].
1684        pub fn new_signed(
1685            id_ed25519: &ed25519::Keypair,
1686            sign_ed25519: ed25519::Ed25519Identity,
1687            expiry: SystemTime,
1688        ) -> StdResult<EmbeddedCert<Self, KeyUnknownCert>, Bug> {
1689            let cert = Ed25519Cert::builder()
1690                .expiration(expiry)
1691                .signing_key(id_ed25519.public_key().into())
1692                .cert_type(CertType::IDENTITY_V_SIGNING)
1693                .cert_key(sign_ed25519.into())
1694                .encode_and_sign(id_ed25519)
1695                .map_err(into_internal!("failed to encode and sign identity cert"))?;
1696
1697            let cert =
1698                Ed25519Cert::decode(&cert).map_err(into_internal!("decode just encoded cert"))?;
1699
1700            Ok(EmbeddedCert::new(
1701                Self {
1702                    id_ed25519: id_ed25519.public_key().into(),
1703                    sign_ed25519,
1704                },
1705                cert,
1706            ))
1707        }
1708    }
1709
1710    /// An Ed25519 family certificate.
1711    ///
1712    /// This is a certificate of [`CertType::FAMILY_V_IDENTITY`] where the
1713    /// family key signs the long-term ed25519 identity key of the given relay.
1714    ///
1715    /// It purposely does not store the long-term ed25519 identity key of the
1716    /// relay because the idea of this type should be equal only to other types
1717    /// with the same family key.
1718    #[derive(Debug, Clone, PartialEq, Eq)]
1719    #[allow(clippy::exhaustive_structs)]
1720    pub struct Ed25519FamilyCert {
1721        /// The public key of the family.
1722        // TODO: We probably want to add a getter for this returning the
1723        // family name as in:
1724        // <https://spec.torproject.org/dir-spec/server-descriptor-format.html#item:family-cert>
1725        pub family_ed25519: ed25519::Ed25519Identity,
1726    }
1727
1728    impl EmbeddableCertObject<KeyUnknownCert> for Ed25519FamilyCert {
1729        const LABEL: &str = "FAMILY CERT";
1730    }
1731
1732    impl Ed25519FamilyCert {
1733        /// Verifies the validity of an [`Ed25519FamilyCert`].
1734        ///
1735        /// For such a certificate to be valid, the caller must provide a
1736        /// known Ed25519 identity key of the relay beforehand.
1737        ///
1738        /// # Requirements
1739        ///
1740        /// 1. MUST have the `signed-with-ed25519-key` extension containing the family key.
1741        /// 2. MUST have a valid signature by the family key.
1742        /// 3. MUST be of of [`CertType::FAMILY_V_IDENTITY`].
1743        /// 4. Certified key MUST BE of [`tor_cert::CertifiedKey::Ed25519`].
1744        /// 5. `id_ed25519` MUST be the certified key.
1745        /// 6. Both keys MUST be valid mappings to a [`ed25519::PublicKey`].
1746        pub fn verify(
1747            id_ed25519: ed25519::Ed25519Identity,
1748            cert: KeyUnknownCert,
1749        ) -> StdResult<TimeRangeBound<Self>, VerifyFailed> {
1750            let cert = cert
1751                // 1. MUST have the `signed-with-ed25519-key` extension containing the family key.
1752                .should_have_signing_key()?
1753                // 2. MUST have a valid signature by the family key.
1754                .check_signature()?
1755                // Okay to call because we create TimeRangeBound later.
1756                // TODO DIRAUTH: Use TimeRangeBound instead.
1757                .dangerously_assume_timely();
1758
1759            // 3. MUST be of of [`CertType::FAMILY_V_IDENTITY`].
1760            if cert.cert_type() != CertType::FAMILY_V_IDENTITY {
1761                return Err(ErrorProblem::ObjectInvalidData.into());
1762            }
1763
1764            // Bug is alright because .should_have_signing_key() assured us.
1765            let family_ed25519 = *cert.signing_key().ok_or(VerifyFailed::Bug)?;
1766
1767            // 4. Certified key MUST BE of [`tor_cert::CertifiedKey::Ed25519`].
1768            let certified_key = *cert
1769                .subject_key()
1770                .as_ed25519()
1771                .ok_or(VerifyFailed::ParseEmbedded(ErrorProblem::ObjectInvalidData))?;
1772
1773            // 5. `id_ed25519` MUST be the certified key.
1774            if certified_key != id_ed25519 {
1775                return Err(VerifyFailed::VerifyFailed);
1776            }
1777
1778            // 6. Both keys MUST be valid mappings to a [`ed25519::PublicKey`].
1779            if ed25519::PublicKey::try_from(family_ed25519).is_err()
1780                || ed25519::PublicKey::try_from(id_ed25519).is_err()
1781            {
1782                return Err(VerifyFailed::ParseEmbedded(ErrorProblem::ObjectInvalidData));
1783            }
1784
1785            Ok(TimeRangeBound::new(
1786                Self { family_ed25519 },
1787                ..cert.expiry(),
1788            ))
1789        }
1790
1791        /// Creates a new signed [`Ed25519FamilyCert`].
1792        pub fn new_signed(
1793            family_ed25519: &ed25519::Keypair,
1794            id_ed25519: ed25519::Ed25519Identity,
1795            expiry: SystemTime,
1796        ) -> StdResult<EmbeddedCert<Self, KeyUnknownCert>, Bug> {
1797            let cert = Ed25519Cert::builder()
1798                .expiration(expiry)
1799                .signing_key(family_ed25519.public_key().into())
1800                .cert_type(CertType::FAMILY_V_IDENTITY)
1801                .cert_key(id_ed25519.into())
1802                .encode_and_sign(family_ed25519)
1803                .map_err(into_internal!("failed to encode and sign family cert"))?;
1804
1805            let cert =
1806                Ed25519Cert::decode(&cert).map_err(into_internal!("decode just encoded cert"))?;
1807
1808            Ok(EmbeddedCert::new(
1809                Self {
1810                    family_ed25519: family_ed25519.public_key().into(),
1811                },
1812                cert,
1813            ))
1814        }
1815    }
1816
1817    /// Verified reverse cert by K_ntor on KP_relayid_ed
1818    ///
1819    /// This certificate is signed by KS_ntor
1820    /// (the circuit extension key) and certifies
1821    /// KP_relayid_ed25519 ed25519 identity key of the relay.
1822    ///
1823    /// The type itself is zero-sized because it provides no new useful
1824    /// information that cannot be found elsewhere within the router descriptor.
1825    /// It is intended for use within
1826    /// [`EmbeddedCert`]`<Ed25519NtorCrossCert, KeyUnknownCert>`
1827    ///
1828    /// # Note on key conversion
1829    ///
1830    /// Keep in mind however that the ntor onion key is only provided as an
1831    /// X25519 key and *not* an Ed25519 key, meaning that interfacing
1832    /// applications have to convert it using a function such as
1833    /// [`tor_llcrypto::pk::keymanip::convert_curve25519_to_ed25519_public()`].
1834    /// This also requires obtaining the sign bit which is usually given as an
1835    /// argument in the `ntor-onion-key-crosscert` item.  However, this is
1836    /// outside of the scope of this struct and the code will assume that
1837    /// callers have already converted the X25519 public key to an Ed25519
1838    /// public key as outlined in the specifications.
1839    ///
1840    /// # See Also
1841    ///
1842    /// * <https://spec.torproject.org/dir-spec/server-descriptor-format.html#item:ntor-onion-key-crosscert>
1843    /// * <https://spec.torproject.org/dir-spec/converting-to-ed25519.html>
1844    #[derive(Debug, Clone, Copy, PartialEq, Eq)]
1845    #[non_exhaustive]
1846    pub struct Ed25519NtorCrossCert {
1847        /// Explicit field, to avoid constructing this accidentally without
1848        /// doing all the verification.
1849        _promise_we_verified: (),
1850    }
1851
1852    impl EmbeddableCertObject<KeyUnknownCert> for Ed25519NtorCrossCert {
1853        const LABEL: &str = "ED25519 CERT";
1854    }
1855
1856    impl Ed25519NtorCrossCert {
1857        /// Verifies the validity of an [`Ed25519NtorCrossCert`].
1858        ///
1859        /// For such a certificate to be valid, the caller must provide a known
1860        /// Ed25519 identity key and Ed25519 ntor onion key of the relay
1861        /// beforehand.
1862        ///
1863        /// # Requirements
1864        ///
1865        /// 1. MUST be of [`CertType::NTOR_CC_IDENTITY`].
1866        /// 2. Certified key MUST be of [`CertifiedKey::Ed25519`].
1867        /// 3. Certified key MUST be equal to `id_ed25519`.
1868        /// 4. MUST have a valid signature.
1869        pub fn verify(
1870            ntor_ed25519: ed25519::Ed25519Identity,
1871            id_ed25519: ed25519::Ed25519Identity,
1872            cert: KeyUnknownCert,
1873        ) -> StdResult<TimeRangeBound<Self>, VerifyFailed> {
1874            Ok(
1875                // .verify_inner() ensures 1-3.
1876                Self::verify_inner(ntor_ed25519, id_ed25519, cert)?
1877                    .0
1878                    // 4. MUST have a valid signature.
1879                    .check_signature()?,
1880            )
1881        }
1882
1883        /// Creates a new signed [`Ed25519NtorCrossCert`].
1884        pub fn new_signed(
1885            ntor_ed25519: &ed25519::ExpandedKeypair,
1886            id_ed25519: ed25519::Ed25519Identity,
1887            expiry: SystemTime,
1888        ) -> StdResult<EmbeddedCert<Self, KeyUnknownCert>, Bug> {
1889            let cert = Ed25519Cert::builder()
1890                .expiration(expiry)
1891                .cert_type(CertType::NTOR_CC_IDENTITY)
1892                .cert_key(id_ed25519.into())
1893                .encode_and_sign(ntor_ed25519)
1894                .map_err(into_internal!("failed to encode and sign ntor cert"))?;
1895
1896            let cert =
1897                Ed25519Cert::decode(&cert).map_err(into_internal!("decode just encoded cert"))?;
1898
1899            Ok(EmbeddedCert::new(
1900                Self {
1901                    _promise_we_verified: (),
1902                },
1903                cert,
1904            ))
1905        }
1906
1907        /// Verifies the validity of a [`KeyUnknownCert`] believed to be a
1908        /// [`CertType::NTOR_CC_IDENTITY`].
1909        ///
1910        /// This function serves as glue between the legacy parser and
1911        /// [`Self::verify()`].
1912        ///
1913        /// # Requirements
1914        ///
1915        /// 1. MUST be of [`CertType::NTOR_CC_IDENTITY`].
1916        /// 2. Certified key MUST be of [`CertifiedKey::Ed25519`].
1917        /// 3. Certified key MUST be equal to `id_ed25519`.
1918        ///
1919        /// # Return Type
1920        ///
1921        /// Actual signature and time validation is done by the caller, hence
1922        /// why it returns a gated type as the first element of the tuple.
1923        /// The other elements constitute the inner signature plus the
1924        /// SystemTime denoting the expiry.  This is required for integration
1925        /// with legacy parser in order to enable pushing it to the verification
1926        /// batch, as the [`tor_checkable`] primitives do not provide access
1927        /// to the inner signatures/expiries and also do not support operations
1928        /// like cloning due to being dyn.
1929        pub(crate) fn verify_inner(
1930            ntor_ed25519: ed25519::Ed25519Identity,
1931            id_ed25519: ed25519::Ed25519Identity,
1932            cert: KeyUnknownCert,
1933        ) -> StdResult<
1934            (
1935                SignatureGated<TimeRangeBound<Self>>,
1936                ValidatableEd25519Signature,
1937                SystemTime,
1938            ),
1939            VerifyFailed,
1940        > {
1941            // 1. MUST be of [`CertType::NTOR_CC_IDENTITY`].
1942            if cert.peek_cert_type() != CertType::NTOR_CC_IDENTITY {
1943                return Err(ErrorProblem::ObjectInvalidData.into());
1944            }
1945
1946            // 2. Certified key MUST be of [`CertifiedKey::Ed25519`].
1947            // 3. Certified key MUST be equal to `id_ed25519`.
1948            if cert.peek_subject_key() != &CertifiedKey::Ed25519(id_ed25519) {
1949                return Err(VerifyFailed::VerifyFailed);
1950            }
1951
1952            // Fish out the signature from the certificate and verify it later.
1953            //
1954            // It may fail if ntor_ed25519 is not a valid mapping to a public
1955            // key.  This is okay.  The .should_be_signed_with() call is
1956            // tor_cert boilerplate and only required to obtain an
1957            // UncheckedCert, as ntor cross-certificates do not contain the
1958            // signed-with extension.
1959            let (cert, sig) = cert
1960                .should_be_signed_with(&ntor_ed25519)?
1961                .dangerously_split()?;
1962
1963            // Fish out the expiration date from the certificate.
1964            //
1965            // Important: We must not set SystemTime::UNIX_EPOCH as the lower
1966            // bound, because with TimeRangeBound, a lower-bound of zero is not
1967            // equal to an absent lower bound!
1968            let cert = cert.dangerously_assume_timely();
1969            let expiration = ..cert.expiry();
1970
1971            Ok((
1972                SignatureGated::new(
1973                    TimeRangeBound::new(
1974                        Self {
1975                            _promise_we_verified: (),
1976                        },
1977                        expiration,
1978                    ),
1979                    vec![Box::new(sig.clone())],
1980                ),
1981                sig,
1982                expiration.end,
1983            ))
1984        }
1985
1986        /// Internal function for creating an unverified instance.
1987        ///
1988        /// This is only intended for testing and legacy parser compatibility
1989        /// purposes.
1990        pub(crate) fn dangerous_new_unverified() -> Self {
1991            Self {
1992                _promise_we_verified: (),
1993            }
1994        }
1995    }
1996}
1997
1998/// Digest identifiers, and digests in the form `ALGORITHM=BASE64U`
1999///
2000/// As found in a vote's `m` line.
2001// TODO Use FixedB64 here.
2002mod identified_digest {
2003    use super::*;
2004
2005    define_derive_deftly! {
2006        /// impl `FromStr` and `Display` for an enum with unit variants but also "unknown"
2007        ///
2008        /// Expected input: an enum whose variants are either
2009        ///  * unit variants, perhaps with `#[deftly(string_repr = "string")]`
2010        ///  * singleton tuple variant, containing `String` (or near equivalent)
2011        ///
2012        /// If `#[deftly(string_repro)]` is not specified,
2013        /// the default is snake case of the variant name.
2014        //
2015        // This macro may seem overkill, but open-coding these impls gives opportunities
2016        // for mismatches between FromStr, Display, and the variant name.
2017        //
2018        // TODO consider putting this in tor-basic-utils (maybe with a better name),
2019        // or possibly asking if derive_more want their FromStr to have this.
2020        StringReprUnitsOrUnknown for enum, expect items, beta_deftly:
2021
2022        ${define STRING_REPR {
2023            ${vmeta(string_repr)
2024              as str,
2025              default { ${concat ${snake_case $vname}} }
2026            }
2027        }}
2028
2029        ${impl FromStr} {
2030            type Err = Void;
2031            fn from_str(s: &str) -> Result<Self, Void> {
2032                $(
2033                    ${when v_is_unit}
2034                    if s == $STRING_REPR {
2035                        return Ok($vtype)
2036                    }
2037                )
2038                $(
2039                    ${when not(v_is_unit)} // anything else had better be Unknown
2040                    // not using `return ..;` makes this a syntax error if there are several.
2041                    Ok($vtype { 0: s.into() })
2042                )
2043            }
2044        }
2045        ${impl AsRef<str>} {
2046            fn as_ref(&self) -> &str {
2047                match self {
2048                    $(
2049                        ${when v_is_unit}
2050                        $vtype => $STRING_REPR,
2051                    )
2052                    $(
2053                        ${when not(v_is_unit)}
2054                        $vpat => f_0,
2055                    )
2056                }
2057            }
2058        }
2059        ${impl Display} {
2060            fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
2061                let s: &str = self.as_ref();
2062                Display::fmt(s, f)
2063            }
2064        }
2065    }
2066
2067    /// The name of a digest algorithm.
2068    ///
2069    /// Can represent an unrecognised algorithm, so it's parsed and reproduced.
2070    #[derive(Debug, Clone, Eq, PartialEq, Hash, Deftly)]
2071    #[derive_deftly(StringReprUnitsOrUnknown)]
2072    #[non_exhaustive]
2073    pub enum DigestName {
2074        /// SHA-256
2075        Sha256,
2076        /// Unknown
2077        Unknown(String),
2078    }
2079
2080    /// A single digest made with a nominated digest algorithm, `ALGORITHM=DIGEST`
2081    #[derive(Debug, Clone, Eq, PartialEq, Ord, PartialOrd, Hash, derive_more::Display)]
2082    #[display("{alg}={value}")]
2083    #[allow(clippy::exhaustive_structs)] // Seems very unlikely to grow
2084    pub struct IdentifiedDigest {
2085        /// The algorithm name.
2086        pub alg: DigestName,
2087
2088        /// The digest value.
2089        ///
2090        /// Invariant: length is correct for `alg`, assuming `alg` is known.
2091        pub value: B64,
2092    }
2093
2094    impl NormalItemArgument for DigestName {}
2095    impl NormalItemArgument for IdentifiedDigest {}
2096
2097    /// Invalid syntax parsing an `IdentifiedDigest`
2098    #[derive(Debug, Clone, Eq, PartialEq, Ord, PartialOrd, Hash, thiserror::Error)]
2099    #[error("invalid syntax, expected ALGORITHM=DIGEST: {0}")]
2100    pub struct IdentifiedDigestParseError(String);
2101
2102    impl Ord for DigestName {
2103        fn cmp(&self, other: &Self) -> Ordering {
2104            self.as_ref().cmp(other.as_ref())
2105        }
2106    }
2107    impl PartialOrd for DigestName {
2108        fn partial_cmp(&self, other: &Self) -> Option<Ordering> {
2109            Some(self.cmp(other))
2110        }
2111    }
2112
2113    impl FromStr for IdentifiedDigest {
2114        type Err = IdentifiedDigestParseError;
2115
2116        fn from_str(s: &str) -> Result<Self, Self::Err> {
2117            (|| {
2118                let (alg, value) = s.split_once('=').ok_or("missing equals sign")?;
2119
2120                let alg = alg.parse().void_unwrap();
2121                let value = value
2122                    .parse::<B64>()
2123                    .map_err(|e| format!("bad value: {}", e.report()))?;
2124
2125                if let Some(exp_len) = (|| {
2126                    Some({
2127                        use DigestName::*;
2128                        match alg {
2129                            Sha256 => 32,
2130                            Unknown(_) => None?,
2131                        }
2132                    })
2133                })() {
2134                    let val_len = value.as_bytes().len();
2135                    if val_len != exp_len {
2136                        return Err(format!("got {val_len} bytes, expected {exp_len}"));
2137                    }
2138                }
2139
2140                Ok(IdentifiedDigest { alg, value })
2141            })()
2142            .map_err(IdentifiedDigestParseError)
2143        }
2144    }
2145}
2146
2147/// Types for decoding RSA fingerprints
2148mod fingerprint {
2149    use super::*;
2150    use crate::parse2::{ArgumentError, ArgumentStream, ItemArgumentParseable};
2151    use crate::{Error, NetdocErrorKind as EK, Pos, Result};
2152    use base64ct::{Base64Unpadded, Encoding as _};
2153    use itertools::Itertools;
2154    use tor_llcrypto::pk::rsa::RsaIdentity;
2155
2156    /// A hex-encoded RSA key identity (fingerprint) with spaces in it.
2157    ///
2158    /// <https://spec.torproject.org/dir-spec/server-descriptor-format.html?highlight=fingerprint#item:fingerprint>
2159    ///
2160    /// Netdoc parsing adapter for [`RsaIdentity`]
2161    #[derive(Debug, Clone, Copy, Eq, PartialEq, Ord, PartialOrd, Hash, Deftly)]
2162    #[derive_deftly(Transparent)]
2163    #[allow(clippy::exhaustive_structs)]
2164    pub struct SpFingerprint(pub RsaIdentity);
2165
2166    /// A hex-encoded fingerprint with no spaces.
2167    ///
2168    /// Netdoc parsing adapter for [`RsaIdentity`]
2169    #[derive(Debug, Clone, Copy, Eq, PartialEq, Ord, PartialOrd, Hash, Deftly)]
2170    #[derive_deftly(Transparent)]
2171    #[allow(clippy::exhaustive_structs)]
2172    pub struct Fingerprint(pub RsaIdentity);
2173
2174    /// A base64-encoded fingerprint (unpadded)
2175    ///
2176    /// Netdoc parsing adapter for [`RsaIdentity`]
2177    #[derive(Debug, Clone, Copy, Eq, PartialEq, Ord, PartialOrd, Hash, Deftly)]
2178    #[derive_deftly(Transparent)]
2179    #[allow(clippy::exhaustive_structs)]
2180    pub struct Base64Fingerprint(pub RsaIdentity);
2181
2182    /// A "long identity" in the format used for Family members.
2183    ///
2184    /// Netdoc parsing adapter for [`RsaIdentity`]
2185    #[derive(Debug, Clone, Copy, Eq, PartialEq, Ord, PartialOrd, Hash, Deftly)]
2186    #[derive_deftly(Transparent)]
2187    #[allow(clippy::exhaustive_structs)]
2188    pub(crate) struct LongIdent(pub RsaIdentity);
2189
2190    /// Helper: parse an identity from a hexadecimal string
2191    fn parse_hex_ident(s: &str) -> Result<RsaIdentity> {
2192        RsaIdentity::from_hex(s).ok_or_else(|| {
2193            EK::BadArgument
2194                .at_pos(Pos::at(s))
2195                .with_msg("wrong length on fingerprint")
2196        })
2197    }
2198
2199    impl FromStr for SpFingerprint {
2200        type Err = Error;
2201        fn from_str(s: &str) -> Result<SpFingerprint> {
2202            let ident = parse_hex_ident(&s.replace(' ', "")).map_err(|e| e.at_pos(Pos::at(s)))?;
2203            Ok(SpFingerprint(ident))
2204        }
2205    }
2206
2207    impl ItemArgumentParseable for SpFingerprint {
2208        fn from_args<'s>(
2209            args: &mut ArgumentStream<'s>,
2210        ) -> std::result::Result<Self, ArgumentError> {
2211            // Take the first 10 arguments because an SpFingerprint consists of
2212            // 10 x 4 = 40 characters.
2213            let fp = args.take(10).collect::<Vec<_>>();
2214
2215            // Less than 10 means missing arguments.
2216            if fp.len() < 10 {
2217                return Err(ArgumentError::Missing);
2218            }
2219
2220            // More than 10 should be impossible due to .take(10).
2221            debug_assert_eq!(fp.len(), 10);
2222
2223            // All arguments must be 4 characters long.
2224            if fp.iter().any(|arg| arg.len() != 4) {
2225                return Err(ArgumentError::Invalid);
2226            }
2227
2228            // Convert it to a string without spaces, RsaIdentity::from_hex will
2229            // verify the rest.
2230            Ok(Self(
2231                RsaIdentity::from_hex(fp.join("").as_str()).ok_or(ArgumentError::Invalid)?,
2232            ))
2233        }
2234    }
2235
2236    impl encode::ItemArgument for SpFingerprint {
2237        fn write_arg_onto(&self, out: &mut ItemEncoder<'_>) -> StdResult<(), Bug> {
2238            let res = self
2239                .0
2240                .to_bytes()
2241                .chunks(2)
2242                .map(|b| format!("{:02X}{:02X}", b[0], b[1]))
2243                .join(" ");
2244            debug_assert_eq!(res.len(), 4 * 10 + 9);
2245            out.args_raw_string(&res);
2246            Ok(())
2247        }
2248    }
2249
2250    impl FromStr for Base64Fingerprint {
2251        type Err = Error;
2252        fn from_str(s: &str) -> Result<Base64Fingerprint> {
2253            let b = s.parse::<super::B64>()?;
2254            let ident = RsaIdentity::from_bytes(b.as_bytes()).ok_or_else(|| {
2255                EK::BadArgument
2256                    .at_pos(Pos::at(s))
2257                    .with_msg("Wrong identity length")
2258            })?;
2259            Ok(Base64Fingerprint(ident))
2260        }
2261    }
2262
2263    impl Display for Base64Fingerprint {
2264        fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
2265            Display::fmt(&Base64Unpadded::encode_string(self.as_bytes()), f)
2266        }
2267    }
2268
2269    impl FromStr for Fingerprint {
2270        type Err = Error;
2271        fn from_str(s: &str) -> Result<Fingerprint> {
2272            let ident = parse_hex_ident(s).map_err(|e| e.at_pos(Pos::at(s)))?;
2273            Ok(Fingerprint(ident))
2274        }
2275    }
2276
2277    impl Display for Fingerprint {
2278        fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
2279            Display::fmt(&hex::encode_upper(self.as_bytes()), f)
2280        }
2281    }
2282
2283    impl FromStr for LongIdent {
2284        type Err = Error;
2285        fn from_str(mut s: &str) -> Result<LongIdent> {
2286            s = s.strip_prefix('$').unwrap_or(s);
2287            // Strip at '=' or '~' if found.
2288            s = s.split_once(['=', '~']).map(|(a, _)| a).unwrap_or(s);
2289            let ident = parse_hex_ident(s)?;
2290            Ok(LongIdent(ident))
2291        }
2292    }
2293
2294    impl Display for LongIdent {
2295        fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
2296            write!(f, "${}", self.0.as_hex_upper())
2297        }
2298    }
2299
2300    impl crate::NormalItemArgument for Fingerprint {}
2301    impl crate::NormalItemArgument for Base64Fingerprint {}
2302    impl crate::NormalItemArgument for LongIdent {}
2303}
2304
2305/// A type for relay nicknames
2306mod nickname {
2307    use super::*;
2308    use tinystr::TinyAsciiStr;
2309
2310    /// This is a strange limit, but it comes from Tor.
2311    const MAX_NICKNAME_LEN: usize = 19;
2312
2313    /// The nickname for a Tor relay.
2314    ///
2315    /// These nicknames are legacy mechanism that's occasionally useful in
2316    /// debugging. They should *never* be used to uniquely identify relays;
2317    /// nothing prevents two relays from having the same nickname.
2318    ///
2319    /// Nicknames are required to be ASCII, alphanumeric, and between 1 and 19
2320    /// characters inclusive.
2321    #[derive(
2322        Clone,
2323        Debug,
2324        PartialEq,
2325        Eq,
2326        Ord,
2327        PartialOrd,
2328        Hash,
2329        serde_with::SerializeDisplay,
2330        serde_with::DeserializeFromStr,
2331    )]
2332    pub struct Nickname(tinystr::TinyAsciiStr<MAX_NICKNAME_LEN>);
2333
2334    /// Invalid nickname
2335    #[derive(Clone, Debug, thiserror::Error)]
2336    #[error("invalid nickname")]
2337    #[non_exhaustive]
2338    pub struct InvalidNickname {}
2339
2340    impl Nickname {
2341        /// Return a view of this nickname as a string slice.
2342        pub fn as_str(&self) -> &str {
2343            self.0.as_str()
2344        }
2345    }
2346
2347    impl Display for Nickname {
2348        fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
2349            self.as_str().fmt(f)
2350        }
2351    }
2352
2353    impl FromStr for Nickname {
2354        type Err = InvalidNickname;
2355
2356        fn from_str(s: &str) -> Result<Self, InvalidNickname> {
2357            let tiny = TinyAsciiStr::from_str(s).map_err(|_| InvalidNickname {})?;
2358
2359            if tiny.is_ascii_alphanumeric() && !tiny.is_empty() {
2360                Ok(Nickname(tiny))
2361            } else {
2362                Err(InvalidNickname {})
2363            }
2364        }
2365    }
2366
2367    impl AsRef<str> for Nickname {
2368        fn as_ref(&self) -> &str {
2369            self.as_str()
2370        }
2371    }
2372
2373    impl crate::NormalItemArgument for Nickname {}
2374}
2375
2376/// Hostnames etc.
2377//
2378// TODO maybe move all this to tor-basic-utils
2379mod hostname {
2380    use super::*;
2381    use std::net::IpAddr;
2382
2383    /// Internet hostname
2384    ///
2385    /// Valid according to Internet RFC1123,
2386    /// with the additional restriction that there must be at least one letter.
2387    /// (That means that anything accepted as a `Hostname`
2388    /// won't be accepted as an address even by very relaxed IPv4 address parsers.
2389    /// We presume that no TLD will ever exist that is entirely decimal digits.)
2390    ///
2391    /// Preserves case.
2392    ///
2393    /// Reserved hostname such as `example.come`, `tor.invalid` and `localhost`
2394    /// are accepted.
2395    ///
2396    /// # Comparisons; `PartialEq`, `Eq`
2397    ///
2398    /// The `PartialEq` and `Eq` implementations are case sensitive,
2399    /// even though internet hostnames are not case-sensitive.
2400    ///
2401    /// Comparing hostnames for identical apparent meaning is complicated.
2402    /// If you need to do that, you (may) need to engage with punycode (IDN),
2403    /// as well as arranging for a case-insensitive comparison.
2404    ///
2405    /// And of course, hostnames reference to the DNS.
2406    /// A single host may have multiple names and it may change its address.
2407    #[derive(Clone, Debug, Hash, Eq, PartialEq, Ord, PartialOrd)] //
2408    #[derive(derive_more::Into, derive_more::Deref, derive_more::AsRef, derive_more::Display)]
2409    pub struct Hostname(String);
2410
2411    /// Hostname, or IP address (v4 or v6)
2412    ///
2413    /// Preserves hostname case.  See [`Hostname`].
2414    ///
2415    /// Reserved hostnames and addresses (eg `0.0.0.0` or `tor.invalid`) are accepted.
2416    ///
2417    /// IPv6 addresses are represented *without* surrounding `[ ]`.
2418    ///
2419    /// Therefore, you cannot make this into a host-and-port by appending `:port`.
2420    /// To process name-and-port is complex.  `SRV` (or `MX`) records might be involved.
2421    //
2422    // This type is called `InternetHost` to emphasise that it is primarily for
2423    // hosts on the public internet and, unlike arti-client's `Host`,
2424    // has special handling of `.onion` addresses.
2425    #[derive(Clone, Debug, Hash, Eq, PartialEq, Ord, PartialOrd)] //
2426    #[derive(derive_more::Display)]
2427    #[allow(clippy::exhaustive_enums)]
2428    // TODO derive .as_hostname(), .as_ip_addr(), From<Hostname>, From<IpAddr>
2429    pub enum InternetHost {
2430        /// Hostname
2431        #[display("{_0}")]
2432        Name(Hostname),
2433        /// IP address (v4 or v6)
2434        #[display("{_0}")]
2435        IpAddr(IpAddr),
2436    }
2437
2438    /// Invalid hostname
2439    #[derive(Clone, Debug, thiserror::Error)]
2440    #[error("invalid hostname")]
2441    #[non_exhaustive]
2442    pub struct InvalidHostname {}
2443
2444    /// Invalid Internet hostname/address
2445    #[derive(Clone, Debug, thiserror::Error)]
2446    #[error("invalid: not a valid hostname, nor a valid IPv4 or IPv6 address")]
2447    #[non_exhaustive]
2448    pub struct InvalidInternetHost {}
2449
2450    impl Hostname {
2451        /// Obtain this hostname as a `str`
2452        pub fn as_str(&self) -> &str {
2453            &self.0
2454        }
2455    }
2456
2457    impl AsRef<str> for Hostname {
2458        fn as_ref(&self) -> &str {
2459            self.as_str()
2460        }
2461    }
2462
2463    impl TryFrom<String> for Hostname {
2464        type Error = InvalidHostname;
2465        fn try_from(s: String) -> Result<Self, InvalidHostname> {
2466            if hostname_validator::is_valid(&s) &&
2467                // Reject hostnames that consist only of decimal digits and full stops.
2468                // Some of those are accepted by some old IPv4 address parsers.
2469                // If any fool makes a TLD that is only digits, they deserve everything they get.
2470                !s.chars().all(|c| c.is_ascii_digit() || c == '.')
2471            {
2472                Ok(Hostname(s))
2473            } else {
2474                Err(InvalidHostname {})
2475            }
2476        }
2477    }
2478
2479    impl FromStr for Hostname {
2480        type Err = InvalidHostname;
2481        fn from_str(s: &str) -> Result<Self, InvalidHostname> {
2482            s.to_owned().try_into()
2483        }
2484    }
2485
2486    impl FromStr for InternetHost {
2487        type Err = InvalidInternetHost;
2488        fn from_str(s: &str) -> Result<Self, InvalidInternetHost> {
2489            if let Ok(y) = s.parse() {
2490                Ok(InternetHost::IpAddr(y))
2491            } else if let Ok(y) = s.parse() {
2492                Ok(InternetHost::Name(y))
2493            } else {
2494                // For simplicity, we  discard the errors from parsing the options
2495                // rather than trying to reproduce them.  Why something isn't a valid
2496                // address or hostname ought to be fairly obvious.
2497                Err(InvalidInternetHost {})
2498            }
2499        }
2500    }
2501
2502    impl NormalItemArgument for Hostname {}
2503    impl NormalItemArgument for InternetHost {}
2504}
2505
2506/// Contact information of the relay operator.
2507mod contact_info {
2508    use super::*;
2509
2510    /// `contact` item: contact information (eg of a relay dirauth operator)
2511    ///
2512    /// <https://spec.torproject.org/dir-spec/server-descriptor-format.html#item:contact>
2513    ///
2514    /// Also used for authority entries in netstatus documents.
2515    #[derive(Clone, Debug, PartialEq, Eq, Ord, PartialOrd, Hash, Deftly)] //
2516    #[derive(
2517        derive_more::Into,
2518        derive_more::AsRef,
2519        derive_more::Deref,
2520        derive_more::Display,
2521        serde_with::SerializeDisplay,
2522        serde_with::DeserializeFromStr,
2523    )]
2524    #[derive_deftly(ItemValueEncodable)]
2525    #[non_exhaustive]
2526    pub struct ContactInfo(#[deftly(netdoc(rest))] String);
2527
2528    /// Contact information (`contact` item value) has invalid syntax
2529    #[derive(Clone, Debug, thiserror::Error)]
2530    #[error("contact information (`contact` item value) has invalid syntax")]
2531    #[non_exhaustive]
2532    pub struct InvalidContactInfo {}
2533
2534    impl FromStr for ContactInfo {
2535        type Err = InvalidContactInfo;
2536
2537        fn from_str(s: &str) -> Result<Self, InvalidContactInfo> {
2538            // TODO torspec#396 we should probably impose more restrictions
2539            // For now we forbid `\n` and initial whitespace, which is enough to ensure
2540            // that all values will roundtrip unchanged through netdoc encoding and parsing.
2541            if s.contains('\n') || s.starts_with(char::is_whitespace) {
2542                Err(InvalidContactInfo {})
2543            } else {
2544                Ok(ContactInfo(s.to_owned()))
2545            }
2546        }
2547    }
2548
2549    impl ItemValueParseable for ContactInfo {
2550        fn from_unparsed(mut item: UnparsedItem<'_>) -> Result<Self, parse2::ErrorProblem> {
2551            item.check_no_object()?;
2552            item.args_mut()
2553                .into_remaining()
2554                .parse()
2555                .map_err(|_e| item.args().handle_error("info", ArgumentError::Invalid))
2556        }
2557    }
2558}
2559
2560/// Types for boolean-like types.
2561mod boolean {
2562    use derive_deftly::Deftly;
2563    use std::{
2564        fmt::Display,
2565        ops::{Deref, DerefMut},
2566        str::FromStr,
2567    };
2568
2569    use crate::{Error, NetdocErrorKind as EK, NormalItemArgument, Pos};
2570
2571    /// A boolean that is represented by a `0` (false) or `1` (true).
2572    #[derive(Clone, Copy, Debug, Default, PartialEq, Eq, PartialOrd, Ord, Hash, Deftly)]
2573    #[derive_deftly(Transparent)]
2574    #[allow(clippy::exhaustive_structs)]
2575    pub struct NumericBoolean(pub bool);
2576
2577    impl FromStr for NumericBoolean {
2578        type Err = Error;
2579
2580        fn from_str(s: &str) -> Result<Self, Self::Err> {
2581            match s {
2582                "0" => Ok(Self(false)),
2583                "1" => Ok(Self(true)),
2584                _ => Err(EK::BadArgument
2585                    .at_pos(Pos::at(s))
2586                    .with_msg("Invalid numeric boolean")),
2587            }
2588        }
2589    }
2590
2591    impl Display for NumericBoolean {
2592        fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
2593            write!(f, "{}", u8::from(self.0))
2594        }
2595    }
2596
2597    impl NormalItemArgument for NumericBoolean {}
2598}
2599
2600#[cfg(test)]
2601mod test {
2602    // @@ begin test lint list maintained by maint/add_warning @@
2603    #![allow(clippy::bool_assert_comparison)]
2604    #![allow(clippy::clone_on_copy)]
2605    #![allow(clippy::dbg_macro)]
2606    #![allow(clippy::mixed_attributes_style)]
2607    #![allow(clippy::print_stderr)]
2608    #![allow(clippy::print_stdout)]
2609    #![allow(clippy::single_char_pattern)]
2610    #![allow(clippy::unwrap_used)]
2611    #![allow(clippy::unchecked_time_subtraction)]
2612    #![allow(clippy::useless_vec)]
2613    #![allow(clippy::needless_pass_by_value)]
2614    #![allow(clippy::string_slice)] // See arti#2571
2615    //! <!-- @@ end test lint list maintained by maint/add_warning @@ -->
2616    use std::{
2617        fmt::Debug,
2618        time::{Duration, SystemTime},
2619    };
2620
2621    use itertools::Itertools;
2622
2623    use base64ct::Encoding;
2624    use tor_basic_utils::test_rng::testing_rng;
2625    use tor_cert::{CertType, CertifiedKey, Ed25519Cert, KeyUnknownCert};
2626    use tor_checkable::{TimeBound, timed::TimeRangeBound};
2627    use tor_llcrypto::pk::ed25519::{self, Ed25519Identity, Ed25519PublicKey, ExpandedKeypair};
2628
2629    use super::*;
2630    use crate::{
2631        Pos, Result,
2632        encode::{NetdocEncodable, encode_netdoc_unsigned},
2633        parse2::{ErrorProblem, ParseInput, VerifyFailed},
2634        types::EmbeddedCert,
2635    };
2636
2637    /// Decode s as a multi-line base64 string, ignoring ascii whitespace.
2638    fn base64_decode_ignore_ws(s: &str) -> std::result::Result<Vec<u8>, base64ct::Error> {
2639        let mut s = s.to_string();
2640        s.retain(|c| !c.is_ascii_whitespace());
2641        base64ct::Base64::decode_vec(s.as_str())
2642    }
2643
2644    #[test]
2645    fn base64() -> Result<()> {
2646        // Test parsing success:
2647        // Unpadded:
2648        assert_eq!("Mi43MTgyOA".parse::<B64>()?.as_bytes(), &b"2.71828"[..]);
2649        assert!("Mi43MTgyOA".parse::<B64>()?.check_len(7..8).is_ok());
2650        assert_eq!("Mg".parse::<B64>()?.as_bytes(), &b"2"[..]);
2651        assert!("Mg".parse::<B64>()?.check_len(1..2).is_ok());
2652        assert_eq!(
2653            "8J+NkvCfjZLwn42S8J+NkvCfjZLwn42S"
2654                .parse::<B64>()?
2655                .as_bytes(),
2656            "🍒🍒🍒🍒🍒🍒".as_bytes()
2657        );
2658        assert!(
2659            "8J+NkvCfjZLwn42S8J+NkvCfjZLwn42S"
2660                .parse::<B64>()?
2661                .check_len(24..25)
2662                .is_ok()
2663        );
2664        assert!(
2665            "ppwthHXW8kXD0f9fE7UPYsOAAu4uj5ORwSomCMxKkz8="
2666                .parse::<B64>()?
2667                .check_len(32..33)
2668                .is_ok()
2669        );
2670        // Padded:
2671        assert_eq!("Mi43MTgyOA==".parse::<B64>()?.as_bytes(), &b"2.71828"[..]);
2672        assert!("Mi43MTgyOA==".parse::<B64>()?.check_len(7..8).is_ok());
2673        assert_eq!("Mg==".parse::<B64>()?.as_bytes(), &b"2"[..]);
2674        assert!("Mg==".parse::<B64>()?.check_len(1..2).is_ok());
2675
2676        // Test parsing failures:
2677        // Invalid character.
2678        assert!("Mi43!!!!!!".parse::<B64>().is_err());
2679        // Invalid last character.
2680        assert!("Mi".parse::<B64>().is_err());
2681        assert!(
2682            "ppwthHXW8kXD0f9fE7UPYsOAAu4uj5ORwSomCMxaaaa"
2683                .parse::<B64>()
2684                .is_err()
2685        );
2686        // Invalid length.
2687        assert!("Mi43MTgyOA".parse::<B64>()?.check_len(8..).is_err());
2688        Ok(())
2689    }
2690
2691    #[test]
2692    fn base64_lengths() -> Result<()> {
2693        assert_eq!("".parse::<B64>()?.as_bytes(), b"");
2694        assert!("=".parse::<B64>().is_err());
2695        assert!("==".parse::<B64>().is_err());
2696        assert!("B".parse::<B64>().is_err());
2697        assert!("B=".parse::<B64>().is_err());
2698        assert!("B==".parse::<B64>().is_err());
2699        assert!("Bg=".parse::<B64>().is_err());
2700        assert_eq!("Bg".parse::<B64>()?.as_bytes(), b"\x06");
2701        assert_eq!("Bg==".parse::<B64>()?.as_bytes(), b"\x06");
2702        assert_eq!("BCg".parse::<B64>()?.as_bytes(), b"\x04\x28");
2703        assert_eq!("BCg=".parse::<B64>()?.as_bytes(), b"\x04\x28");
2704        assert!("BCg==".parse::<B64>().is_err());
2705        assert_eq!("BCDE".parse::<B64>()?.as_bytes(), b"\x04\x20\xc4");
2706        assert!("BCDE=".parse::<B64>().is_err());
2707        assert!("BCDE==".parse::<B64>().is_err());
2708        Ok(())
2709    }
2710
2711    #[test]
2712    fn base64_rev() {
2713        use base64ct::{Base64, Base64Unpadded};
2714
2715        // Check that strings that we accept are precisely ones which
2716        // can be generated by either Base64 or Base64Unpadded
2717        for n in 0..=5 {
2718            for c_vec in std::iter::repeat_n("ACEQg/=".chars(), n).multi_cartesian_product() {
2719                let s: String = c_vec.into_iter().collect();
2720                #[allow(clippy::print_stderr)]
2721                let b = match s.parse::<B64>() {
2722                    Ok(b) => {
2723                        eprintln!("{:10} {:?}", s, b.as_bytes());
2724                        b
2725                    }
2726                    Err(_) => {
2727                        eprintln!("{:10} Err", s);
2728                        continue;
2729                    }
2730                };
2731                let b = b.as_bytes();
2732
2733                let ep = Base64::encode_string(b);
2734                let eu = Base64Unpadded::encode_string(b);
2735
2736                assert!(
2737                    s == ep || s == eu,
2738                    "{:?} decoded to {:?} giving neither {:?} nor {:?}",
2739                    s,
2740                    b,
2741                    ep,
2742                    eu
2743                );
2744            }
2745        }
2746    }
2747
2748    #[test]
2749    fn base16() -> anyhow::Result<()> {
2750        let chk = |s: &str, b: &[u8]| -> anyhow::Result<()> {
2751            let parsed = s.parse::<B16>()?;
2752            assert_eq!(parsed.as_bytes(), b, "{s:?}");
2753            assert_eq!(parsed.to_string(), s.to_ascii_lowercase());
2754
2755            let parsed = s.parse::<B16U>()?;
2756            assert_eq!(parsed.as_bytes(), b, "{s:?}");
2757            assert_eq!(parsed.to_string(), s.to_ascii_uppercase());
2758            Ok(())
2759        };
2760
2761        chk("332e313432", b"3.142")?;
2762        chk("332E313432", b"3.142")?;
2763        chk("332E3134", b"3.14")?;
2764
2765        assert!("332E313".parse::<B16>().is_err());
2766        assert!("332G3134".parse::<B16>().is_err());
2767        Ok(())
2768    }
2769
2770    #[test]
2771    fn curve25519() -> Result<()> {
2772        use tor_llcrypto::pk::curve25519::PublicKey;
2773        let k1 = "ppwthHXW8kXD0f9fE7UPYsOAAu4uj5ORwSomCMxKkz8=";
2774        let k2 = hex::decode("a69c2d8475d6f245c3d1ff5f13b50f62c38002ee2e8f9391c12a2608cc4a933f")
2775            .unwrap();
2776        let k2: &[u8; 32] = &k2[..].try_into().unwrap();
2777
2778        let k1: PublicKey = k1.parse::<Curve25519Public>()?.into();
2779        assert_eq!(k1, (*k2).into());
2780
2781        assert!(
2782            "ppwthHXW8kXD0f9fE7UPYsOAAu4uj5ORwSomCMxKkz"
2783                .parse::<Curve25519Public>()
2784                .is_err()
2785        );
2786        assert!(
2787            "ppwthHXW8kXD0f9fE7UPYsOAAu4uj5ORSomCMxKkz"
2788                .parse::<Curve25519Public>()
2789                .is_err()
2790        );
2791        assert!(
2792            "ppwthHXW8kXD0f9fE7UPYsOAAu4uj5wSomCMxKkz"
2793                .parse::<Curve25519Public>()
2794                .is_err()
2795        );
2796        assert!(
2797            "ppwthHXW8kXD0f9fE7UPYsOAAu4ORwSomCMxKkz"
2798                .parse::<Curve25519Public>()
2799                .is_err()
2800        );
2801
2802        Ok(())
2803    }
2804
2805    #[test]
2806    fn ed25519() -> Result<()> {
2807        use tor_llcrypto::pk::ed25519::Ed25519Identity;
2808        let k1 = "WVIPQ8oArAqLY4XzkcpIOI6U8KsUJHBQhG8SC57qru0";
2809        let k2 = hex::decode("59520f43ca00ac0a8b6385f391ca48388e94f0ab14247050846f120b9eeaaeed")
2810            .unwrap();
2811
2812        let k1: Ed25519Identity = k1.parse::<Ed25519Public>()?.into();
2813        assert_eq!(k1, Ed25519Identity::from_bytes(&k2).unwrap());
2814
2815        assert!(
2816            "WVIPQ8oArAqLY4Xzk0!!!!8KsUJHBQhG8SC57qru"
2817                .parse::<Ed25519Public>()
2818                .is_err()
2819        );
2820        assert!(
2821            "WVIPQ8oArAqLY4XzkcpIU8KsUJHBQhG8SC57qru"
2822                .parse::<Ed25519Public>()
2823                .is_err()
2824        );
2825        assert!(
2826            "WVIPQ8oArAqLY4XzkcpIU8KsUJHBQhG8SC57qr"
2827                .parse::<Ed25519Public>()
2828                .is_err()
2829        );
2830        // right length, bad key:
2831        assert!(
2832            "ppwthHXW8kXD0f9fE7UPYsOAAu4uj5ORwSomCMxaaaa"
2833                .parse::<Curve25519Public>()
2834                .is_err()
2835        );
2836        Ok(())
2837    }
2838
2839    #[test]
2840    fn time() -> Result<()> {
2841        use humantime::parse_rfc3339;
2842        use std::time::SystemTime;
2843
2844        let t = "2020-09-29 13:36:33".parse::<Iso8601TimeSp>()?;
2845        let t: SystemTime = t.into();
2846        assert_eq!(t, parse_rfc3339("2020-09-29T13:36:33Z").unwrap());
2847
2848        assert!("2020-FF-29 13:36:33".parse::<Iso8601TimeSp>().is_err());
2849        assert!("2020-09-29Q13:99:33".parse::<Iso8601TimeSp>().is_err());
2850        assert!("2020-09-29".parse::<Iso8601TimeSp>().is_err());
2851        assert!("too bad, waluigi time".parse::<Iso8601TimeSp>().is_err());
2852
2853        assert_eq!(
2854            "2020-09-29 13:36:33",
2855            "2020-09-29 13:36:33".parse::<Iso8601TimeSp>()?.to_string()
2856        );
2857
2858        let t = "2020-09-29T13:36:33".parse::<Iso8601TimeNoSp>()?;
2859        let t: SystemTime = t.into();
2860        assert_eq!(t, parse_rfc3339("2020-09-29T13:36:33Z").unwrap());
2861
2862        assert!("2020-09-29 13:36:33".parse::<Iso8601TimeNoSp>().is_err());
2863        assert!("2020-09-29Q13:99:33".parse::<Iso8601TimeNoSp>().is_err());
2864        assert!("2020-09-29".parse::<Iso8601TimeNoSp>().is_err());
2865        assert!("too bad, waluigi time".parse::<Iso8601TimeNoSp>().is_err());
2866
2867        assert_eq!(
2868            "2020-09-29T13:36:33",
2869            "2020-09-29T13:36:33"
2870                .parse::<Iso8601TimeNoSp>()?
2871                .to_string()
2872        );
2873
2874        Ok(())
2875    }
2876
2877    #[test]
2878    fn rsa_public_key() {
2879        // Taken from a chutney network.
2880        let key_b64 = r#"
2881        MIIBigKCAYEAsDkzTcKS4kAF56R2ijb9qCek53tKC1EwMdpWMk58bB28fY6kHc55
2882        E7n1hB+LC5neZlx88GKuZ9k8P3g0MlO5ejalcfBdIIm28Nz86JXf/L23YnEpxnG/
2883        IpxZEcmx/EYN+vwp72W3DGuzyntaoaut6lGJk+O/aRCLLcTm4MNznvN1ackK2H6b
2884        Xm2ejRwtVRLoPKODJiPGl43snCfXXWsMH3IALFOgm0szPLv2fAJzBI8VWrUN81M/
2885        lgwJhG6+xbr1CkrXI5fKs/TNr0B0ydC9BIZplmPrnXaeNklnw1cqUJ1oxDSgBrvx
2886        rpDo7paObjSPV26opa68QKGa7Gu2MZQC3RzViNCbawka/108g6hSUkoM+Om2oivr
2887        DvtMOs10MjsfibEBVnwEhqnlb/gj3hJkYoGRsCwAyMIaMObHcmAevMJRWAjGCc8T
2888        GMS9dSmg1IZst+U+V2OCcIHXT6wZ1zPsBM0pYKVLCwtewaq1306k0n+ekriEo7eI
2889        FS3Dd/Dx/a6jAgMBAAE=
2890        "#;
2891        let key_bytes = base64_decode_ignore_ws(key_b64).unwrap();
2892        let rsa = RsaPublicParse1Helper::from_vec(key_bytes, Pos::None).unwrap();
2893
2894        let bits = tor_llcrypto::pk::rsa::PublicKey::from(rsa.clone()).bits();
2895        assert_eq!(bits, 3072);
2896
2897        // tests on a valid key
2898        assert!(rsa.clone().check_exponent(65537).is_ok());
2899        assert!(rsa.clone().check_exponent(1337).is_err());
2900        assert!(rsa.clone().check_len_eq(3072).is_ok());
2901        assert!(rsa.clone().check_len(1024..=4096).is_ok());
2902        assert!(rsa.clone().check_len(1024..=1024).is_err());
2903        assert!(rsa.check_len(4096..).is_err());
2904
2905        // A string of bytes that is not an RSA key.
2906        let failure = RsaPublicParse1Helper::from_vec(vec![1, 2, 3], Pos::None);
2907        assert!(failure.is_err());
2908    }
2909
2910    #[test]
2911    fn ed_cert() {
2912        use tor_llcrypto::pk::ed25519::Ed25519Identity;
2913
2914        // From a chutney network.
2915        let cert_b64 = r#"
2916        AQQABwRNAR6m3kq5h8i3wwac+Ti293opoOP8RKGP9MT0WD4Bbz7YAQAgBACGCdys
2917        G7AwsoYMIKenDN6In6ReiGF8jaYoGqmWKDVBdGGMDIZyNIq+VdhgtAB1EyNFHJU1
2918        jGM0ir9dackL+PIsHbzJH8s/P/8RfUsKIL6/ZHbn3nKMxLH/8kjtxp5ScAA=
2919        "#;
2920        let cert_bytes = base64_decode_ignore_ws(cert_b64).unwrap();
2921        // From the cert above.
2922        let right_subject_key: Ed25519Identity = "HqbeSrmHyLfDBpz5OLb3eimg4/xEoY/0xPRYPgFvPtg"
2923            .parse::<Ed25519Public>()
2924            .unwrap()
2925            .into();
2926        // From `ed25519()` test above.
2927        let wrong_subject_key: Ed25519Identity = "WVIPQ8oArAqLY4XzkcpIOI6U8KsUJHBQhG8SC57qru0"
2928            .parse::<Ed25519Public>()
2929            .unwrap()
2930            .into();
2931
2932        // decode and check correct type and key
2933        let cert = UnvalidatedEdCert::from_vec(cert_bytes, Pos::None)
2934            .unwrap()
2935            .check_cert_type(tor_cert::CertType::IDENTITY_V_SIGNING)
2936            .unwrap()
2937            .check_subject_key_is(&right_subject_key)
2938            .unwrap();
2939        // check wrong type.
2940        assert!(
2941            cert.clone()
2942                .check_cert_type(tor_cert::CertType::RSA_ID_X509)
2943                .is_err()
2944        );
2945        // check wrong key.
2946        assert!(cert.check_subject_key_is(&wrong_subject_key).is_err());
2947
2948        // Try an invalid object that isn't a certificate.
2949        let failure = UnvalidatedEdCert::from_vec(vec![1, 2, 3], Pos::None);
2950        assert!(failure.is_err());
2951    }
2952
2953    #[test]
2954    fn fingerprint() -> Result<()> {
2955        use tor_llcrypto::pk::rsa::RsaIdentity;
2956        let fp1 = "7467 A97D 19CD 2B4F 2BC0 388A A99C 5E67 710F 847E";
2957        let fp2 = "7467A97D19CD2B4F2BC0388AA99C5E67710F847E";
2958        let fp3 = "$7467A97D19CD2B4F2BC0388AA99C5E67710F847E";
2959        let fp4 = "$7467A97D19CD2B4F2BC0388AA99C5E67710F847E=fred";
2960
2961        let k = hex::decode(fp2).unwrap();
2962        let k = RsaIdentity::from_bytes(&k[..]).unwrap();
2963
2964        assert_eq!(RsaIdentity::from(fp1.parse::<SpFingerprint>()?), k);
2965        assert_eq!(RsaIdentity::from(fp2.parse::<SpFingerprint>()?), k);
2966        assert!(fp3.parse::<SpFingerprint>().is_err());
2967        assert!(fp4.parse::<SpFingerprint>().is_err());
2968
2969        assert!(fp1.parse::<Fingerprint>().is_err());
2970        assert_eq!(RsaIdentity::from(fp2.parse::<Fingerprint>()?), k);
2971        assert!(fp3.parse::<Fingerprint>().is_err());
2972        assert!(fp4.parse::<Fingerprint>().is_err());
2973        assert_eq!(Fingerprint(k).to_string(), fp2);
2974
2975        assert!(fp1.parse::<LongIdent>().is_err());
2976        assert_eq!(RsaIdentity::from(fp2.parse::<LongIdent>()?), k);
2977        assert_eq!(RsaIdentity::from(fp3.parse::<LongIdent>()?), k);
2978        assert_eq!(RsaIdentity::from(fp4.parse::<LongIdent>()?), k);
2979
2980        assert!("xxxx".parse::<Fingerprint>().is_err());
2981        assert!("ffffffffff".parse::<Fingerprint>().is_err());
2982
2983        let fp_b64 = "dGepfRnNK08rwDiKqZxeZ3EPhH4";
2984        assert_eq!(RsaIdentity::from(fp_b64.parse::<Base64Fingerprint>()?), k);
2985        assert_eq!(Base64Fingerprint(k).to_string(), fp_b64);
2986
2987        Ok(())
2988    }
2989
2990    #[test]
2991    fn nickname() -> anyhow::Result<()> {
2992        let n: Nickname = "Foo".parse()?;
2993        assert_eq!(n.as_str(), "Foo");
2994        assert_eq!(n.to_string(), "Foo");
2995
2996        let word = "Untr1gonometr1cally";
2997        assert_eq!(word.len(), 19);
2998        let long: Nickname = word.parse()?;
2999        assert_eq!(long.as_str(), word);
3000
3001        let too_long = "abcdefghijklmnopqrstuvwxyz";
3002        let not_ascii = "Eyjafjallajökull";
3003        let too_short = "";
3004        let other_invalid = "contains space";
3005        assert!(not_ascii.len() <= 19);
3006        assert!(too_long.parse::<Nickname>().is_err());
3007        assert!(not_ascii.parse::<Nickname>().is_err());
3008        assert!(too_short.parse::<Nickname>().is_err());
3009        assert!(other_invalid.parse::<Nickname>().is_err());
3010
3011        Ok(())
3012    }
3013
3014    /// Test for both `Hostname` and `InternetHost`
3015    #[test]
3016    fn hostname() {
3017        use std::net::IpAddr;
3018
3019        // Test a string that we should treat as a valid hostname.
3020        let chk_name = |s: &str| {
3021            let n: Hostname = s.parse().expect(s);
3022            assert_eq!(n.as_str(), s);
3023            assert_eq!(n.to_string(), s);
3024            assert_eq!(s.parse::<InternetHost>().expect(s), InternetHost::Name(n));
3025        };
3026
3027        // Test a string that looks like it could be an address or a hostname.
3028        // We parse those as addresses.
3029        let chk_either = |s: &str| {
3030            let h: InternetHost = s.parse().expect(s);
3031            let a: IpAddr = s.parse().expect(s);
3032            assert_eq!(h, InternetHost::IpAddr(a), "{s:?}");
3033            assert_eq!(h.to_string(), a.to_string(), "{s:?}");
3034        };
3035
3036        // Test a string that's an address, and isn't a valid hostname.
3037        let chk_addr = |s: &str| {
3038            let _: InvalidHostname = s.parse::<Hostname>().expect_err(s);
3039            chk_either(s);
3040        };
3041
3042        // Test a string that we should reject.
3043        let chk_bad = |s: &str| {
3044            let _: InvalidHostname = s.parse::<Hostname>().expect_err(s);
3045            let _: InvalidInternetHost = s.parse::<InternetHost>().expect_err(s);
3046        };
3047
3048        chk_name("foo.bar");
3049        chk_name("localhost");
3050        chk_name("tor.invalid");
3051        chk_name("example.com");
3052
3053        // Unarguably invalid.
3054        chk_bad("");
3055        chk_bad("foo bar");
3056        chk_bad("foo..bar");
3057        chk_bad("foo.-bar");
3058        chk_bad(" foo.bar ");
3059        chk_bad("[::1]");
3060
3061        // Strings that some IP address parsers accept as addresses,
3062        // but which are also valid hostnames according to RFC1123.
3063        //
3064        // We reject them rather than processing of them as hostnames,
3065        // exposing downstream software to possible strangeness.
3066        chk_bad("1");
3067        chk_bad("127.0.0.023");
3068
3069        // No-one thinks this is a valid IP address but we reject it as a hostname too,
3070        // even though it's syntactically legal per RFC1123, because it's quite bad.
3071        chk_bad("1.2.3.4.5");
3072
3073        chk_either("0.0.0.0");
3074        chk_either("127.0.0.1");
3075        chk_addr("::");
3076        chk_addr("::1");
3077        chk_addr("2001:0db8:85a3:0000:0000:8a2e:0370:7334");
3078        chk_addr("::ffff:192.0.2.3"); // IPv6-mapped IPv4 address
3079    }
3080
3081    #[test]
3082    fn contact_info() -> anyhow::Result<()> {
3083        use parse2::{ParseInput, parse_netdoc};
3084
3085        const S: &str = "some relay operator";
3086        let n: ContactInfo = S.parse()?;
3087        assert_eq!(n.as_str(), S);
3088        assert_eq!(n.to_string(), S);
3089
3090        let bad = |s: &str| {
3091            let _: InvalidContactInfo = s.parse::<ContactInfo>().unwrap_err();
3092        };
3093
3094        bad(" starts with space");
3095        bad("contains\nnewline");
3096
3097        #[derive(PartialEq, Debug, Deftly)]
3098        #[derive_deftly(NetdocParseable, NetdocEncodable)]
3099        struct TestDoc {
3100            pub intro: (),
3101            pub contact: ContactInfo,
3102        }
3103
3104        let roundtrip = |s: &str| -> anyhow::Result<()> {
3105            let doc = TestDoc {
3106                intro: (),
3107                contact: s.parse()?,
3108            };
3109            let enc = encode_netdoc_unsigned([&doc])?;
3110            let reparsed = parse_netdoc::<TestDoc>(&ParseInput::new(&enc, "<test>"))?;
3111            assert_eq!(doc, reparsed);
3112            Ok(())
3113        };
3114
3115        roundtrip("normal")?;
3116        roundtrip("trailing  white space  ")?;
3117        roundtrip("wtf is this allowed in \x03 netdocs\r")?; // TODO torspec#396
3118
3119        Ok(())
3120    }
3121
3122    /// Round trip test for [`NumericBoolean`] ensuring that `0` is false,
3123    /// `1` is true, and other things fail.
3124    #[test]
3125    fn numeric_boolean() {
3126        let chk = |s: &str| {
3127            assert_eq!(NumericBoolean::from_str(s).expect(s).to_string(), s);
3128        };
3129        chk("0");
3130        chk("1");
3131        // Testing this because it is not a u8.
3132        assert!(NumericBoolean::from_str("10000").is_err());
3133    }
3134
3135    #[test]
3136    fn f64_finite() {
3137        let normalise_string = |i: &str, o: &str| {
3138            let v: F64Finite = i.parse().expect(i);
3139            assert_eq!(v.to_string(), o, "i={i:?}");
3140        };
3141        let roundtrip_string = |s: &str| normalise_string(s, s);
3142        let roundtrip_value = |i: f64| {
3143            let v: F64Finite = i.try_into().unwrap();
3144            let s = v.to_string();
3145            let o: F64Finite = s.parse().expect(&s);
3146            assert_eq!(v, o, "{i:?} {s}");
3147            assert_eq!(v.to_bits(), o.to_bits(), "{i:?} {s}");
3148        };
3149        let error_string = |s: &str| {
3150            let _: F64FiniteParseError = s.parse::<F64Finite>().expect_err(s);
3151        };
3152
3153        roundtrip_string("0");
3154        roundtrip_string("0.5");
3155        roundtrip_string("1");
3156        roundtrip_string("42");
3157        roundtrip_string("9007199254740991"); // f64::MAX_EXACT_INTEGER (as per Rust 1.96.0)
3158        normalise_string("1e3", "1000");
3159
3160        roundtrip_value(f64::EPSILON);
3161        roundtrip_value(f64::EPSILON + 1.0);
3162        roundtrip_value(f64::MIN);
3163        roundtrip_value(f64::MIN_POSITIVE);
3164        roundtrip_value(-f64::MIN_POSITIVE);
3165        roundtrip_value(f64::MAX);
3166
3167        error_string(&f64::NAN.to_string());
3168        error_string(&f64::INFINITY.to_string());
3169        error_string("");
3170        error_string("garbage");
3171
3172        // TODO torspec#416 these ought to be more reasonable, but this is what it does now:
3173        roundtrip_string(
3174            "0.000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000022250738585072014",
3175        ); // MIN_POSITIVE
3176        roundtrip_string(
3177            "179769313486231570000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
3178        ); // MAX
3179    }
3180
3181    /// Test that ensures SpFingerprint matches the 10x4 requirement.
3182    #[test]
3183    fn sp_fingerprint() {
3184        use derive_deftly::Deftly;
3185        use tor_llcrypto::pk::rsa::RsaIdentity;
3186
3187        use crate::parse2::ErrorProblem;
3188
3189        #[derive(Deftly)]
3190        #[derive_deftly(NetdocParseable, NetdocEncodable)]
3191        struct Wrapper {
3192            #[deftly(netdoc(single_arg))]
3193            fingerprint: SpFingerprint,
3194        }
3195
3196        /// Small helper to parse an [`SpFingerprint`].
3197        ///
3198        /// In the case the parsing went successful, it also performs a
3199        /// round-trip encoding test.
3200        fn parse2(s: &str) -> std::result::Result<SpFingerprint, ErrorProblem> {
3201            use crate::parse2::{self, ParseInput};
3202
3203            let input = format!("fingerprint {s}\n");
3204            let res = parse2::parse_netdoc::<Wrapper>(&ParseInput::new(&input, ""))
3205                .map_err(|x| x.problem)?;
3206
3207            // Round-trip encoding; we only do .starts_with() because input
3208            // may contain trailing parameters which will obviously not be
3209            // encoded; trimming to remove the trailing "\n" afterwards.
3210            let mut enc = NetdocEncoder::default();
3211            res.encode_unsigned(&mut enc).unwrap();
3212            assert!(input.starts_with(enc.finish().unwrap().trim_end()));
3213
3214            Ok(res.fingerprint)
3215        }
3216
3217        // Test a valid one.
3218        assert_eq!(
3219            parse2(&vec!["ABAB"; 10].join(" ")).unwrap(),
3220            SpFingerprint(RsaIdentity::from_bytes(&[0xAB; 20]).unwrap())
3221        );
3222
3223        // Test a valid one with tail.
3224        assert_eq!(
3225            parse2(&vec!["ABAB"; 11].join(" ")).unwrap(),
3226            SpFingerprint(RsaIdentity::from_bytes(&[0xAB; 20]).unwrap())
3227        );
3228
3229        // Missing argument
3230        assert!(matches!(
3231            parse2(&vec!["ABAB"; 9].join(" ")).unwrap_err(),
3232            ErrorProblem::MissingArgument { .. }
3233        ));
3234
3235        // Invalid argument.
3236        // In this case, we have string with a total length of 40 but with
3237        // one pair having 6 characters and another one having 2 as a proof
3238        // of that.
3239        assert!(matches!(
3240            parse2("0000 000000 00 0000 0000 0000 0000 0000 0000 0000").unwrap_err(),
3241            ErrorProblem::InvalidArgument { .. }
3242        ));
3243
3244        // And of course invalid hex should fail too.
3245        assert!(matches!(
3246            parse2(&vec!["ZZZZ"; 10].join(" ")).unwrap_err(),
3247            ErrorProblem::InvalidArgument { .. }
3248        ));
3249    }
3250
3251    /// Verifies the parsing of [`ItemPresent`].
3252    #[test]
3253    fn item_present_parse2() {
3254        #[derive(Default)]
3255        struct Token;
3256
3257        #[derive(Deftly)]
3258        #[derive_deftly(NetdocParseable)]
3259        struct TestDoc {
3260            #[allow(unused)]
3261            intro: Ignored,
3262            foo: Option<ItemPresent<Token>>,
3263        }
3264
3265        // The test cases with their respective result; boolean indicating that
3266        // it was present.
3267        let tests = [
3268            // Test valid present.
3269            ("intro\nfoo\n", Ok(true)),
3270            // Test valid absent.
3271            ("intro\n", Ok(false)),
3272            // Test repeated.
3273            ("intro\nfoo\nfoo\n", Err(ErrorProblem::ItemRepeated)),
3274            // Test repeated with unknown.
3275            ("intro\nbar\nfoo\nfoo\n", Err(ErrorProblem::ItemRepeated)),
3276            // Test with argument.
3277            ("intro\nfoo bar\n", Ok(true)),
3278            // Test with two arguments.
3279            ("intro\nfoo bar baz\n", Ok(true)),
3280            // Test with object.
3281            (
3282                "intro\nfoo\n-----BEGIN RSA PUBLIC KEY-----\n-----END RSA PUBLIC KEY-----\n",
3283                Err(ErrorProblem::ObjectUnexpected),
3284            ),
3285        ];
3286
3287        for (input, expect) in tests {
3288            println!("{input:?}, {expect:?}");
3289
3290            // Convert the result by calling .is_present() and extracting EP.
3291            let got = parse2::parse_netdoc::<TestDoc>(&ParseInput::new(input, ""))
3292                .map(|x| x.foo.is_some())
3293                .map_err(|e| e.problem);
3294            assert_eq!(got, expect);
3295        }
3296    }
3297
3298    #[test]
3299    fn item_present_encode() {
3300        #[derive(Default)]
3301        struct Token;
3302
3303        #[derive(Deftly)]
3304        #[derive_deftly(NetdocEncodable)]
3305        struct TestDoc {
3306            #[allow(unused)]
3307            intro: (),
3308            foo: Option<ItemPresent<Token>>,
3309        }
3310
3311        let tests = [
3312            (Some(ItemPresent(Token)), "intro\nfoo\n"),
3313            (None, "intro\n"),
3314        ];
3315
3316        for (present, output) in tests {
3317            let re_encoded = encode_netdoc_unsigned([&TestDoc {
3318                intro: (),
3319                foo: present,
3320            }])
3321            .unwrap();
3322            assert_eq!(re_encoded, output);
3323        }
3324    }
3325
3326    /// Helper to call methods for edcerts.
3327    trait Ed25519CertTest: Sized + PartialEq + Eq + Debug {
3328        /// Creates a new instance.
3329        ///
3330        /// Used to create a struct in ad-hoc fashion for Eq comparison.
3331        fn new(
3332            signing_key: ed25519::Ed25519Identity,
3333            certified_key: ed25519::Ed25519Identity,
3334        ) -> Self;
3335
3336        /// Returns the expected [`CertType`].
3337        fn cert_type() -> CertType;
3338
3339        /// Calls .new_signed().
3340        ///
3341        /// This method is used to create an [`EmbeddedCert`] with a given
3342        /// signing key and a key that shall be certified.
3343        fn new_signed(
3344            signing_key: &ed25519::Keypair,
3345            certified_key: ed25519::Ed25519Identity,
3346            expiry: SystemTime,
3347        ) -> StdResult<EmbeddedCert<Self, KeyUnknownCert>, Bug>;
3348
3349        /// Calls .verify().
3350        ///
3351        /// The method verifies a certificate given a pre-known certified key,
3352        /// the actual certificate, and a timestamp.
3353        fn verify(
3354            signing_key: Option<ed25519::Ed25519Identity>,
3355            certified_key: ed25519::Ed25519Identity,
3356            cert: KeyUnknownCert,
3357        ) -> StdResult<TimeRangeBound<Self>, VerifyFailed>;
3358    }
3359
3360    impl Ed25519CertTest for Ed25519IdentityCert {
3361        fn new(
3362            signing_key: ed25519::Ed25519Identity,
3363            certified_key: ed25519::Ed25519Identity,
3364        ) -> Self {
3365            Self {
3366                id_ed25519: signing_key,
3367                sign_ed25519: certified_key,
3368            }
3369        }
3370
3371        fn cert_type() -> CertType {
3372            CertType::IDENTITY_V_SIGNING
3373        }
3374
3375        fn new_signed(
3376            signing_key: &ed25519::Keypair,
3377            certified_key: ed25519::Ed25519Identity,
3378            expiry: SystemTime,
3379        ) -> StdResult<EmbeddedCert<Self, KeyUnknownCert>, Bug> {
3380            Self::new_signed(signing_key, certified_key, expiry)
3381        }
3382
3383        fn verify(
3384            _signing_key: Option<ed25519::Ed25519Identity>,
3385            _certified_key: ed25519::Ed25519Identity,
3386            cert: KeyUnknownCert,
3387        ) -> StdResult<TimeRangeBound<Self>, VerifyFailed> {
3388            Self::verify(cert)
3389        }
3390    }
3391
3392    impl Ed25519CertTest for Ed25519FamilyCert {
3393        fn new(
3394            signing_key: ed25519::Ed25519Identity,
3395            _certified_key: ed25519::Ed25519Identity,
3396        ) -> Self {
3397            Self {
3398                family_ed25519: signing_key,
3399            }
3400        }
3401
3402        fn cert_type() -> CertType {
3403            CertType::FAMILY_V_IDENTITY
3404        }
3405
3406        fn new_signed(
3407            signing_key: &ed25519::Keypair,
3408            certified_key: ed25519::Ed25519Identity,
3409            expiry: SystemTime,
3410        ) -> StdResult<EmbeddedCert<Self, KeyUnknownCert>, Bug> {
3411            Self::new_signed(signing_key, certified_key, expiry)
3412        }
3413
3414        fn verify(
3415            _signing_key: Option<ed25519::Ed25519Identity>,
3416            certified_key: ed25519::Ed25519Identity,
3417            cert: KeyUnknownCert,
3418        ) -> StdResult<TimeRangeBound<Self>, VerifyFailed> {
3419            Self::verify(certified_key, cert)
3420        }
3421    }
3422
3423    impl Ed25519CertTest for Ed25519NtorCrossCert {
3424        fn new(
3425            _signing_key: ed25519::Ed25519Identity,
3426            _certified_key: ed25519::Ed25519Identity,
3427        ) -> Self {
3428            Self::dangerous_new_unverified()
3429        }
3430
3431        fn cert_type() -> CertType {
3432            CertType::NTOR_CC_IDENTITY
3433        }
3434
3435        fn new_signed(
3436            signing_key: &ed25519::Keypair,
3437            certified_key: ed25519::Ed25519Identity,
3438            expiry: SystemTime,
3439        ) -> StdResult<EmbeddedCert<Self, KeyUnknownCert>, Bug> {
3440            Self::new_signed(&ExpandedKeypair::from(signing_key), certified_key, expiry)
3441        }
3442
3443        fn verify(
3444            signing_key: Option<ed25519::Ed25519Identity>,
3445            certified_key: ed25519::Ed25519Identity,
3446            cert: KeyUnknownCert,
3447        ) -> StdResult<TimeRangeBound<Self>, VerifyFailed> {
3448            Self::verify(signing_key.unwrap(), certified_key, cert)
3449        }
3450    }
3451
3452    /// Converts from [`Iso8601TimeSp`] to [`SystemTime`]
3453    fn str_to_st(s: &str) -> SystemTime {
3454        Iso8601TimeSp::from_str(s).unwrap().0
3455    }
3456
3457    /// Tests a valid ad-hoc generated certificate.
3458    fn ed25519_cert_rng<T: Ed25519CertTest>() {
3459        let mut rng = testing_rng();
3460        let signing_key = ed25519::Keypair::generate(&mut rng);
3461        let certified_key = ed25519::Keypair::generate(&mut rng);
3462        let now = str_to_st("2000-01-01 06:00:00");
3463        let expiry = str_to_st("2000-01-01 12:00:00");
3464
3465        // Test ad-hoc generation.
3466        let embedded_cert =
3467            T::new_signed(&signing_key, certified_key.public_key().into(), expiry).unwrap();
3468        assert_eq!(
3469            *embedded_cert.get().unwrap(),
3470            T::new(
3471                signing_key.public_key().into(),
3472                certified_key.public_key().into()
3473            )
3474        );
3475
3476        // Verify ad-hoc certificate generation.
3477        let unverified = embedded_cert.raw_unverified().clone();
3478        assert_eq!(T::cert_type(), unverified.peek_cert_type());
3479        match unverified.peek_subject_key() {
3480            CertifiedKey::Ed25519(x) => assert_eq!(
3481                *x,
3482                ed25519::Ed25519Identity::from(certified_key.public_key())
3483            ),
3484            _ => panic!(),
3485        }
3486
3487        // Finally, see if .verify() agrees.
3488        T::verify(
3489            Some(signing_key.public_key().into()),
3490            certified_key.public_key().into(),
3491            unverified.clone(),
3492        )
3493        .unwrap()
3494        .check_valid_at(&now)
3495        .unwrap();
3496
3497        // See if .verify() also agrees when expired but with toleration.
3498        T::verify(
3499            Some(signing_key.public_key().into()),
3500            certified_key.public_key().into(),
3501            unverified,
3502        )
3503        .unwrap()
3504        .extend_end_bound(Duration::from_secs(60 * 60))
3505        .check_valid_at(&now)
3506        .unwrap();
3507    }
3508
3509    /// Tests invalid Ed25519 certificates by violating various constraints.
3510    fn ed25519_cert_invalid<T: Ed25519CertTest + 'static>(requires_signed_with_ext: bool) {
3511        let mut rng = testing_rng();
3512        let now = str_to_st("2000-01-01 06:00:00");
3513        let expiry = str_to_st("2000-01-01 12:00:00");
3514        let signing_key = ed25519::Keypair::generate(&mut rng);
3515        let signing_pk = ed25519::Ed25519Identity::from(signing_key.public_key());
3516        let certified_key = ed25519::Keypair::generate(&mut rng);
3517        let certified_pk = ed25519::Ed25519Identity::from(certified_key.public_key());
3518
3519        let mut tests: Vec<(_, _, CertifiedKey, _, _)> = vec![
3520            // Testing a violation of the signature is hard because the encoder
3521            // refuses to emit such a thing.
3522            // ---
3523            // Violate timestamp.
3524            (
3525                T::cert_type(),
3526                // We achieve this by setting expiry to now - 1 day.
3527                now - Duration::from_secs(64 * 64 * 24),
3528                certified_pk.into(),
3529                Some(&signing_pk),
3530                &signing_key,
3531            ),
3532            // Violate cert type.
3533            (
3534                // Just picking something completely out of place here.
3535                CertType::LINK_AUTH_X509,
3536                expiry,
3537                certified_pk.into(),
3538                Some(&signing_pk),
3539                &signing_key,
3540            ),
3541            // Violate certified key type.
3542            (
3543                T::cert_type(),
3544                expiry,
3545                // Just pass a different CertifiedKey variant here.
3546                CertifiedKey::RsaSha256Digest(certified_pk.into()),
3547                Some(&signing_pk),
3548                &signing_key,
3549            ),
3550            // ---
3551            // Missing test for violating both keys MUST be valid mappings to a
3552            // [`ed25519::PublicKey`].  I was unable to find a single test
3553            // vector for this, even in curve25591-dalek. :/
3554        ];
3555
3556        // Violate absence of `signed-with-ed25519-key`.
3557        // This is not a violation in Ed25519NtorCrossCert.
3558        if requires_signed_with_ext {
3559            tests.push((
3560                T::cert_type(),
3561                expiry,
3562                certified_pk.into(),
3563                None,
3564                &signing_key,
3565            ));
3566        }
3567
3568        for (ctype, expiry, certified_key, signing_key, signing_kp) in tests {
3569            let mut builder = Ed25519Cert::builder()
3570                .cert_type(ctype)
3571                .expiration(expiry)
3572                .cert_key(certified_key.clone())
3573                .clone();
3574            if let Some(signing_key) = signing_key {
3575                builder = builder.signing_key(*signing_key).clone();
3576            }
3577            let cert = Ed25519Cert::decode(&builder.encode_and_sign(signing_kp).unwrap()).unwrap();
3578
3579            // We purposely always create an Ed25519Identity here from the bytes
3580            // in order to make it possible to test for invalid certified
3581            // key types.
3582            T::verify(
3583                signing_key.copied(),
3584                Ed25519Identity::from_bytes(certified_key.as_bytes()).unwrap(),
3585                cert,
3586            )
3587            .and_then(|expired| expired.check_valid_at(&now).map_err(|e| e.into()))
3588            .unwrap_err();
3589        }
3590    }
3591
3592    #[test]
3593    fn ed25519_cert_rng_test() {
3594        ed25519_cert_rng::<Ed25519IdentityCert>();
3595        ed25519_cert_rng::<Ed25519FamilyCert>();
3596        ed25519_cert_rng::<Ed25519NtorCrossCert>();
3597    }
3598
3599    #[test]
3600    fn ed25519_cert_invalid_test() {
3601        ed25519_cert_invalid::<Ed25519IdentityCert>(true);
3602        ed25519_cert_invalid::<Ed25519FamilyCert>(true);
3603        ed25519_cert_invalid::<Ed25519NtorCrossCert>(false);
3604    }
3605}