[tor-bugs] #28848 [Obfuscation/Snowflake]: Document Snowflake broker implementation

[Tor Bug Tracker & Wiki]

#28848: Document Snowflake broker implementation
-------------------------------------------------+-------------------------
 Reporter:  ahf                                  |          Owner:  ahf
     Type:  project                              |         Status:
                                                 |  needs_review
 Priority:  Medium                               |      Milestone:
Component:  Obfuscation/Snowflake                |        Version:  Tor:
                                                 |  unspecified
 Severity:  Normal                               |     Resolution:
 Keywords:  snowflake, tor-pt, network-team-     |  Actual Points:  2
  roadmap-2019-Q1Q2                              |
Parent ID:                                       |         Points:  8
 Reviewer:  cohosh, arma                         |        Sponsor:
                                                 |  Sponsor19
-------------------------------------------------+-------------------------

Comment (by cohosh):

 Looking good! Here's some comments:

 === Dependencies
 - Let's keep track in the documentation of the current required version of
 Go needed to build the broker. This could be put in the Go Dependencies
 section.


 === Source code documentation
 - I think one of the goals of this documentation should also be for
 someone to be able to look at it and then implement their own client and
 proxies that can interface with the broker without having to look at the
 existing client and proxy code. As such, we can be more precise about how
 to use each of these handlers. More specifically, does the client/proxy
 make a GET or a POST request when interacting with the handlers, and are
 there any request headers that are necessary? For example: the
 '''/proxy''' handler expects the {{{X-Session-ID}}} header, and is
 implemented in proxy-go as a {{{POST}}} request with no body.

 - Maybe we should mention that the timeout is currently 10s?

 - We could have another section for command line arguments:
 {{{
 Usage of ./broker:
   -acme-email string
         optional contact email for Let's Encrypt notifications
   -acme-hostnames string
         comma-separated hostnames for TLS certificate
   -addr string
         address to listen on (default ":443")
   -disable-tls
         don't use HTTPS
 }}}

 - In the '''/answer handler''' section, it says {{{If the client was too
 slow to send its offer}}} but it should be if the *snowflake proxy* is too
 slow.

 - Also in '''/answer handler''': We might want to expand on what "bogus
 answer" means here. I think it's simply if ioutil.ReadAll failed. I don't
 think there's any sort of mediation or sanitization of the actual Session
 Descriptor Answer.

 - Was the question about crawling ever answered? I can't think of a very
 good reason not to allow it. Even if censors were crawling the web for
 Snowflake brokers, they could get this information much more easily just
 from the source code. I think because of domain fronting we do not need to
 keep broker locations a secret. Perhaps if we are later doing something
 more sneaky with partitioning snowflakes and distributing them with
 something like Salmon or Hyphae we need to be careful about a crawler
 possibly gaining access to that information. In any case, my understanding
 of robots.txt is that is suggests to web crawlers not to crawl but doesn't
 have any actual security guarantees. So maybe we do not care one way or
 the other.

 === Metrics
 - Let's give the units for the round trip estimate. We might even want to
 add this to the debug output.

 === Other notes

 I fixed some minor typos here: https://github.com/ahf/snowflake-
 notes/commit/fb4304a7df08c6ddeeb103f38fc9103721a20cd9

--
Ticket URL: <https://trac.torproject.org/projects/tor/ticket/28848#comment:11>
Tor Bug Tracker & Wiki <https://trac.torproject.org/>
The Tor Project: anonymity online