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
//!
6
//! These types shouldn't be exposed outside of the netdoc crate.
7

            
8
pub use b16impl::*;
9
pub use b64impl::*;
10
pub use contact_info::*;
11
pub use curve25519impl::*;
12
pub use ed25519impl::*;
13
#[cfg(any(feature = "routerdesc", feature = "hs-common"))]
14
pub(crate) use edcert::*;
15
pub use fingerprint::*;
16
pub use hostname::*;
17
pub use rsa::*;
18
pub use timeimpl::*;
19

            
20
pub use nickname::{InvalidNickname, Nickname};
21

            
22
pub use boolean::NumericBoolean;
23

            
24
pub use fingerprint::{Base64Fingerprint, Fingerprint};
25

            
26
pub use identified_digest::{DigestName, IdentifiedDigest};
27

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

            
30
use crate::NormalItemArgument;
31
use 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
};
41
use crate::parse2::{
42
    self, ArgumentError, ArgumentStream, ItemArgumentParseable, ItemObjectParseable,
43
    ItemValueParseable, SignatureHashInputs, SignatureItemParseable, UnparsedItem,
44
    multiplicity::{
45
        ItemSetMethods,
46
        // `P2` for "parse2`; different from `encode::MultiplicitySelector`
47
        MultiplicitySelector as P2MultiplicitySelector,
48
        ObjectSetMethods,
49
    },
50
    sig_hashes::Sha1WholeKeywordLine,
51
};
52

            
53
use derive_deftly::{Deftly, define_derive_deftly, define_derive_deftly_module};
54
use digest::Digest as _;
55
use educe::Educe;
56
use std::cmp::{self, PartialOrd};
57
use std::fmt::{self, Display};
58
use std::iter;
59
use std::marker::PhantomData;
60
use std::ops::{Deref, DerefMut};
61
use std::result::Result as StdResult;
62
use std::str::FromStr;
63
use subtle::{Choice, ConstantTimeEq};
64
use tor_error::{Bug, ErrorReport as _, internal, into_internal};
65
use void::{ResultVoidExt as _, Void};
66

            
67
/// Describes a value that van be decoded from a bunch of bytes.
68
///
69
/// Used for decoding the objects between BEGIN and END tags.
70
pub(crate) trait FromBytes: Sized {
71
    /// Try to parse a value of this type from a byte slice
72
    fn from_bytes(b: &[u8], p: crate::Pos) -> crate::Result<Self>;
73
    /// Try to parse a value of this type from a vector of bytes,
74
    /// and consume that value
75
5300
    fn from_vec(v: Vec<u8>, p: crate::Pos) -> crate::Result<Self> {
76
5300
        Self::from_bytes(&v[..], p)
77
5300
    }
78
}
79

            
80
define_derive_deftly_module! {
81
    /// Implement conversion traits for a transparent newtype around bytes - shared code
82
    ///
83
    /// This is precisely `#[derive_deftly(Transparent)]`, but in the form of a deftly module,
84
    /// so that other derives (eg `BytesTransparent`) can re-use it.
85
    Transparent beta_deftly:
86

            
87
    // Expands to bullet points for "generated code", except omitting
88
    // `AsRef` & `AsMut` because some uses sites have additional impls of those,
89
    // which are best presented together in the docs.
90
  ${define TRANSPARENT_DOCS_IMPLS {
91
    ///  * impls of `Deref`, `DerefMut`
92
    ///  * impls of `From<field>` and "`Into`" (technically, `From<Self> for field`)
93
  }}
94

            
95
    // Expands to the implementations
96
  ${define TRANSPARENT_IMPLS {
97

            
98
  ${for fields {
99
    ${loop_exactly_1 "must be applied to a single-field struct"}
100

            
101
    impl<$tgens> From<$ftype> for $ttype {
102
520727
        fn from($fpatname: $ftype) -> $ttype {
103
            $vpat
104
        }
105
    }
106

            
107
    impl<$tgens> From<$ttype> for $ftype {
108
21714
        fn from(self_: $ttype) -> $ftype {
109
            self_.$fname
110
        }
111
    }
112

            
113
    impl<$tgens> Deref for $ttype {
114
        type Target = $ftype;
115
250944527
        fn deref(&self) -> &$ftype {
116
            &self.$fname
117
        }
118
    }
119

            
120
    impl<$tgens> DerefMut for $ttype {
121
2
        fn deref_mut(&mut self) -> &mut $ftype {
122
            &mut self.$fname
123
        }
124
    }
125

            
126
    impl<$tgens> AsRef<$ftype> for $ttype {
127
        fn as_ref(&self) -> &$ftype {
128
            &self.$fname
129
        }
130
    }
131

            
132
    impl<$tgens> AsMut<$ftype> for $ttype {
133
        fn as_mut(&mut self) -> &mut $ftype {
134
            &mut self.$fname
135
        }
136
    }
137
  }}
138
  }}
139
}
140

            
141
define_derive_deftly! {
142
    use Transparent;
143

            
144
    /// Implement conversion traits for an arbitrary transparent newtype
145
    ///
146
    /// # Requirements
147
    ///
148
    ///  * Self should be a single-field struct
149
    ///  * Self should have no runtime invariants
150
    ///
151
    /// # Generated code
152
    ///
153
    $TRANSPARENT_DOCS_IMPLS
154
    ///  * impls of `AsMut<field>`, `AsRef<field>`
155
    ///
156
    /// # Guidelines
157
    ///
158
    ///  * the field should be `pub`, with `#[allow(clippy::exhaustive_structs)]`
159
    ///  * derive `Hash`, `Debug` and (usually) `Clone`
160
    ///  * consider deriving `PartialEq` and `Eq`
161
    ///    but for types containing bytes, use [`ConstantTimeEq`],
162
    ///    eg with [`#[derive_deftly(BytesTransparent)]`](derive_deftly_template_BytesTransparent)
163
    ///    (instead of `Transparent`).
164
    ///  * implement `FromStr`, `Display`, `NormalItemArgument`, as required
165
    Transparent for struct, beta_deftly:
166

            
167
    $TRANSPARENT_IMPLS
168
}
169

            
170
define_derive_deftly! {
171
    use Transparent;
172

            
173
    /// Implement `ConstantTimeEq`, `.as_bytes()`, etc., for a transparent newtype around bytes
174
    ///
175
    /// # Requirements
176
    ///
177
    ///  * Self should be a single-field struct
178
    ///  * Self should deref to `&[u8]` (and to `&mut [u8]`).
179
    ///  * (so Self should have no runtime invariants)
180
    ///
181
    /// # Generated code
182
    ///
183
    ///  * impls of `ConstantTimeEq`, `Eq`, `PartialEq`
184
    ///  * `as_bytes()` method
185
    ${TRANSPARENT_DOCS_IMPLS}
186
    ///  * impls of `AsMut<field>`, `AsRef<field>`, `AsRef<[u8]>`, `AsMut<[u8]>`
187
    ///
188
    // We could derive Debug here but then we have to deal with the Fixed's N
189
    // which gets quite fiddly.
190
    //
191
    /// # Guidelines
192
    ///
193
    ///  * derive `Hash` and write `#[allow(clippy::derived_hash_with_manual_eq)]`
194
    ///  * impl `FromStr` and `Display` (if required, which they usually will be)
195
    ///  * derive `derive_more::Debug` eg with `#[debug(r#"B64("{self}")"#)]`
196
    ///  * `impl NormalItemArgument` if appropriate (ie the representation has no spaces)
197
    BytesTransparent for struct, beta_deftly:
198

            
199
    $TRANSPARENT_IMPLS
200

            
201
    impl<$tgens> ConstantTimeEq for $ttype {
202
        fn ct_eq(&self, other: &$ttype) -> Choice {
203
          $(
204
            self.$fname.ct_eq(&other.$fname)
205
          )
206
        }
207
    }
208
    $/// `$tname` is `Eq` via its constant-time implementation.
209
    impl<$tgens> PartialEq for $ttype {
210
        fn eq(&self, other: &$ttype) -> bool {
211
            self.ct_eq(other).into()
212
        }
213
    }
214
    impl<$tgens> Eq for $ttype {}
215

            
216
    impl<$tgens> $ttype {
217
        /// Return the byte array from this object.
218
12417
        pub fn as_bytes(&self) -> &[u8] {
219
          $(
220
12417
            &self.$fname[..]
221
          )
222
12417
        }
223
    }
224

            
225
    impl<$tgens> AsRef<[u8]> for $ttype {
226
        fn as_ref(&self) -> &[u8] {
227
          $(
228
            self.$fname.as_ref()
229
          )
230
        }
231
    }
232

            
233
    impl<$tgens> AsMut<[u8]> for $ttype {
234
        fn as_mut(&mut self) -> &mut [u8] {
235
          $(
236
            self.$fname.as_mut()
237
          )
238
        }
239
    }
240
}
241

            
242
/// Types for decoding base64-encoded values.
243
mod b64impl {
244
    use super::*;
245
    use crate::{Error, NetdocErrorKind as EK, Pos, Result};
246
    use base64ct::{Base64, Base64Unpadded, Encoding};
247
    use std::ops::RangeBounds;
248

            
249
    /// A byte array, encoded in base64 with optional padding.
250
    ///
251
    /// On output (`Display`), output is unpadded.
252
    #[derive(Clone, Hash, Deftly)]
253
    #[derive_deftly(BytesTransparent)]
254
    #[allow(clippy::derived_hash_with_manual_eq)]
255
    #[derive(derive_more::Debug)]
256
    #[debug(r#"B64("{self}")"#)]
257
    #[allow(clippy::exhaustive_structs)]
258
    pub struct B64(pub Vec<u8>);
259

            
260
    impl FromStr for B64 {
261
        type Err = Error;
262
74869
        fn from_str(s: &str) -> Result<Self> {
263
74869
            let v: core::result::Result<Vec<u8>, base64ct::Error> = match s.len() % 4 {
264
11206
                0 => Base64::decode_vec(s),
265
63663
                _ => Base64Unpadded::decode_vec(s),
266
            };
267
92876
            let v = v.map_err(|_| {
268
36014
                EK::BadArgument
269
36014
                    .with_msg("Invalid base64")
270
36014
                    .at_pos(Pos::at(s))
271
54021
            })?;
272
38855
            Ok(B64(v))
273
74869
        }
274
    }
275

            
276
    impl Display for B64 {
277
22
        fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
278
22
            Display::fmt(&Base64Unpadded::encode_string(&self.0), f)
279
22
        }
280
    }
281

            
282
    impl B64 {
283
        /// Return this object if its length is within the provided bounds
284
        /// object, or an error otherwise.
285
2086
        pub(crate) fn check_len<B: RangeBounds<usize>>(self, bounds: B) -> Result<Self> {
286
2086
            if bounds.contains(&self.0.len()) {
287
2084
                Ok(self)
288
            } else {
289
2
                Err(EK::BadObjectVal.with_msg("Invalid length on base64 data"))
290
            }
291
2086
        }
292

            
293
        /// Try to convert this object into an array of N bytes.
294
        ///
295
        /// Return an error if the length is wrong.
296
24276
        pub(crate) fn into_array<const N: usize>(self) -> Result<[u8; N]> {
297
24276
            self.0
298
24276
                .try_into()
299
24276
                .map_err(|_| EK::BadObjectVal.with_msg("Invalid length on base64 data"))
300
24276
        }
301
    }
302

            
303
    impl FromIterator<u8> for B64 {
304
        fn from_iter<T: IntoIterator<Item = u8>>(iter: T) -> Self {
305
            Self(iter.into_iter().collect())
306
        }
307
    }
308

            
309
    impl NormalItemArgument for B64 {}
310

            
311
    /// A byte array encoded in a hexadecimal with a fixed length.
312
    #[derive(Clone, Hash, Deftly)]
313
    #[derive_deftly(BytesTransparent)]
314
    #[allow(clippy::derived_hash_with_manual_eq)]
315
    #[derive(derive_more::Debug)]
316
    #[debug(r#"FixedB64::<{N}>("{self}")"#)]
317
    #[allow(clippy::exhaustive_structs)]
318
    pub struct FixedB64<const N: usize>(pub [u8; N]);
319

            
320
    impl<const N: usize> Display for FixedB64<N> {
321
2
        fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
322
2
            Display::fmt(&B64(self.0.to_vec()), f)
323
2
        }
324
    }
325

            
326
    impl<const N: usize> FromStr for FixedB64<N> {
327
        type Err = Error;
328
5444
        fn from_str(s: &str) -> Result<Self> {
329
5444
            Ok(Self(B64::from_str(s)?.0.try_into().map_err(|_| {
330
2
                EK::BadArgument
331
2
                    .at_pos(Pos::at(s))
332
2
                    .with_msg("invalid length")
333
2
            })?))
334
5444
        }
335
    }
336

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

            
340
// ============================================================
341

            
342
/// Types for decoding hex-encoded values.
343
mod b16impl {
344
    use super::*;
345
    use crate::{Error, NetdocErrorKind as EK, Pos, Result};
346

            
347
    /// A byte array encoded in hexadecimal; prints in lowercase
348
    ///
349
    /// Both uppercase and lowercase are tolerated when parsing.
350
    #[derive(Clone, Hash, Deftly)]
351
    #[derive_deftly(BytesTransparent)]
352
    #[allow(clippy::derived_hash_with_manual_eq)]
353
    #[derive(derive_more::Debug)]
354
    #[debug(r#"B16("{self}")"#)]
355
    #[allow(clippy::exhaustive_structs)]
356
    pub struct B16(pub Vec<u8>);
357

            
358
    /// A byte array encoded in hexadecimal; prints in uppercase
359
    ///
360
    /// Both uppercase and lowercase are tolerated when parsing.
361
    #[derive(Clone, Hash, Deftly)]
362
    #[derive_deftly(BytesTransparent)]
363
    #[allow(clippy::derived_hash_with_manual_eq)]
364
    #[derive(derive_more::Debug)]
365
    #[debug(r#"B16U("{self}")"#)]
366
    #[allow(clippy::exhaustive_structs)]
367
    pub struct B16U(pub Vec<u8>);
368

            
369
    /// A fixed-length version of [`B16U`].
370
    #[derive(Clone, Hash, Deftly)]
371
    #[derive_deftly(BytesTransparent)]
372
    #[allow(clippy::derived_hash_with_manual_eq)]
373
    #[derive(derive_more::Debug)]
374
    #[debug(r#"FixedB16U("{self}")"#)]
375
    #[allow(clippy::exhaustive_structs)]
376
    pub struct FixedB16U<const N: usize>(pub [u8; N]);
377

            
378
    impl FromStr for B16 {
379
        type Err = Error;
380
3097
        fn from_str(s: &str) -> Result<Self> {
381
3099
            let bytes = hex::decode(s).map_err(|_| {
382
4
                EK::BadArgument
383
4
                    .at_pos(Pos::at(s))
384
4
                    .with_msg("invalid hexadecimal")
385
6
            })?;
386
3093
            Ok(B16(bytes))
387
3097
        }
388
    }
389

            
390
    impl FromStr for B16U {
391
        type Err = Error;
392
3087
        fn from_str(s: &str) -> Result<Self> {
393
3087
            Ok(B16U(B16::from_str(s)?.0))
394
3087
        }
395
    }
396

            
397
    impl<const N: usize> FromStr for FixedB16U<N> {
398
        type Err = Error;
399
        fn from_str(s: &str) -> Result<Self> {
400
            Ok(Self(B16U::from_str(s)?.0.try_into().map_err(|_| {
401
                EK::BadArgument
402
                    .at_pos(Pos::at(s))
403
                    .with_msg("invalid length")
404
            })?))
405
        }
406
    }
407

            
408
    impl Display for B16 {
409
6
        fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
410
            // `hex` has `hex::encode` but that allocates a `String`, which this approach doesn't
411
28
            for c in self.as_bytes() {
412
28
                write!(f, "{c:02x}")?;
413
            }
414
6
            Ok(())
415
6
        }
416
    }
417

            
418
    impl Display for B16U {
419
22
        fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
420
            // `hex` has `hex::encode_upper` but that allocates a `String`
421
348
            for c in self.as_bytes() {
422
348
                write!(f, "{c:02X}")?;
423
            }
424
22
            Ok(())
425
22
        }
426
    }
427

            
428
    impl<const N: usize> Display for FixedB16U<N> {
429
        fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
430
            // TODO DIRAUTH combine this with the same code in `Display for B16U`
431
            // `hex` has `hex::encode_upper` but that allocates a `String`
432
            for c in self.as_bytes() {
433
                write!(f, "{c:02X}")?;
434
            }
435
            Ok(())
436
        }
437
    }
438

            
439
    impl NormalItemArgument for B16 {}
440
    impl NormalItemArgument for B16U {}
441
    impl<const N: usize> NormalItemArgument for FixedB16U<N> {}
442
}
443

            
444
// ============================================================
445

            
446
/// Types for decoding curve25519 keys
447
mod curve25519impl {
448
    use super::*;
449

            
450
    use crate::{Error, NormalItemArgument, Result, types::misc::FixedB64};
451
    use tor_llcrypto::pk::curve25519::PublicKey;
452

            
453
    /// A Curve25519 public key, encoded in base64 with optional padding
454
    #[derive(Debug, Clone, PartialEq, Eq, Deftly)]
455
    #[derive_deftly(Transparent)]
456
    #[allow(clippy::exhaustive_structs)]
457
    pub struct Curve25519Public(pub PublicKey);
458

            
459
    impl FromStr for Curve25519Public {
460
        type Err = Error;
461
2720
        fn from_str(s: &str) -> Result<Self> {
462
2720
            let pk: FixedB64<32> = s.parse()?;
463
2710
            let pk: [u8; 32] = pk.into();
464
2710
            Ok(Curve25519Public(pk.into()))
465
2720
        }
466
    }
467

            
468
    impl Display for Curve25519Public {
469
        fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
470
            FixedB64::from(self.0.to_bytes()).fmt(f)
471
        }
472
    }
473

            
474
    impl NormalItemArgument for Curve25519Public {}
475
}
476

            
477
// ============================================================
478

            
479
/// Types for decoding ed25519 keys
480
mod ed25519impl {
481
    use super::*;
482

            
483
    use crate::{Error, NormalItemArgument, Result, types::misc::FixedB64};
484
    use derive_deftly::Deftly;
485
    use tor_llcrypto::pk::ed25519::{Ed25519Identity, Signature};
486

            
487
    /// An alleged ed25519 public key, encoded in base64 with optional
488
    /// padding.
489
    #[derive(Debug, Clone, PartialEq, Eq)]
490
    #[allow(clippy::exhaustive_structs)]
491
    pub struct Ed25519Public(pub Ed25519Identity);
492

            
493
    impl FromStr for Ed25519Public {
494
        type Err = Error;
495
2718
        fn from_str(s: &str) -> Result<Self> {
496
2718
            let pk: FixedB64<32> = s.parse()?;
497
2712
            Ok(Ed25519Public(Ed25519Identity::new(pk.into())))
498
2718
        }
499
    }
500

            
501
    impl Display for Ed25519Public {
502
        fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
503
            let pk: [u8; 32] = self.0.into();
504
            let pk = FixedB64::from(pk);
505
            pk.fmt(f)
506
        }
507
    }
508

            
509
    impl NormalItemArgument for Ed25519Public {}
510

            
511
    impl From<Ed25519Public> for Ed25519Identity {
512
2254
        fn from(pk: Ed25519Public) -> Ed25519Identity {
513
2254
            pk.0
514
2254
        }
515
    }
516

            
517
    /// Helper that checks for the presence of `ed25519`.
518
    #[derive(Debug, Clone, PartialEq, Eq, derive_more::Display, derive_more::FromStr)]
519
    #[display(rename_all = "lowercase")]
520
    #[from_str(rename_all = "lowercase")]
521
    #[allow(clippy::exhaustive_enums)]
522
    pub enum Ed25519AlgorithmString {
523
        /// Ed25519 encoded as `ed25519`.
524
        Ed25519,
525
    }
526

            
527
    impl NormalItemArgument for Ed25519AlgorithmString {}
528

            
529
    /// An Ed25519 public key found in a micro descriptor `id` line.
530
    #[derive(Debug, Clone, PartialEq, Eq, Deftly)]
531
    #[derive_deftly(ItemValueParseable)]
532
    #[non_exhaustive]
533
    pub struct Ed25519IdentityLine {
534
        /// Fixed magic identifier (`ed25519`) for this line.
535
        pub alg: Ed25519AlgorithmString,
536

            
537
        /// The actual Ed25519 identity.
538
        pub pk: Ed25519Public,
539
    }
540

            
541
    impl From<Ed25519Public> for Ed25519IdentityLine {
542
479126
        fn from(pk: Ed25519Public) -> Self {
543
479126
            Self {
544
479126
                alg: Ed25519AlgorithmString::Ed25519,
545
479126
                pk,
546
479126
            }
547
479126
        }
548
    }
549

            
550
    impl From<Ed25519Identity> for Ed25519IdentityLine {
551
479126
        fn from(pk: Ed25519Identity) -> Self {
552
479126
            Ed25519Public(pk).into()
553
479126
        }
554
    }
555

            
556
    impl ItemArgument for Signature {
557
2
        fn write_arg_onto(&self, out: &mut ItemEncoder) -> StdResult<(), Bug> {
558
2
            FixedB64::from(self.to_bytes()).write_arg_onto(out)
559
2
        }
560
    }
561
}
562

            
563
// ============================================================
564

            
565
/// Dummy types like [`Ignored`]
566
mod ignored_impl {
567
    use super::*;
568

            
569
    use crate::parse2::ErrorProblem as EP;
570

            
571
    /// Part of a network document, that isn't actually there.
572
    ///
573
    /// Used as a standin in `ns_type!` calls in various netstatus `each_variety.rs`.
574
    /// The effect is as if the field were omitted from the containing type.
575
    ///
576
    ///  * When used as item(s) (ie, a field type when deriving `NetdocParseable\[Fields\]`):
577
    ///    **ignores any number** of items with that field's keyword during parsing,
578
    ///    and emits none during encoding.
579
    ///
580
    ///    (To *reject* documents containing this item, use `Option<Void>`,
581
    ///    but note that the spec says unknown items should be ignored,
582
    ///    which would normally include items which are merely missing from one variety.)
583
    ///
584
    ///  * When used as an argument (ie, a field type when deriving `ItemValueParseable`,
585
    ///    or with `netdoc(single_arg)`  when deriving `NetdocParseable\[Fields\]`):
586
    ///    consumes **no arguments** during parsing, and emits none during encoding.
587
    ///
588
    ///  * When used as an object field (ie, `netdoc(object)` when deriving `ItemValueParseable`):
589
    ///    **rejects** an object - failing the parse if one is present.
590
    ///    (Functions similarly to `Option<Void>`, but prefer `NotPresent` as it's clearer.)
591
    ///
592
    /// There are bespoke impls of the multiplicity traits
593
    /// `ItemSetMethods` and `ObjectSetMethods`:
594
    /// don't wrap this type in `Option` or `Vec`.
595
    //
596
    // TODO we'll need to implement ItemArgument etc., for encoding, too.
597
    #[derive(Debug, Copy, Clone, Eq, PartialEq, Hash, Ord, PartialOrd, Default)]
598
    #[allow(clippy::exhaustive_structs)]
599
    #[derive(Deftly)]
600
    #[derive_deftly(NetdocParseableFields)]
601
    pub struct NotPresent;
602

            
603
    /// Ignored part of a network document.
604
    ///
605
    /// With `parse2`, can be used as an item, object, or even flattened-fields.
606
    ///
607
    /// When deriving `parse2` traits, and a field is absent in a particular netstatus variety,
608
    /// use `ns_type!` with [`NotPresent`], rather than `Ignored`.
609
    ///
610
    /// During encoding as an Items or Objects, will be entirely omitted,
611
    /// via the multiplicity arrangements.
612
    ///
613
    /// Cannot be encoded as an Argument: if this is not the last
614
    /// Argument, we need something to put into the output document to avoid generating
615
    /// a document with the arguments out of step.  If it *is* the last argument,
616
    /// it could simply be omitted, since additional arguments are in any case ignored.
617
    #[derive(Debug, Copy, Clone, Eq, PartialEq, Hash, Ord, PartialOrd, Default, Deftly)]
618
    #[derive_deftly(ItemValueParseable, NetdocParseableFields)]
619
    #[allow(clippy::exhaustive_structs)]
620
    pub struct Ignored;
621

            
622
    /// An Item or Object that would be ignored during parsing and is omitted during encoding
623
    ///
624
    /// This is the "single" item type for encoding multiplicity for Items or Objects,
625
    /// for [`Ignored`].
626
    ///
627
    /// This type is uninhabited.
628
    pub struct IgnoredItemOrObjectValue(Void);
629

            
630
    impl ItemSetMethods for P2MultiplicitySelector<NotPresent> {
631
        type Each = Ignored;
632
        type Field = NotPresent;
633
        fn can_accumulate(self, _acc: &Option<NotPresent>) -> Result<(), EP> {
634
            Ok(())
635
        }
636
12
        fn accumulate(self, _acc: &mut Option<NotPresent>, _item: Ignored) -> Result<(), EP> {
637
12
            Ok(())
638
12
        }
639
458
        fn finish(self, _acc: Option<NotPresent>, _: &'static str) -> Result<NotPresent, EP> {
640
458
            Ok(NotPresent)
641
458
        }
642
        fn debug_core(self) -> &'static str {
643
            "Ignored"
644
        }
645
    }
646

            
647
    impl ItemArgumentParseable for NotPresent {
648
14
        fn from_args(_: &mut ArgumentStream) -> Result<NotPresent, ArgumentError> {
649
14
            Ok(NotPresent)
650
14
        }
651
    }
652

            
653
    impl ObjectSetMethods for P2MultiplicitySelector<NotPresent> {
654
        type Field = NotPresent;
655
        type Each = Void;
656
6
        fn resolve_option(self, _found: Option<Void>) -> Result<NotPresent, EP> {
657
6
            Ok(NotPresent)
658
6
        }
659
        fn debug_core(self) -> &'static str {
660
            "NotPresent"
661
        }
662
    }
663

            
664
    impl<'f> encode::MultiplicityMethods<'f> for EMultiplicitySelector<NotPresent> {
665
        type Field = NotPresent;
666
        type Each = Void;
667
6
        fn iter_ordered(self, _: &'f Self::Field) -> impl Iterator<Item = &'f Self::Each> {
668
6
            iter::empty()
669
6
        }
670
    }
671

            
672
    impl encode::OptionalityMethods for EMultiplicitySelector<NotPresent> {
673
        type Field = NotPresent;
674
        type Each = Void;
675
2
        fn as_option<'f>(self, _: &'f Self::Field) -> Option<&'f Self::Each> {
676
2
            None
677
2
        }
678
    }
679

            
680
    impl FromStr for Ignored {
681
        type Err = Void;
682
        fn from_str(_s: &str) -> Result<Ignored, Void> {
683
            Ok(Ignored)
684
        }
685
    }
686

            
687
    impl ItemArgumentParseable for Ignored {
688
        fn from_args(_: &mut ArgumentStream) -> Result<Ignored, ArgumentError> {
689
            Ok(Ignored)
690
        }
691
    }
692

            
693
    impl ItemObjectParseable for Ignored {
694
6
        fn check_label(_label: &str) -> Result<(), EP> {
695
            // allow any label
696
6
            Ok(())
697
6
        }
698
6
        fn from_bytes(_input: &[u8]) -> Result<Self, EP> {
699
6
            Ok(Ignored)
700
6
        }
701
    }
702

            
703
    impl ObjectSetMethods for P2MultiplicitySelector<Ignored> {
704
        type Field = Ignored;
705
        type Each = Ignored;
706
6
        fn resolve_option(self, _found: Option<Ignored>) -> Result<Ignored, EP> {
707
6
            Ok(Ignored)
708
6
        }
709
        fn debug_core(self) -> &'static str {
710
            "Ignored"
711
        }
712
    }
713

            
714
    impl<'f> encode::MultiplicityMethods<'f> for EMultiplicitySelector<Ignored> {
715
        type Field = Ignored;
716
        type Each = IgnoredItemOrObjectValue;
717
        fn iter_ordered(self, _: &'f Self::Field) -> impl Iterator<Item = &'f Self::Each> {
718
            iter::empty()
719
        }
720
    }
721

            
722
    impl encode::OptionalityMethods for EMultiplicitySelector<Ignored> {
723
        type Field = Ignored;
724
        type Each = IgnoredItemOrObjectValue;
725
2
        fn as_option<'f>(self, _: &'f Self::Field) -> Option<&'f Self::Each> {
726
2
            None
727
2
        }
728
    }
729

            
730
    impl ItemValueEncodable for IgnoredItemOrObjectValue {
731
        fn write_item_value_onto(&self, _: ItemEncoder) -> Result<(), Bug> {
732
            void::unreachable(self.0)
733
        }
734
    }
735

            
736
    impl ItemObjectEncodable for IgnoredItemOrObjectValue {
737
        fn label(&self) -> &str {
738
            void::unreachable(self.0)
739
        }
740
        fn write_object_onto(&self, _: &mut Vec<u8>) -> Result<(), Bug> {
741
            void::unreachable(self.0)
742
        }
743
    }
744
}
745

            
746
// ============================================================
747

            
748
/// Information about unknown values, which may have been retained as a `T`
749
///
750
/// Won't grow additional variants - but, `Retained` is only included conditionally.
751
///
752
/// Also used in the form `Unknown<()>` to indicate whether unknown values *should* be retained.
753
///
754
/// ### Example
755
///
756
/// ```
757
/// # {
758
/// #![cfg(feature = "retain-unknown")]
759
///
760
/// use tor_netdoc::types::Unknown;
761
///
762
/// let mut unk: Unknown<Vec<String>> = Unknown::new_retained_default();
763
/// unk.with_mut_unknown(|u| u.push("something-we-found".into()));
764
/// assert_eq!(unk.into_retained().unwrap(), ["something-we-found"]);
765
/// # }
766
/// ```
767
///
768
/// ### Equality comparison, semantics
769
///
770
/// Two `Unknown` are consider equal if both have the same record of unknown values,
771
/// or if neither records unknown values at all.
772
///
773
/// `Unknown` is not `Eq` or `Ord` because we won't want to relate a `Discarded`
774
/// to a `Retained`.  That would be a logic error.  `partial_cmp` gives `None` for this.
775
#[derive(Debug, PartialEq, Clone, Copy, Hash)]
776
#[non_exhaustive]
777
pub enum Unknown<T> {
778
    /// The parsing discarded unknown values and they are no longer available.
779
    Discarded(PhantomData<T>),
780

            
781
    /// The document parsing retained (or should retain) unknown values.
782
    #[cfg(feature = "retain-unknown")]
783
    Retained(T),
784
}
785

            
786
impl<T> Unknown<T> {
787
    /// Create an `Unknown` which specifies that values were discarded (or should be)
788
467711
    pub fn new_discard() -> Self {
789
467711
        Unknown::Discarded(PhantomData)
790
467711
    }
791

            
792
    /// Map the `Retained`, if there is one
793
2544
    pub fn map<U>(self, f: impl FnOnce(T) -> U) -> Unknown<U> {
794
2544
        self.try_map(move |t| Ok::<_, Void>(f(t))).void_unwrap()
795
2544
    }
796

            
797
    /// Map the `Retained`, fallibly
798
2544
    pub fn try_map<U, E>(self, f: impl FnOnce(T) -> Result<U, E>) -> Result<Unknown<U>, E> {
799
2544
        Ok(match self {
800
2544
            Unknown::Discarded(_) => Unknown::Discarded(PhantomData),
801
            #[cfg(feature = "retain-unknown")]
802
            Unknown::Retained(t) => Unknown::Retained(f(t)?),
803
        })
804
2544
    }
805

            
806
    /// Obtain an `Unknown` containing (maybe) a reference
807
    pub fn as_ref(&self) -> Option<&T> {
808
        match self {
809
            Unknown::Discarded(_) => None,
810
            #[cfg(feature = "retain-unknown")]
811
            Unknown::Retained(t) => Some(t),
812
        }
813
    }
814

            
815
    /// Obtain the `Retained` data
816
    ///
817
    /// Treats lack of retention as an internal error.
818
    #[cfg(feature = "retain-unknown")]
819
    pub fn into_retained(self) -> Result<T, Bug> {
820
        match self {
821
            Unknown::Discarded(_) => Err(internal!("Unknown::retained but data not collected")),
822
            Unknown::Retained(t) => Ok(t),
823
        }
824
    }
825

            
826
    /// Start recording unknown information, with a default value for `T`
827
    #[cfg(feature = "retain-unknown")]
828
    pub fn new_retained_default() -> Self
829
    where
830
        T: Default,
831
    {
832
        Unknown::Retained(T::default())
833
    }
834

            
835
    /// Update the `Retained`, if there is one
836
    ///
837
    /// Intended for use in parsing, when we encounter an unknown value.
838
    ///
839
    /// Not provided in `try_` form.  If you think you need this, instead, unconditionally
840
    /// parse and verify the unknown value, and then conditionally insert it with this function.
841
    /// Don't parse it conditionally - that would skip some validation.
842
2
    pub fn with_mut_unknown(&mut self, f: impl FnOnce(&mut T)) {
843
2
        match self {
844
2
            Unknown::Discarded(_) => {}
845
            #[cfg(feature = "retain-unknown")]
846
            Unknown::Retained(t) => f(t),
847
        }
848
2
    }
849
}
850

            
851
impl<T: PartialOrd> PartialOrd for Unknown<T> {
852
    fn partial_cmp(&self, other: &Self) -> Option<cmp::Ordering> {
853
        use Unknown::*;
854
        match (self, other) {
855
            (Discarded(_), Discarded(_)) => Some(cmp::Ordering::Equal),
856
            #[cfg(feature = "retain-unknown")]
857
            (Discarded(_), Retained(_)) | (Retained(_), Discarded(_)) => None,
858
            #[cfg(feature = "retain-unknown")]
859
            (Retained(a), Retained(b)) => a.partial_cmp(b),
860
        }
861
    }
862
}
863

            
864
// ============================================================
865

            
866
/// A sequence of `T` items, with their order retained
867
///
868
/// Normally when a `Vec<T>` appears in a network document,
869
/// we expect the items to be sortable - they must impl [`EncodeOrd`](encode::EncodeOrd).
870
/// When encoding, the output is always sorted.
871
///
872
/// *This* type retains the ordering.
873
///
874
/// Implements the [`encode`] and [`parse2`] item multiplicity traits.
875
#[derive(Debug, Clone, Hash, Deftly, Eq, PartialEq, Educe)]
876
#[educe(Default)]
877
#[derive_deftly(Transparent)]
878
#[allow(clippy::exhaustive_structs)]
879
pub struct RetainedOrderVec<T>(pub Vec<T>);
880

            
881
// ============================================================
882

            
883
/// Types for decoding times and dates
884
mod timeimpl {
885
    use super::*;
886
    use crate::{Error, NetdocErrorKind as EK, Pos, Result};
887
    use std::time::SystemTime;
888
    use time::{
889
        OffsetDateTime, PrimitiveDateTime, format_description::FormatItem,
890
        macros::format_description,
891
    };
892

            
893
    /// A wall-clock time, encoded in Iso8601 format with an intervening
894
    /// space between the date and time.
895
    ///
896
    /// (Example: "2020-10-09 17:38:12")
897
    #[derive(Debug, Copy, Clone, Ord, PartialOrd, Eq, PartialEq, Hash, Deftly)]
898
    #[derive_deftly(Transparent)]
899
    #[allow(clippy::exhaustive_structs)]
900
    pub struct Iso8601TimeSp(pub SystemTime);
901

            
902
    /// Formatting object for parsing the space-separated Iso8601 format.
903
    const ISO_8601SP_FMT: &[FormatItem] =
904
        format_description!("[year]-[month]-[day] [hour]:[minute]:[second]");
905

            
906
    impl FromStr for Iso8601TimeSp {
907
        type Err = Error;
908
8201
        fn from_str(s: &str) -> Result<Iso8601TimeSp> {
909
8205
            let d = PrimitiveDateTime::parse(s, &ISO_8601SP_FMT).map_err(|e| {
910
8
                EK::BadArgument
911
8
                    .at_pos(Pos::at(s))
912
8
                    .with_msg(format!("invalid time: {}", e))
913
12
            })?;
914
8193
            Ok(Iso8601TimeSp(d.assume_utc().into()))
915
8201
        }
916
    }
917

            
918
    /// Formats a SystemTime according to the given format description
919
    ///
920
    /// Also converts any time::error::format to fmt::Error
921
    /// so that it can be unwrapped in the Display trait impl
922
18
    fn fmt_with(
923
18
        t: SystemTime,
924
18
        format_desc: &[FormatItem],
925
18
    ) -> core::result::Result<String, fmt::Error> {
926
18
        OffsetDateTime::from(t)
927
18
            .format(format_desc)
928
18
            .map_err(|_| fmt::Error)
929
18
    }
930

            
931
    impl Display for Iso8601TimeSp {
932
12
        fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
933
12
            write!(f, "{}", fmt_with(self.0, ISO_8601SP_FMT)?)
934
12
        }
935
    }
936

            
937
    /// A wall-clock time, encoded in ISO8601 format without an intervening
938
    /// space.
939
    ///
940
    /// This represents a specific UTC instant (ie an instant in global civil time).
941
    /// But it may not be able to represent leap seconds.
942
    ///
943
    /// The timezone is not included in the string representation; `+0000` is implicit.
944
    ///
945
    /// (Example: "2020-10-09T17:38:12")
946
    #[derive(Debug, Copy, Clone, Ord, PartialOrd, Eq, PartialEq, Hash, Deftly)]
947
    #[derive_deftly(Transparent)]
948
    #[allow(clippy::exhaustive_structs)]
949
    pub struct Iso8601TimeNoSp(pub SystemTime);
950

            
951
    /// Formatting object for parsing the space-separated Iso8601 format.
952
    const ISO_8601NOSP_FMT: &[FormatItem] =
953
        format_description!("[year]-[month]-[day]T[hour]:[minute]:[second]");
954

            
955
    impl FromStr for Iso8601TimeNoSp {
956
        type Err = Error;
957
24
        fn from_str(s: &str) -> Result<Iso8601TimeNoSp> {
958
28
            let d = PrimitiveDateTime::parse(s, &ISO_8601NOSP_FMT).map_err(|e| {
959
8
                EK::BadArgument
960
8
                    .at_pos(Pos::at(s))
961
8
                    .with_msg(format!("invalid time: {}", e))
962
12
            })?;
963
16
            Ok(Iso8601TimeNoSp(d.assume_utc().into()))
964
24
        }
965
    }
966

            
967
    impl Display for Iso8601TimeNoSp {
968
6
        fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
969
6
            write!(f, "{}", fmt_with(self.0, ISO_8601NOSP_FMT)?)
970
6
        }
971
    }
972

            
973
    impl crate::NormalItemArgument for Iso8601TimeNoSp {}
974
}
975

            
976
/// Types for decoding RSA keys
977
mod rsa {
978
    use super::*;
979
    use crate::{NetdocErrorKind as EK, Pos, Result};
980
    use std::ops::RangeBounds;
981
    use tor_llcrypto::pk::rsa::PublicKey;
982
    use tor_llcrypto::{d::Sha1, pk::rsa::KeyPair};
983

            
984
    /// The fixed exponent which we require when parsing any RSA key in a netdoc
985
    //
986
    // TODO this value is duplicated a lot in the v1 parser
987
    pub(crate) const RSA_FIXED_EXPONENT: u32 = 65537;
988

            
989
    /// The fixed exponent which we require when parsing any RSA key in a netdoc
990
    //
991
    // TODO this value is duplicated a lot in the v1 parser
992
    pub(crate) const RSA_MIN_BITS: usize = 1024;
993

            
994
    /// RSA public key, partially processed by `crate::paarse`.
995
    ///
996
    /// As parsed from a base64-encoded object.
997
    /// They key's properties (exponent and size) haven't been checked.
998
    #[allow(non_camel_case_types)]
999
    #[derive(Clone, Debug)]
    pub(crate) struct RsaPublicParse1Helper(PublicKey, Pos);
    /// RSA signature using SHA-1 as per "Signing documents" in dir-spec
    ///
    /// <https://spec.torproject.org/dir-spec/netdoc.html#signing>
    ///
    /// Used for
    /// [`AuthCert::dir-key-certification`](crate::doc::authcert::AuthCert::dir-key-certification),
    /// for example.
    ///
    /// # Caveats
    ///
    /// This type MUST NOT be used for anomalous signatures
    /// such as
    /// [`AuthCert::dir_key_crosscert`](crate::doc::authcert::AuthCert::dir_key_crosscert);
    /// in that case because `dir_key_crosscert`'s
    /// set of allowed object labels includes `ID SIGNATURE` whereas this type
    /// is always `SIGNATURE`
    #[derive(Debug, Clone, PartialEq, Eq, Deftly)]
    #[derive_deftly(ItemValueParseable, ItemValueEncodable)]
    #[deftly(netdoc(no_extra_args, signature(hash_accu = Sha1WholeKeywordLine)))]
    #[non_exhaustive]
    pub struct RsaSha1Signature {
        /// The bytes of the signature (base64-decoded).
        #[deftly(netdoc(object(label = "SIGNATURE"), with = crate::types::raw_data_object))]
        pub signature: Vec<u8>,
    }
    impl From<RsaPublicParse1Helper> for PublicKey {
5298
        fn from(k: RsaPublicParse1Helper) -> PublicKey {
5298
            k.0
5298
        }
    }
    impl super::FromBytes for RsaPublicParse1Helper {
5300
        fn from_bytes(b: &[u8], pos: Pos) -> Result<Self> {
5300
            let key = PublicKey::from_der(b)
5301
                .ok_or_else(|| EK::BadObjectVal.with_msg("unable to decode RSA public key"))?;
5298
            Ok(RsaPublicParse1Helper(key, pos))
5300
        }
    }
    impl RsaPublicParse1Helper {
        /// Give an error if the exponent of this key is not 'e'
5300
        pub(crate) fn check_exponent(self, e: u32) -> Result<Self> {
5300
            if self.0.exponent_is(e) {
5298
                Ok(self)
            } else {
2
                Err(EK::BadObjectVal
2
                    .at_pos(self.1)
2
                    .with_msg("invalid RSA exponent"))
            }
5300
        }
        /// Give an error if the length of this key's modulus, in
        /// bits, is not contained in 'bounds'
5304
        pub(crate) fn check_len<B: RangeBounds<usize>>(self, bounds: B) -> Result<Self> {
5304
            if bounds.contains(&self.0.bits()) {
5300
                Ok(self)
            } else {
4
                Err(EK::BadObjectVal
4
                    .at_pos(self.1)
4
                    .with_msg("invalid RSA length"))
            }
5304
        }
        /// Give an error if the length of this key's modulus, in
        /// bits, is not exactly `n`.
4928
        pub(crate) fn check_len_eq(self, n: usize) -> Result<Self> {
4928
            self.check_len(n..=n)
4928
        }
    }
    impl RsaSha1Signature {
        /// Make a signature according to "Signing documents" in the netdoc spec
        ///
        /// <https://spec.torproject.org/dir-spec/netdoc.html#signing>
        ///
        /// `NetdocEncoder` should have had the body of the document
        /// (everything except the signatures) already encoded.
        ///
        /// `item_keyword` is the keyword for the signature item.
        /// This is needed because different documents use different keywords,
        /// and the keyword is covered by the signature (an annoying is a layering violation).
        /// See <https://gitlab.torproject.org/tpo/core/torspec/-/issues/322>.
        ///
        /// # Example
        ///
        /// ```
        /// use derive_deftly::Deftly;
        /// use tor_error::Bug;
        /// use tor_llcrypto::pk::rsa;
        /// use tor_netdoc::derive_deftly_template_NetdocEncodable;
        /// use tor_netdoc::encode::{NetdocEncodable, NetdocEncoder};
        /// use tor_netdoc::types::RsaSha1Signature;
        ///
        /// #[derive(Deftly, Default)]
        /// #[derive_deftly(NetdocEncodable)]
        /// pub struct Document {
        ///     pub document_intro_keyword: (),
        /// }
        /// #[derive(Deftly)]
        /// #[derive_deftly(NetdocEncodable)]
        /// pub struct DocumentSignatures {
        ///     pub document_signature: RsaSha1Signature,
        /// }
        /// impl Document {
        ///     pub fn encode_sign(&self, k: &rsa::KeyPair) -> Result<String, Bug> {
        ///         let mut encoder = NetdocEncoder::new();
        ///         self.encode_unsigned(&mut encoder)?;
        ///         let document_signature =
        ///             RsaSha1Signature::new_sign_netdoc(k, &encoder, "document-signature")?;
        ///         let sigs = DocumentSignatures { document_signature };
        ///         sigs.encode_unsigned(&mut encoder)?;
        ///         let encoded = encoder.finish()?;
        ///         Ok(encoded)
        ///     }
        /// }
        ///
        /// # fn main() -> Result<(), anyhow::Error> {
        /// let k = rsa::KeyPair::generate(&mut tor_basic_utils::test_rng::testing_rng())?;
        /// let doc = Document::default();
        /// let encoded = doc.encode_sign(&k)?;
        /// assert!(encoded.starts_with(concat!(
        ///     "document-intro-keyword\n",
        ///     "document-signature\n",
        ///     "-----BEGIN SIGNATURE-----\n",
        /// )));
        /// # Ok(())
        /// # }
        /// ```
2
        pub fn new_sign_netdoc(
2
            private_key: &KeyPair,
2
            encoder: &NetdocEncoder,
2
            item_keyword: &str,
2
        ) -> StdResult<Self, Bug> {
2
            let mut h = Sha1::new();
2
            h.update(encoder.text_sofar()?);
2
            h.update(item_keyword);
2
            h.update("\n");
2
            let h = h.finalize();
2
            let signature = private_key
2
                .sign(&h)
2
                .map_err(into_internal!("RSA signing failed"))?;
2
            Ok(RsaSha1Signature { signature })
2
        }
    }
}
/// Types for decoding Ed25519 certificates
#[cfg(any(feature = "routerdesc", feature = "hs-common"))]
mod edcert {
    use crate::{NetdocErrorKind as EK, Pos, Result};
    use tor_cert::{CertType, Ed25519Cert, KeyUnknownCert};
    #[cfg(feature = "routerdesc")]
    use tor_llcrypto::pk::ed25519;
    /// An ed25519 certificate as parsed from a directory object, with
    /// signature not validated.
    #[derive(Debug, Clone)]
    pub(crate) struct UnvalidatedEdCert(KeyUnknownCert, Pos);
    impl super::FromBytes for UnvalidatedEdCert {
7371
        fn from_bytes(b: &[u8], p: Pos) -> Result<Self> {
7372
            let cert = Ed25519Cert::decode(b).map_err(|e| {
2
                EK::BadObjectVal
2
                    .at_pos(p)
2
                    .with_msg("Bad certificate")
2
                    .with_source(e)
3
            })?;
7369
            Ok(Self(cert, p))
7371
        }
7371
        fn from_vec(v: Vec<u8>, p: Pos) -> Result<Self> {
7371
            Self::from_bytes(&v[..], p)
7371
        }
    }
    impl UnvalidatedEdCert {
        /// Give an error if this certificate's type is not `desired_type`.
7371
        pub(crate) fn check_cert_type(self, desired_type: CertType) -> Result<Self> {
7371
            if self.0.peek_cert_type() != desired_type {
2
                return Err(EK::BadObjectVal.at_pos(self.1).with_msg(format!(
2
                    "bad certificate type {} (wanted {})",
2
                    self.0.peek_cert_type(),
2
                    desired_type
2
                )));
7369
            }
7369
            Ok(self)
7371
        }
        /// Give an error if this certificate's subject_key is not `pk`
        #[cfg(feature = "routerdesc")]
2248
        pub(crate) fn check_subject_key_is(self, pk: &ed25519::Ed25519Identity) -> Result<Self> {
2248
            if self.0.peek_subject_key().as_ed25519() != Some(pk) {
2
                return Err(EK::BadObjectVal
2
                    .at_pos(self.1)
2
                    .with_msg("incorrect subject key"));
2246
            }
2246
            Ok(self)
2248
        }
        /// Consume this object and return the inner Ed25519 certificate.
7367
        pub(crate) fn into_unchecked(self) -> KeyUnknownCert {
7367
            self.0
7367
        }
    }
}
/// Digest identifiers, and digests in the form `ALGORITHM=BASE64U`
///
/// As found in a vote's `m` line.
// TODO Use FixedB64 here.
mod identified_digest {
    use super::*;
    define_derive_deftly! {
        /// impl `FromStr` and `Display` for an enum with unit variants but also "unknown"
        ///
        /// Expected input: an enum whose variants are either
        ///  * unit variants, perhaps with `#[deftly(string_repr = "string")]`
        ///  * singleton tuple variant, containing `String` (or near equivalent)
        ///
        /// If `#[deftly(string_repro)]` is not specified,
        /// the default is snake case of the variant name.
        //
        // This macro may seem overkill, but open-coding these impls gives opportunities
        // for mismatches between FromStr, Display, and the variant name.
        //
        // TODO consider putting this in tor-basic-utils (maybe with a better name),
        // or possibly asking if derive_more want their FromStr to have this.
        StringReprUnitsOrUnknown for enum, expect items, beta_deftly:
        ${define STRING_REPR {
            ${vmeta(string_repr)
              as str,
              default { ${concat ${snake_case $vname}} }
            }
        }}
        impl FromStr for $ttype {
            type Err = Void;
14
            fn from_str(s: &str) -> Result<Self, Void> {
                $(
                    ${when v_is_unit}
                    if s == $STRING_REPR {
                        return Ok($vtype)
                    }
                )
                $(
                    ${when not(v_is_unit)} // anything else had better be Unknown
                    // not using `return ..;` makes this a syntax error if there are several.
                    Ok($vtype { 0: s.into() })
                )
            }
        }
        impl Display for $ttype {
            fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
                let s: &str = match self {
                    $(
                        ${when v_is_unit}
                        $vtype => $STRING_REPR,
                    )
                    $(
                        ${when not(v_is_unit)}
                        $vpat => f_0,
                    )
                };
                Display::fmt(s, f)
            }
        }
    }
    /// The name of a digest algorithm.
    ///
    /// Can represent an unrecognised algorithm, so it's parsed and reproduced.
    #[derive(Debug, Clone, Eq, PartialEq, Ord, PartialOrd, Hash, Deftly)]
    #[derive_deftly(StringReprUnitsOrUnknown)]
    #[non_exhaustive]
    pub enum DigestName {
        /// SHA-256
        Sha256,
        /// Unknown
        Unknown(String),
    }
    /// A single digest made with a nominated digest algorithm, `ALGORITHM=DIGEST`
    #[derive(Debug, Clone, Eq, PartialEq, Hash, derive_more::Display)]
    #[display("{alg}={value}")]
    #[non_exhaustive]
    pub struct IdentifiedDigest {
        /// The algorithm name.
        alg: DigestName,
        /// The digest value.
        ///
        /// Invariant: length is correct for `alg`, assuming `alg` is known.
        value: B64,
    }
    impl NormalItemArgument for DigestName {}
    impl NormalItemArgument for IdentifiedDigest {}
    /// Invalid syntax parsing an `IdentifiedDigest`
    #[derive(Debug, Clone, Eq, PartialEq, Ord, PartialOrd, Hash, thiserror::Error)]
    #[error("invalid syntax, expected ALGORITHM=DIGEST: {0}")]
    pub struct IdentifiedDigestParseError(String);
    impl FromStr for IdentifiedDigest {
        type Err = IdentifiedDigestParseError;
14
        fn from_str(s: &str) -> Result<Self, Self::Err> {
14
            (|| {
14
                let (alg, value) = s.split_once('=').ok_or("missing equals sign")?;
14
                let alg = alg.parse().void_unwrap();
14
                let value = value
14
                    .parse::<B64>()
14
                    .map_err(|e| format!("bad value: {}", e.report()))?;
14
                if let Some(exp_len) = (|| {
                    Some({
                        use DigestName::*;
14
                        match alg {
14
                            Sha256 => 32,
                            Unknown(_) => None?,
                        }
                    })
                })() {
14
                    let val_len = value.as_bytes().len();
14
                    if val_len != exp_len {
                        return Err(format!("got {val_len} bytes, expected {exp_len}"));
14
                    }
                }
14
                Ok(IdentifiedDigest { alg, value })
            })()
14
            .map_err(IdentifiedDigestParseError)
14
        }
    }
}
/// Types for decoding RSA fingerprints
mod fingerprint {
    use super::*;
    use crate::parse2::{ArgumentError, ArgumentStream, ItemArgumentParseable};
    use crate::{Error, NetdocErrorKind as EK, Pos, Result};
    use base64ct::{Base64Unpadded, Encoding as _};
    use tor_llcrypto::pk::rsa::RsaIdentity;
    /// A hex-encoded RSA key identity (fingerprint) with spaces in it.
    ///
    /// <https://spec.torproject.org/dir-spec/server-descriptor-format.html?highlight=fingerprint#item:fingerprint>
    ///
    /// Netdoc parsing adapter for [`RsaIdentity`]
    #[derive(Debug, Clone, Eq, PartialEq, Hash, Deftly)]
    #[derive_deftly(Transparent)]
    #[allow(clippy::exhaustive_structs)]
    pub struct SpFingerprint(pub RsaIdentity);
    /// A hex-encoded fingerprint with no spaces.
    ///
    /// Netdoc parsing adapter for [`RsaIdentity`]
    #[derive(Debug, Clone, Eq, PartialEq, Hash, Deftly)]
    #[derive_deftly(Transparent)]
    #[allow(clippy::exhaustive_structs)]
    pub struct Fingerprint(pub RsaIdentity);
    /// A base64-encoded fingerprint (unpadded)
    ///
    /// Netdoc parsing adapter for [`RsaIdentity`]
    #[derive(Debug, Clone, Eq, PartialEq, Hash, Deftly)]
    #[derive_deftly(Transparent)]
    #[allow(clippy::exhaustive_structs)]
    pub struct Base64Fingerprint(pub RsaIdentity);
    /// A "long identity" in the format used for Family members.
    ///
    /// Netdoc parsing adapter for [`RsaIdentity`]
    #[derive(Debug, Clone, Eq, PartialEq, Hash, Deftly)]
    #[derive_deftly(Transparent)]
    #[allow(clippy::exhaustive_structs)]
    pub(crate) struct LongIdent(pub RsaIdentity);
    /// Helper: parse an identity from a hexadecimal string
813391
    fn parse_hex_ident(s: &str) -> Result<RsaIdentity> {
813444
        RsaIdentity::from_hex(s).ok_or_else(|| {
2146
            EK::BadArgument
2146
                .at_pos(Pos::at(s))
2146
                .with_msg("wrong length on fingerprint")
2146
        })
813391
    }
    impl FromStr for SpFingerprint {
        type Err = Error;
2248
        fn from_str(s: &str) -> Result<SpFingerprint> {
2250
            let ident = parse_hex_ident(&s.replace(' ', "")).map_err(|e| e.at_pos(Pos::at(s)))?;
2244
            Ok(SpFingerprint(ident))
2248
        }
    }
    impl ItemArgumentParseable for SpFingerprint {
10
        fn from_args<'s>(
10
            args: &mut ArgumentStream<'s>,
10
        ) -> std::result::Result<Self, ArgumentError> {
            // Take the first 10 arguments because an SpFingerprint consists of
            // 10 x 4 = 40 characters.
10
            let fp = args.take(10).collect::<Vec<_>>();
            // Less than 10 means missing arguments.
10
            if fp.len() < 10 {
2
                return Err(ArgumentError::Missing);
8
            }
            // More than 10 should be impossible due to .take(10).
8
            debug_assert_eq!(fp.len(), 10);
            // All arguments must be 4 characters long.
68
            if fp.iter().any(|arg| arg.len() != 4) {
2
                return Err(ArgumentError::Invalid);
6
            }
            // Convert it to a string without spaces, RsaIdentity::from_hex will
            // verify the rest.
            Ok(Self(
6
                RsaIdentity::from_hex(fp.join("").as_str()).ok_or(ArgumentError::Invalid)?,
            ))
10
        }
    }
    impl FromStr for Base64Fingerprint {
        type Err = Error;
2546
        fn from_str(s: &str) -> Result<Base64Fingerprint> {
2546
            let b = s.parse::<super::B64>()?;
2546
            let ident = RsaIdentity::from_bytes(b.as_bytes()).ok_or_else(|| {
                EK::BadArgument
                    .at_pos(Pos::at(s))
                    .with_msg("Wrong identity length")
            })?;
2546
            Ok(Base64Fingerprint(ident))
2546
        }
    }
    impl Display for Base64Fingerprint {
2
        fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
2
            Display::fmt(&Base64Unpadded::encode_string(self.as_bytes()), f)
2
        }
    }
    impl FromStr for Fingerprint {
        type Err = Error;
10311
        fn from_str(s: &str) -> Result<Fingerprint> {
10316
            let ident = parse_hex_ident(s).map_err(|e| e.at_pos(Pos::at(s)))?;
10301
            Ok(Fingerprint(ident))
10311
        }
    }
    impl Display for Fingerprint {
4
        fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
4
            Display::fmt(&hex::encode_upper(self.as_bytes()), f)
4
        }
    }
    impl FromStr for LongIdent {
        type Err = Error;
800832
        fn from_str(mut s: &str) -> Result<LongIdent> {
800832
            if s.starts_with('$') {
406
                s = &s[1..];
800600
            }
800832
            if let Some(idx) = s.find(['=', '~']) {
6
                s = &s[..idx];
800826
            }
800832
            let ident = parse_hex_ident(s)?;
798700
            Ok(LongIdent(ident))
800832
        }
    }
    impl Display for LongIdent {
        fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
            write!(f, "${}", self.0.as_hex_upper())
        }
    }
    impl crate::NormalItemArgument for Fingerprint {}
    impl crate::NormalItemArgument for Base64Fingerprint {}
    impl crate::NormalItemArgument for LongIdent {}
}
/// A type for relay nicknames
mod nickname {
    use super::*;
    use tinystr::TinyAsciiStr;
    /// This is a strange limit, but it comes from Tor.
    const MAX_NICKNAME_LEN: usize = 19;
    /// The nickname for a Tor relay.
    ///
    /// These nicknames are legacy mechanism that's occasionally useful in
    /// debugging. They should *never* be used to uniquely identify relays;
    /// nothing prevents two relays from having the same nickname.
    ///
    /// Nicknames are required to be ASCII, alphanumeric, and between 1 and 19
    /// characters inclusive.
    #[derive(Clone, Debug, PartialEq, Eq)]
    pub struct Nickname(tinystr::TinyAsciiStr<MAX_NICKNAME_LEN>);
    /// Invalid nickname
    #[derive(Clone, Debug, thiserror::Error)]
    #[error("invalid nickname")]
    #[non_exhaustive]
    pub struct InvalidNickname {}
    impl Nickname {
        /// Return a view of this nickname as a string slice.
8
        pub(crate) fn as_str(&self) -> &str {
8
            self.0.as_str()
8
        }
    }
    impl Display for Nickname {
2
        fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
2
            self.as_str().fmt(f)
2
        }
    }
    impl FromStr for Nickname {
        type Err = InvalidNickname;
460352
        fn from_str(s: &str) -> Result<Self, InvalidNickname> {
460354
            let tiny = TinyAsciiStr::from_str(s).map_err(|_| InvalidNickname {})?;
460348
            if tiny.is_ascii_alphanumeric() && !tiny.is_empty() {
460344
                Ok(Nickname(tiny))
            } else {
4
                Err(InvalidNickname {})
            }
460352
        }
    }
    impl crate::NormalItemArgument for Nickname {}
}
/// Hostnames etc.
//
// TODO maybe move all this to tor-basic-utils
mod hostname {
    use super::*;
    use std::net::IpAddr;
    /// Internet hostname
    ///
    /// Valid according to Internet RFC1123,
    /// with the additional restriction that there must be at least one letter.
    /// (That means that anything accepted as a `Hostname`
    /// won't be accepted as an address even by very relaxed IPv4 address parsers.
    /// We presume that no TLD will ever exist that is entirely decimal digits.)
    ///
    /// Preserves case.
    ///
    /// Reserved hostname such as `example.come`, `tor.invalid` and `localhost`
    /// are accepted.
    ///
    /// # Comparisons; `PartialEq`, `Eq`
    ///
    /// The `PartialEq` and `Eq` implementations are case sensitive,
    /// even though internet hostnames are not case-sensitive.
    ///
    /// Comparing hostnames for identical apparent meaning is complicated.
    /// If you need to do that, you (may) need to engage with punycode (IDN),
    /// as well as arranging for a case-insensitive comparison.
    ///
    /// And of course, hostnames reference to the DNS.
    /// A single host may have multiple names and it may change its address.
    #[derive(Clone, Debug, Hash, Eq, PartialEq, Ord, PartialOrd)] //
    #[derive(derive_more::Into, derive_more::Deref, derive_more::AsRef, derive_more::Display)]
    pub struct Hostname(String);
    /// Hostname, or IP address (v4 or v6)
    ///
    /// Preserves hostname case.  See [`Hostname`].
    ///
    /// Reserved hostnames and addresses (eg `0.0.0.0` or `tor.invalid`) are accepted.
    ///
    /// IPv6 addresses are represented *without* surrounding `[ ]`.
    ///
    /// Therefore, you cannot make this into a host-and-port by appending `:port`.
    /// To process name-and-port is complex.  `SRV` (or `MX`) records might be involved.
    //
    // This type is called `InternetHost` to emphasise that it is primarily for
    // hosts on the public internet and, unlike arti-client's `Host`,
    // has special handling of `.onion` addresses.
    #[derive(Clone, Debug, Hash, Eq, PartialEq, Ord, PartialOrd)] //
    #[derive(derive_more::Display)]
    #[allow(clippy::exhaustive_enums)]
    // TODO derive .as_hostname(), .as_ip_addr(), From<Hostname>, From<IpAddr>
    pub enum InternetHost {
        /// Hostname
        #[display("{_0}")]
        Name(Hostname),
        /// IP address (v4 or v6)
        #[display("{_0}")]
        IpAddr(IpAddr),
    }
    /// Invalid hostname
    #[derive(Clone, Debug, thiserror::Error)]
    #[error("invalid hostname")]
    #[non_exhaustive]
    pub struct InvalidHostname {}
    /// Invalid Internet hostname/address
    #[derive(Clone, Debug, thiserror::Error)]
    #[error("invalid: not a valid hostname, nor a valid IPv4 or IPv6 address")]
    #[non_exhaustive]
    pub struct InvalidInternetHost {}
    impl Hostname {
        /// Obtain this hostname as a `str`
8
        pub fn as_str(&self) -> &str {
8
            &self.0
8
        }
    }
    impl AsRef<str> for Hostname {
        fn as_ref(&self) -> &str {
            self.as_str()
        }
    }
    impl TryFrom<String> for Hostname {
        type Error = InvalidHostname;
488
        fn try_from(s: String) -> Result<Self, InvalidHostname> {
488
            if hostname_validator::is_valid(&s) &&
                // Reject hostnames that consist only of decimal digits and full stops.
                // Some of those are accepted by some old IPv4 address parsers.
                // If any fool makes a TLD that is only digits, they deserve everything they get.
552
                !s.chars().all(|c| c.is_ascii_digit() || c == '.')
            {
444
                Ok(Hostname(s))
            } else {
44
                Err(InvalidHostname {})
            }
488
        }
    }
    impl FromStr for Hostname {
        type Err = InvalidHostname;
488
        fn from_str(s: &str) -> Result<Self, InvalidHostname> {
488
            s.to_owned().try_into()
488
        }
    }
    impl FromStr for InternetHost {
        type Err = InvalidInternetHost;
3125
        fn from_str(s: &str) -> Result<Self, InvalidInternetHost> {
3125
            if let Ok(y) = s.parse() {
2671
                Ok(InternetHost::IpAddr(y))
454
            } else if let Ok(y) = s.parse() {
436
                Ok(InternetHost::Name(y))
            } else {
                // For simplicity, we  discard the errors from parsing the options
                // rather than trying to reproduce them.  Why something isn't a valid
                // address or hostname ought to be fairly obvious.
18
                Err(InvalidInternetHost {})
            }
3125
        }
    }
    impl NormalItemArgument for Hostname {}
    impl NormalItemArgument for InternetHost {}
}
/// Contact information of the relay operator.
mod contact_info {
    use super::*;
    /// `contact` item: contact information (eg of a relay dirauth operator)
    ///
    /// <https://spec.torproject.org/dir-spec/server-descriptor-format.html#item:contact>
    ///
    /// Also used for authority entries in netstatus documents.
    #[derive(Clone, Debug, PartialEq, Eq, Deftly)] //
    #[derive(derive_more::Into, derive_more::AsRef, derive_more::Deref, derive_more::Display)]
    #[derive_deftly(ItemValueEncodable)]
    #[non_exhaustive]
    pub struct ContactInfo(#[deftly(netdoc(rest))] String);
    /// Contact information (`contact` item value) has invalid syntax
    #[derive(Clone, Debug, thiserror::Error)]
    #[error("contact information (`contact` item value) has invalid syntax")]
    #[non_exhaustive]
    pub struct InvalidContactInfo {}
    impl FromStr for ContactInfo {
        type Err = InvalidContactInfo;
3105
        fn from_str(s: &str) -> Result<Self, InvalidContactInfo> {
            // TODO torspec#396 we should probably impose more restrictions
            // For now we forbid `\n` and initial whitespace, which is enough to ensure
            // that all values will roundtrip unchanged through netdoc encoding and parsing.
3105
            if s.contains('\n') || s.starts_with(char::is_whitespace) {
4
                Err(InvalidContactInfo {})
            } else {
3101
                Ok(ContactInfo(s.to_owned()))
            }
3105
        }
    }
    impl ItemValueParseable for ContactInfo {
1932
        fn from_unparsed(mut item: UnparsedItem<'_>) -> Result<Self, parse2::ErrorProblem> {
1932
            item.check_no_object()?;
1932
            item.args_mut()
1932
                .into_remaining()
1932
                .parse()
1932
                .map_err(|_e| item.args().handle_error("info", ArgumentError::Invalid))
1932
        }
    }
}
/// Types for boolean-like types.
mod boolean {
    use std::{fmt::Display, str::FromStr};
    use derive_more::{From, Into};
    use crate::{Error, NetdocErrorKind as EK, NormalItemArgument, Pos};
    /// A boolean that is represented by a `0` (false) or `1` (true).
    // TODO DIRMIRROR: Derive Transparent
    #[derive(Clone, Copy, Debug, Default, From, Into)]
    #[allow(clippy::exhaustive_structs)]
    pub struct NumericBoolean(pub bool);
    impl FromStr for NumericBoolean {
        type Err = Error;
6
        fn from_str(s: &str) -> Result<Self, Self::Err> {
6
            match s {
6
                "0" => Ok(Self(false)),
4
                "1" => Ok(Self(true)),
2
                _ => Err(EK::BadArgument
2
                    .at_pos(Pos::at(s))
2
                    .with_msg("Invalid numeric boolean")),
            }
6
        }
    }
    impl Display for NumericBoolean {
4
        fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
4
            write!(f, "{}", u8::from(self.0))
4
        }
    }
    impl NormalItemArgument for NumericBoolean {}
}
/// Types for router descriptors.
pub mod routerdesc {
    use super::*;
    use parse2::ErrorProblem as EP;
    use tor_llcrypto::pk::ed25519;
    /// Version argument found in an `overload-general` item.
    ///
    /// <https://spec.torproject.org/dir-spec/server-descriptor-format.html#item:overload-general>
    #[derive(Debug, Clone, Copy, Hash, Eq, PartialEq, strum::EnumString, strum::Display)]
    #[non_exhaustive]
    pub enum OverloadGeneralVersion {
        /// Version 1, currently the only supported and specified one.
        #[strum(serialize = "1")]
        V1,
    }
    impl NormalItemArgument for OverloadGeneralVersion {}
    /// The overload general type found in router descriptors.
    ///
    /// <https://spec.torproject.org/dir-spec/server-descriptor-format.html#item:overload-general>
    #[derive(Debug, Clone, Copy, PartialEq, Eq, Deftly)]
    #[derive_deftly(ItemValueParseable)]
    #[non_exhaustive]
    pub struct OverloadGeneral {
        /// The version of the item.
        pub version: OverloadGeneralVersion,
        /// The timestamp since when the relay is overloaded.
        pub since: Iso8601TimeSp,
    }
    /// Introduction line of a router descriptor.
    ///
    /// <https://spec.torproject.org/dir-spec/server-descriptor-format.html#item:router>
    #[derive(Clone, Debug, PartialEq, Eq, Deftly)]
    #[derive_deftly(ItemValueParseable)]
    #[non_exhaustive]
    pub struct RouterDescIntroItem {
        /// A valid router [`Nickname`].
        pub nickname: Nickname,
        /// An IPv4 address in dotted-squad format.
        pub address: std::net::Ipv4Addr,
        /// The TCP port of the onion router.
        pub orport: u16,
        /// Legacy.
        pub socksport: u16,
        /// Legacy.
        pub dirport: u16,
    }
    /// Digest identifying the extra-info document.
    ///
    /// <https://spec.torproject.org/dir-spec/server-descriptor-format.html#item:extra-info-digest>
    #[derive(Clone, Debug, PartialEq, Eq, Deftly)]
    #[derive_deftly(ItemValueParseable)]
    #[non_exhaustive]
    pub struct ExtraInfoDigests {
        /// Mandatory SHA-1 of the signed data in base 16.
        pub sha1: FixedB16U<20>,
        /// Optional SHA-256 of the entire extra-info in base 64.
        pub sha2: Option<FixedB64<32>>,
    }
    /// Accumulator for router descriptor hash signatures.
    #[derive(Debug, Clone, Default, Deftly)]
    #[derive_deftly(AsMutSelf)]
    #[allow(clippy::exhaustive_structs)]
    pub struct RouterHashAccu {
        /// Potentially the SHA-1 for the signature.
        pub sha1: Option<[u8; 20]>,
        /// Potentially the SHA-256 for the signature.
        pub sha256: Option<[u8; 32]>,
    }
    /// SHA-256 router descriptor signature including magic and the keyword.
    #[derive(Debug, Clone, PartialEq, Eq, Deftly)]
    #[derive_deftly(ItemValueEncodable)]
    #[allow(clippy::exhaustive_structs)]
    // TODO SPEC is RouterSigEd25519 not a standard-ish kind of signature?
    // TODO DIRAUTH is RouterSigEd25519 not a standard-ish kind of signature?
    pub struct RouterSigEd25519(pub ed25519::Signature);
    impl RouterSigEd25519 {
        /// The magic prefix for hashing this type of signature.
        const HASH_PREFIX_MAGIC: &str = "Tor router descriptor signature v1";
        /// Calculate the hash for signature
        ///
        /// `signature_item_kw_spc` is the keyword *with a trailing space*.
        /// It's `&[&str]` for the convenience of the two call sites.
4
        fn hash(document_sofar: &str, signature_item_kw_spc: &[&str]) -> [u8; 32] {
4
            debug_assert!(
4
                signature_item_kw_spc
4
                    .last()
4
                    .expect("signature_item_kw_spc")
4
                    .ends_with(" ")
            );
4
            let mut h = tor_llcrypto::d::Sha256::new();
4
            h.update(Self::HASH_PREFIX_MAGIC);
4
            h.update(document_sofar);
6
            for b in signature_item_kw_spc {
6
                h.update(b);
6
            }
4
            h.finalize().into()
4
        }
        /// Make a signature during document encoding
        ///
        /// `item_keyword` is the keyword for the signature item.
        ///
        /// # Example
        ///
        /// ```
        /// use derive_deftly::Deftly;
        /// use tor_error::Bug;
        /// use tor_llcrypto::pk::ed25519;
        /// use tor_netdoc::derive_deftly_template_NetdocEncodable;
        /// use tor_netdoc::encode::{NetdocEncodable, NetdocEncoder};
        /// use tor_netdoc::types::routerdesc::RouterSigEd25519;
        ///
        /// #[derive(Deftly, Default)]
        /// #[derive_deftly(NetdocEncodable)]
        /// pub struct Document {
        ///     pub document_intro_keyword: (),
        /// }
        /// #[derive(Deftly)]
        /// #[derive_deftly(NetdocEncodable)]
        /// pub struct DocumentSignatures {
        ///     pub document_signature: RouterSigEd25519,
        /// }
        /// impl Document {
        ///     pub fn encode_sign(&self, k: &ed25519::Keypair) -> Result<String, Bug> {
        ///         let mut encoder = NetdocEncoder::new();
        ///         self.encode_unsigned(&mut encoder)?;
        ///         let document_signature =
        ///             RouterSigEd25519::new_sign_netdoc(k, &encoder, "document-signature")?;
        ///         let sigs = DocumentSignatures { document_signature };
        ///         sigs.encode_unsigned(&mut encoder)?;
        ///         let encoded = encoder.finish()?;
        ///         Ok(encoded)
        ///     }
        /// }
        ///
        /// # fn main() -> Result<(), anyhow::Error> {
        /// let k = ed25519::Keypair::generate(&mut tor_basic_utils::test_rng::testing_rng());
        /// let doc = Document::default();
        /// let encoded = doc.encode_sign(&k)?;
        /// assert!(encoded.starts_with(concat!(
        ///     "document-intro-keyword\n",
        ///     "document-signature ",
        /// )));
        /// # Ok(())
        /// # }
        /// ```
2
        pub fn new_sign_netdoc(
2
            private_key: &ed25519::Keypair,
2
            encoder: &NetdocEncoder,
2
            item_keyword: &str,
2
        ) -> StdResult<Self, Bug> {
2
            let signature = private_key
2
                .sign(&Self::hash(encoder.text_sofar()?, &[item_keyword, " "]))
2
                .to_bytes()
2
                .into();
2
            Ok(RouterSigEd25519(signature))
2
        }
    }
    impl SignatureItemParseable for RouterSigEd25519 {
        type HashAccu = RouterHashAccu;
2
        fn from_unparsed_and_body(
2
            mut item: UnparsedItem<'_>,
2
            hash_inputs: &SignatureHashInputs<'_>,
2
            hash: &mut Self::HashAccu,
2
        ) -> Result<Self, EP> {
            // TODO DIRMIRROR break this out into impl ItemArgumentParseable for Signature
2
            let args = item.args_mut();
2
            let sig = FixedB64::<64>::from_args(args)
2
                .map_err(|e| args.handle_error("router-sig-ed25519", e))?
                .0;
2
            let sig = ed25519::Signature::from(sig);
2
            hash.sha256 = Some(Self::hash(
2
                hash_inputs.document_sofar,
2
                &[hash_inputs.signature_item_kw_spc],
2
            ));
2
            Ok(Self(sig))
2
        }
    }
    /// SHA-1 router descriptor signature over `router-sig-ed25519`.
    // TODO DIRMIRROR Is this not the same as RsaSha1Signature ?
    #[derive(Debug, Clone, PartialEq, Eq)]
    #[allow(clippy::exhaustive_structs)]
    pub struct RouterSignature(pub Vec<u8>);
    impl SignatureItemParseable for RouterSignature {
        type HashAccu = RouterHashAccu;
        fn from_unparsed_and_body(
            mut item: UnparsedItem<'_>,
            hash_inputs: &SignatureHashInputs<'_>,
            hash: &mut Self::HashAccu,
        ) -> Result<Self, EP> {
            // There must be no additonal arguments.
            let args = item.args_mut();
            if args.next().is_some() {
                return Err(EP::UnexpectedArgument {
                    column: args.prev_arg_column(),
                });
            }
            let obj = item.object().ok_or(EP::MissingObject)?.decode_data()?;
            let mut h = tor_llcrypto::d::Sha1::new();
            h.update(hash_inputs.document_sofar);
            h.update(hash_inputs.signature_item_line);
            h.update("\n");
            hash.sha1 = Some(h.finalize().into());
            Ok(Self(obj))
        }
    }
}
#[cfg(test)]
mod test {
    // @@ begin test lint list maintained by maint/add_warning @@
    #![allow(clippy::bool_assert_comparison)]
    #![allow(clippy::clone_on_copy)]
    #![allow(clippy::dbg_macro)]
    #![allow(clippy::mixed_attributes_style)]
    #![allow(clippy::print_stderr)]
    #![allow(clippy::print_stdout)]
    #![allow(clippy::single_char_pattern)]
    #![allow(clippy::unwrap_used)]
    #![allow(clippy::unchecked_time_subtraction)]
    #![allow(clippy::useless_vec)]
    #![allow(clippy::needless_pass_by_value)]
    //! <!-- @@ end test lint list maintained by maint/add_warning @@ -->
    use itertools::Itertools;
    use base64ct::Encoding;
    use super::*;
    use crate::{Pos, Result};
    /// Decode s as a multi-line base64 string, ignoring ascii whitespace.
    fn base64_decode_ignore_ws(s: &str) -> std::result::Result<Vec<u8>, base64ct::Error> {
        let mut s = s.to_string();
        s.retain(|c| !c.is_ascii_whitespace());
        base64ct::Base64::decode_vec(s.as_str())
    }
    #[test]
    fn base64() -> Result<()> {
        // Test parsing success:
        // Unpadded:
        assert_eq!("Mi43MTgyOA".parse::<B64>()?.as_bytes(), &b"2.71828"[..]);
        assert!("Mi43MTgyOA".parse::<B64>()?.check_len(7..8).is_ok());
        assert_eq!("Mg".parse::<B64>()?.as_bytes(), &b"2"[..]);
        assert!("Mg".parse::<B64>()?.check_len(1..2).is_ok());
        assert_eq!(
            "8J+NkvCfjZLwn42S8J+NkvCfjZLwn42S"
                .parse::<B64>()?
                .as_bytes(),
            "🍒🍒🍒🍒🍒🍒".as_bytes()
        );
        assert!(
            "8J+NkvCfjZLwn42S8J+NkvCfjZLwn42S"
                .parse::<B64>()?
                .check_len(24..25)
                .is_ok()
        );
        assert!(
            "ppwthHXW8kXD0f9fE7UPYsOAAu4uj5ORwSomCMxKkz8="
                .parse::<B64>()?
                .check_len(32..33)
                .is_ok()
        );
        // Padded:
        assert_eq!("Mi43MTgyOA==".parse::<B64>()?.as_bytes(), &b"2.71828"[..]);
        assert!("Mi43MTgyOA==".parse::<B64>()?.check_len(7..8).is_ok());
        assert_eq!("Mg==".parse::<B64>()?.as_bytes(), &b"2"[..]);
        assert!("Mg==".parse::<B64>()?.check_len(1..2).is_ok());
        // Test parsing failures:
        // Invalid character.
        assert!("Mi43!!!!!!".parse::<B64>().is_err());
        // Invalid last character.
        assert!("Mi".parse::<B64>().is_err());
        assert!(
            "ppwthHXW8kXD0f9fE7UPYsOAAu4uj5ORwSomCMxaaaa"
                .parse::<B64>()
                .is_err()
        );
        // Invalid length.
        assert!("Mi43MTgyOA".parse::<B64>()?.check_len(8..).is_err());
        Ok(())
    }
    #[test]
    fn base64_lengths() -> Result<()> {
        assert_eq!("".parse::<B64>()?.as_bytes(), b"");
        assert!("=".parse::<B64>().is_err());
        assert!("==".parse::<B64>().is_err());
        assert!("B".parse::<B64>().is_err());
        assert!("B=".parse::<B64>().is_err());
        assert!("B==".parse::<B64>().is_err());
        assert!("Bg=".parse::<B64>().is_err());
        assert_eq!("Bg".parse::<B64>()?.as_bytes(), b"\x06");
        assert_eq!("Bg==".parse::<B64>()?.as_bytes(), b"\x06");
        assert_eq!("BCg".parse::<B64>()?.as_bytes(), b"\x04\x28");
        assert_eq!("BCg=".parse::<B64>()?.as_bytes(), b"\x04\x28");
        assert!("BCg==".parse::<B64>().is_err());
        assert_eq!("BCDE".parse::<B64>()?.as_bytes(), b"\x04\x20\xc4");
        assert!("BCDE=".parse::<B64>().is_err());
        assert!("BCDE==".parse::<B64>().is_err());
        Ok(())
    }
    #[test]
    fn base64_rev() {
        use base64ct::{Base64, Base64Unpadded};
        // Check that strings that we accept are precisely ones which
        // can be generated by either Base64 or Base64Unpadded
        for n in 0..=5 {
            for c_vec in std::iter::repeat_n("ACEQg/=".chars(), n).multi_cartesian_product() {
                let s: String = c_vec.into_iter().collect();
                #[allow(clippy::print_stderr)]
                let b = match s.parse::<B64>() {
                    Ok(b) => {
                        eprintln!("{:10} {:?}", &s, b.as_bytes());
                        b
                    }
                    Err(_) => {
                        eprintln!("{:10} Err", &s);
                        continue;
                    }
                };
                let b = b.as_bytes();
                let ep = Base64::encode_string(b);
                let eu = Base64Unpadded::encode_string(b);
                assert!(
                    s == ep || s == eu,
                    "{:?} decoded to {:?} giving neither {:?} nor {:?}",
                    s,
                    b,
                    ep,
                    eu
                );
            }
        }
    }
    #[test]
    fn base16() -> anyhow::Result<()> {
        let chk = |s: &str, b: &[u8]| -> anyhow::Result<()> {
            let parsed = s.parse::<B16>()?;
            assert_eq!(parsed.as_bytes(), b, "{s:?}");
            assert_eq!(parsed.to_string(), s.to_ascii_lowercase());
            let parsed = s.parse::<B16U>()?;
            assert_eq!(parsed.as_bytes(), b, "{s:?}");
            assert_eq!(parsed.to_string(), s.to_ascii_uppercase());
            Ok(())
        };
        chk("332e313432", b"3.142")?;
        chk("332E313432", b"3.142")?;
        chk("332E3134", b"3.14")?;
        assert!("332E313".parse::<B16>().is_err());
        assert!("332G3134".parse::<B16>().is_err());
        Ok(())
    }
    #[test]
    fn curve25519() -> Result<()> {
        use tor_llcrypto::pk::curve25519::PublicKey;
        let k1 = "ppwthHXW8kXD0f9fE7UPYsOAAu4uj5ORwSomCMxKkz8=";
        let k2 = hex::decode("a69c2d8475d6f245c3d1ff5f13b50f62c38002ee2e8f9391c12a2608cc4a933f")
            .unwrap();
        let k2: &[u8; 32] = &k2[..].try_into().unwrap();
        let k1: PublicKey = k1.parse::<Curve25519Public>()?.into();
        assert_eq!(k1, (*k2).into());
        assert!(
            "ppwthHXW8kXD0f9fE7UPYsOAAu4uj5ORwSomCMxKkz"
                .parse::<Curve25519Public>()
                .is_err()
        );
        assert!(
            "ppwthHXW8kXD0f9fE7UPYsOAAu4uj5ORSomCMxKkz"
                .parse::<Curve25519Public>()
                .is_err()
        );
        assert!(
            "ppwthHXW8kXD0f9fE7UPYsOAAu4uj5wSomCMxKkz"
                .parse::<Curve25519Public>()
                .is_err()
        );
        assert!(
            "ppwthHXW8kXD0f9fE7UPYsOAAu4ORwSomCMxKkz"
                .parse::<Curve25519Public>()
                .is_err()
        );
        Ok(())
    }
    #[test]
    fn ed25519() -> Result<()> {
        use tor_llcrypto::pk::ed25519::Ed25519Identity;
        let k1 = "WVIPQ8oArAqLY4XzkcpIOI6U8KsUJHBQhG8SC57qru0";
        let k2 = hex::decode("59520f43ca00ac0a8b6385f391ca48388e94f0ab14247050846f120b9eeaaeed")
            .unwrap();
        let k1: Ed25519Identity = k1.parse::<Ed25519Public>()?.into();
        assert_eq!(k1, Ed25519Identity::from_bytes(&k2).unwrap());
        assert!(
            "WVIPQ8oArAqLY4Xzk0!!!!8KsUJHBQhG8SC57qru"
                .parse::<Ed25519Public>()
                .is_err()
        );
        assert!(
            "WVIPQ8oArAqLY4XzkcpIU8KsUJHBQhG8SC57qru"
                .parse::<Ed25519Public>()
                .is_err()
        );
        assert!(
            "WVIPQ8oArAqLY4XzkcpIU8KsUJHBQhG8SC57qr"
                .parse::<Ed25519Public>()
                .is_err()
        );
        // right length, bad key:
        assert!(
            "ppwthHXW8kXD0f9fE7UPYsOAAu4uj5ORwSomCMxaaaa"
                .parse::<Curve25519Public>()
                .is_err()
        );
        Ok(())
    }
    #[test]
    fn time() -> Result<()> {
        use humantime::parse_rfc3339;
        use std::time::SystemTime;
        let t = "2020-09-29 13:36:33".parse::<Iso8601TimeSp>()?;
        let t: SystemTime = t.into();
        assert_eq!(t, parse_rfc3339("2020-09-29T13:36:33Z").unwrap());
        assert!("2020-FF-29 13:36:33".parse::<Iso8601TimeSp>().is_err());
        assert!("2020-09-29Q13:99:33".parse::<Iso8601TimeSp>().is_err());
        assert!("2020-09-29".parse::<Iso8601TimeSp>().is_err());
        assert!("too bad, waluigi time".parse::<Iso8601TimeSp>().is_err());
        assert_eq!(
            "2020-09-29 13:36:33",
            "2020-09-29 13:36:33".parse::<Iso8601TimeSp>()?.to_string()
        );
        let t = "2020-09-29T13:36:33".parse::<Iso8601TimeNoSp>()?;
        let t: SystemTime = t.into();
        assert_eq!(t, parse_rfc3339("2020-09-29T13:36:33Z").unwrap());
        assert!("2020-09-29 13:36:33".parse::<Iso8601TimeNoSp>().is_err());
        assert!("2020-09-29Q13:99:33".parse::<Iso8601TimeNoSp>().is_err());
        assert!("2020-09-29".parse::<Iso8601TimeNoSp>().is_err());
        assert!("too bad, waluigi time".parse::<Iso8601TimeNoSp>().is_err());
        assert_eq!(
            "2020-09-29T13:36:33",
            "2020-09-29T13:36:33"
                .parse::<Iso8601TimeNoSp>()?
                .to_string()
        );
        Ok(())
    }
    #[test]
    fn rsa_public_key() {
        // Taken from a chutney network.
        let key_b64 = r#"
        MIIBigKCAYEAsDkzTcKS4kAF56R2ijb9qCek53tKC1EwMdpWMk58bB28fY6kHc55
        E7n1hB+LC5neZlx88GKuZ9k8P3g0MlO5ejalcfBdIIm28Nz86JXf/L23YnEpxnG/
        IpxZEcmx/EYN+vwp72W3DGuzyntaoaut6lGJk+O/aRCLLcTm4MNznvN1ackK2H6b
        Xm2ejRwtVRLoPKODJiPGl43snCfXXWsMH3IALFOgm0szPLv2fAJzBI8VWrUN81M/
        lgwJhG6+xbr1CkrXI5fKs/TNr0B0ydC9BIZplmPrnXaeNklnw1cqUJ1oxDSgBrvx
        rpDo7paObjSPV26opa68QKGa7Gu2MZQC3RzViNCbawka/108g6hSUkoM+Om2oivr
        DvtMOs10MjsfibEBVnwEhqnlb/gj3hJkYoGRsCwAyMIaMObHcmAevMJRWAjGCc8T
        GMS9dSmg1IZst+U+V2OCcIHXT6wZ1zPsBM0pYKVLCwtewaq1306k0n+ekriEo7eI
        FS3Dd/Dx/a6jAgMBAAE=
        "#;
        let key_bytes = base64_decode_ignore_ws(key_b64).unwrap();
        let rsa = RsaPublicParse1Helper::from_vec(key_bytes, Pos::None).unwrap();
        let bits = tor_llcrypto::pk::rsa::PublicKey::from(rsa.clone()).bits();
        assert_eq!(bits, 3072);
        // tests on a valid key
        assert!(rsa.clone().check_exponent(65537).is_ok());
        assert!(rsa.clone().check_exponent(1337).is_err());
        assert!(rsa.clone().check_len_eq(3072).is_ok());
        assert!(rsa.clone().check_len(1024..=4096).is_ok());
        assert!(rsa.clone().check_len(1024..=1024).is_err());
        assert!(rsa.check_len(4096..).is_err());
        // A string of bytes that is not an RSA key.
        let failure = RsaPublicParse1Helper::from_vec(vec![1, 2, 3], Pos::None);
        assert!(failure.is_err());
    }
    #[cfg(feature = "routerdesc")]
    #[test]
    fn ed_cert() {
        use tor_llcrypto::pk::ed25519::Ed25519Identity;
        // From a chutney network.
        let cert_b64 = r#"
        AQQABwRNAR6m3kq5h8i3wwac+Ti293opoOP8RKGP9MT0WD4Bbz7YAQAgBACGCdys
        G7AwsoYMIKenDN6In6ReiGF8jaYoGqmWKDVBdGGMDIZyNIq+VdhgtAB1EyNFHJU1
        jGM0ir9dackL+PIsHbzJH8s/P/8RfUsKIL6/ZHbn3nKMxLH/8kjtxp5ScAA=
        "#;
        let cert_bytes = base64_decode_ignore_ws(cert_b64).unwrap();
        // From the cert above.
        let right_subject_key: Ed25519Identity = "HqbeSrmHyLfDBpz5OLb3eimg4/xEoY/0xPRYPgFvPtg"
            .parse::<Ed25519Public>()
            .unwrap()
            .into();
        // From `ed25519()` test above.
        let wrong_subject_key: Ed25519Identity = "WVIPQ8oArAqLY4XzkcpIOI6U8KsUJHBQhG8SC57qru0"
            .parse::<Ed25519Public>()
            .unwrap()
            .into();
        // decode and check correct type and key
        let cert = UnvalidatedEdCert::from_vec(cert_bytes, Pos::None)
            .unwrap()
            .check_cert_type(tor_cert::CertType::IDENTITY_V_SIGNING)
            .unwrap()
            .check_subject_key_is(&right_subject_key)
            .unwrap();
        // check wrong type.
        assert!(
            cert.clone()
                .check_cert_type(tor_cert::CertType::RSA_ID_X509)
                .is_err()
        );
        // check wrong key.
        assert!(cert.check_subject_key_is(&wrong_subject_key).is_err());
        // Try an invalid object that isn't a certificate.
        let failure = UnvalidatedEdCert::from_vec(vec![1, 2, 3], Pos::None);
        assert!(failure.is_err());
    }
    #[test]
    fn fingerprint() -> Result<()> {
        use tor_llcrypto::pk::rsa::RsaIdentity;
        let fp1 = "7467 A97D 19CD 2B4F 2BC0 388A A99C 5E67 710F 847E";
        let fp2 = "7467A97D19CD2B4F2BC0388AA99C5E67710F847E";
        let fp3 = "$7467A97D19CD2B4F2BC0388AA99C5E67710F847E";
        let fp4 = "$7467A97D19CD2B4F2BC0388AA99C5E67710F847E=fred";
        let k = hex::decode(fp2).unwrap();
        let k = RsaIdentity::from_bytes(&k[..]).unwrap();
        assert_eq!(RsaIdentity::from(fp1.parse::<SpFingerprint>()?), k);
        assert_eq!(RsaIdentity::from(fp2.parse::<SpFingerprint>()?), k);
        assert!(fp3.parse::<SpFingerprint>().is_err());
        assert!(fp4.parse::<SpFingerprint>().is_err());
        assert!(fp1.parse::<Fingerprint>().is_err());
        assert_eq!(RsaIdentity::from(fp2.parse::<Fingerprint>()?), k);
        assert!(fp3.parse::<Fingerprint>().is_err());
        assert!(fp4.parse::<Fingerprint>().is_err());
        assert_eq!(Fingerprint(k).to_string(), fp2);
        assert!(fp1.parse::<LongIdent>().is_err());
        assert_eq!(RsaIdentity::from(fp2.parse::<LongIdent>()?), k);
        assert_eq!(RsaIdentity::from(fp3.parse::<LongIdent>()?), k);
        assert_eq!(RsaIdentity::from(fp4.parse::<LongIdent>()?), k);
        assert!("xxxx".parse::<Fingerprint>().is_err());
        assert!("ffffffffff".parse::<Fingerprint>().is_err());
        let fp_b64 = "dGepfRnNK08rwDiKqZxeZ3EPhH4";
        assert_eq!(RsaIdentity::from(fp_b64.parse::<Base64Fingerprint>()?), k);
        assert_eq!(Base64Fingerprint(k).to_string(), fp_b64);
        Ok(())
    }
    #[test]
    fn nickname() -> anyhow::Result<()> {
        let n: Nickname = "Foo".parse()?;
        assert_eq!(n.as_str(), "Foo");
        assert_eq!(n.to_string(), "Foo");
        let word = "Untr1gonometr1cally";
        assert_eq!(word.len(), 19);
        let long: Nickname = word.parse()?;
        assert_eq!(long.as_str(), word);
        let too_long = "abcdefghijklmnopqrstuvwxyz";
        let not_ascii = "Eyjafjallajökull";
        let too_short = "";
        let other_invalid = "contains space";
        assert!(not_ascii.len() <= 19);
        assert!(too_long.parse::<Nickname>().is_err());
        assert!(not_ascii.parse::<Nickname>().is_err());
        assert!(too_short.parse::<Nickname>().is_err());
        assert!(other_invalid.parse::<Nickname>().is_err());
        Ok(())
    }
    /// Test for both `Hostname` and `InternetHost`
    #[test]
    fn hostname() {
        use std::net::IpAddr;
        // Test a string that we should treat as a valid hostname.
        let chk_name = |s: &str| {
            let n: Hostname = s.parse().expect(s);
            assert_eq!(n.as_str(), s);
            assert_eq!(n.to_string(), s);
            assert_eq!(s.parse::<InternetHost>().expect(s), InternetHost::Name(n));
        };
        // Test a string that looks like it could be an address or a hostname.
        // We parse those as addresses.
        let chk_either = |s: &str| {
            let h: InternetHost = s.parse().expect(s);
            let a: IpAddr = s.parse().expect(s);
            assert_eq!(h, InternetHost::IpAddr(a), "{s:?}");
            assert_eq!(h.to_string(), a.to_string(), "{s:?}");
        };
        // Test a string that's an address, and isn't a valid hostname.
        let chk_addr = |s: &str| {
            let _: InvalidHostname = s.parse::<Hostname>().expect_err(s);
            chk_either(s);
        };
        // Test a string that we should reject.
        let chk_bad = |s: &str| {
            let _: InvalidHostname = s.parse::<Hostname>().expect_err(s);
            let _: InvalidInternetHost = s.parse::<InternetHost>().expect_err(s);
        };
        chk_name("foo.bar");
        chk_name("localhost");
        chk_name("tor.invalid");
        chk_name("example.com");
        // Unarguably invalid.
        chk_bad("");
        chk_bad("foo bar");
        chk_bad("foo..bar");
        chk_bad("foo.-bar");
        chk_bad(" foo.bar ");
        chk_bad("[::1]");
        // Strings that some IP address parsers accept as addresses,
        // but which are also valid hostnames according to RFC1123.
        //
        // We reject them rather than processing of them as hostnames,
        // exposing downstream software to possible strangeness.
        chk_bad("1");
        chk_bad("127.0.0.023");
        // No-one thinks this is a valid IP address but we reject it as a hostname too,
        // even though it's syntactically legal per RFC1123, because it's quite bad.
        chk_bad("1.2.3.4.5");
        chk_either("0.0.0.0");
        chk_either("127.0.0.1");
        chk_addr("::");
        chk_addr("::1");
        chk_addr("2001:0db8:85a3:0000:0000:8a2e:0370:7334");
        chk_addr("::ffff:192.0.2.3"); // IPv6-mapped IPv4 address
    }
    #[test]
    fn contact_info() -> anyhow::Result<()> {
        use encode::NetdocEncodable;
        use parse2::{ParseInput, parse_netdoc};
        const S: &str = "some relay operator";
        let n: ContactInfo = S.parse()?;
        assert_eq!(n.as_str(), S);
        assert_eq!(n.to_string(), S);
        let bad = |s: &str| {
            let _: InvalidContactInfo = s.parse::<ContactInfo>().unwrap_err();
        };
        bad(" starts with space");
        bad("contains\nnewline");
        #[derive(PartialEq, Debug, Deftly)]
        #[derive_deftly(NetdocParseable, NetdocEncodable)]
        struct TestDoc {
            pub intro: (),
            pub contact: ContactInfo,
        }
        let roundtrip = |s: &str| -> anyhow::Result<()> {
            let doc = TestDoc {
                intro: (),
                contact: s.parse()?,
            };
            let mut enc = NetdocEncoder::new();
            doc.encode_unsigned(&mut enc)?;
            let enc = enc.finish()?;
            let reparsed = parse_netdoc::<TestDoc>(&ParseInput::new(&enc, "<test>"))?;
            assert_eq!(doc, reparsed);
            Ok(())
        };
        roundtrip("normal")?;
        roundtrip("trailing  white space  ")?;
        roundtrip("wtf is this allowed in \x03 netdocs\r")?; // TODO torspec#396
        Ok(())
    }
    /// Round trip test for [`NumericBoolean`] ensuring that `0` is false,
    /// `1` is true, and other things fail.
    #[test]
    fn numeric_boolean() {
        let chk = |s: &str| {
            assert_eq!(NumericBoolean::from_str(s).expect(s).to_string(), s);
        };
        chk("0");
        chk("1");
        // Testing this because it is not a u8.
        assert!(NumericBoolean::from_str("10000").is_err());
    }
    /// Test that ensures SpFingerprint matches the 10x4 requirement.
    #[test]
    fn sp_fingerprint() {
        use derive_deftly::Deftly;
        use tor_llcrypto::pk::rsa::RsaIdentity;
        use crate::parse2::ErrorProblem;
        #[derive(Deftly)]
        #[derive_deftly(NetdocParseable)]
        struct Wrapper {
            #[deftly(netdoc(single_arg))]
            fingerprint: SpFingerprint,
        }
        /// Small helper to parse an [`SpFingerprint`].
        fn parse2(s: &str) -> std::result::Result<SpFingerprint, ErrorProblem> {
            use crate::parse2::{self, ParseInput};
            let s = format!("fingerprint {s}\n");
            parse2::parse_netdoc::<Wrapper>(&ParseInput::new(&s, ""))
                .map(|x| x.fingerprint)
                .map_err(|x| x.problem)
        }
        // Test a valid one.
        assert_eq!(
            parse2(&vec!["ABAB"; 10].join(" ")).unwrap(),
            SpFingerprint(RsaIdentity::from_bytes(&[0xAB; 20]).unwrap())
        );
        // Test a valid one with tail.
        assert_eq!(
            parse2(&vec!["ABAB"; 11].join(" ")).unwrap(),
            SpFingerprint(RsaIdentity::from_bytes(&[0xAB; 20]).unwrap())
        );
        // Missing argument
        assert!(matches!(
            parse2(&vec!["ABAB"; 9].join(" ")).unwrap_err(),
            ErrorProblem::MissingArgument { .. }
        ));
        // Invalid argument.
        // In this case, we have string with a total length of 40 but with
        // one pair having 6 characters and another one having 2 as a proof
        // of that.
        assert!(matches!(
            parse2("0000 000000 00 0000 0000 0000 0000 0000 0000 0000").unwrap_err(),
            ErrorProblem::InvalidArgument { .. }
        ));
        // And of course invalid hex should fail too.
        assert!(matches!(
            parse2(&vec!["ZZZZ"; 10].join(" ")).unwrap_err(),
            ErrorProblem::InvalidArgument { .. }
        ));
    }
}