1  Building and signing netdocs
 2  ============================
 3  
 4  We need to be able to create HS descriptors.  These are a kind of netdoc
 5  (dir-spec.txt s1.2, 1.3).
 6  
 7  Our tor-netdoc crate has code for parsing these.  Internally, in
 8  `tor_netdoc::parse`, there are `SectionRules` which are used for
 9  dismembering an incoming document.)  This is not done with types
10  structs with fields; rather, parsing into a dynamic data structure
11  indexed by values of a C-like enum, controlled by `SectionRules`.
12  I propose to not reuse `SectionRules`.
13  
14  (In this design sketch lifetimes, generic bounds, etc., are often omitted.)
15  
16  ## Proposed internal API
17  
18  (Now moved to `crates/tor-netdoc/src/build.rs`.)
19  
20  ## Proposed public API
21  
22  ```rust
23  // maybe derived with derive_builder? but the "built" struct is private
24  pub struct HsDescriptorBuilder<'b> {
25      // Crypto keys we need to use
26      k_desc_sign: Option<&'b ed25519::ExpandedSecretKey>,
27  
28      // fields to go in outer wrapper
29      descriptor_lifetime: Option<LifetimeMinutes>, // err, type TBD
30      ...
31      ...
32      // fields to go in layer 2 plaintest
33      single_onion_service: bool,
34      ...
35  }
36  
37  impl HsDescriptorBuilder {
38      // setters for everything, maybe taking borrowed values where relevant
39      /// setter
40      pub fn single_onion_service(&mut self, single_onion_service: bool);
41  }
42  
43  impl NetdocBuilder for HsDescriptorBuilder;
44  ```
45  
46  ## Proposed generic API for documents
47  
48  ```rust
49  pub trait NetdocBuilder {
50      fn build_sign(self) -> Result<NetdocText<Self>, >;
51  }
52  
53  ```
54  
55  ## Imagined implementation
56  
57  ```rust
58  impl NetdocBuilder for HsDescriptorBuilder {
59      fn build_sign(self /* or &self? */) -> Result<NetdocText<Self>, > {
60          construct the L2 plaintext with NetdocBuilder
61          construct the encryption key (using fields from swlf)
62          encrypt
63          construct the L1 plaintext with NetdocBuilder
64          encrypt
65          Construct the L0 plaintext.
66          sign it with the provided key.
67          eventually return the final NetdocText from NetdocBuilder.finish()
68      }
69  }
70  ```