commit 521eb4d4d6d76a1d57d3c8fc5c3a8261c171ea4e Author: David Fifield david@bamsoftware.com Date: Mon Jul 19 09:01:17 2021 -0600
Add info about rendezvous methods to client README. --- client/README.md | 56 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 56 insertions(+)
diff --git a/client/README.md b/client/README.md index aed11c3..0680408 100644 --- a/client/README.md +++ b/client/README.md @@ -52,3 +52,59 @@ To bootstrap Tor, run: tor -f torrc ``` This should start the client plugin, bootstrapping to 100% using WebRTC. + +### Registration methods + +The Snowflake client supports a few different ways of communicating with the broker. +This initial step is sometimes called rendezvous. + +#### Domain fronting HTTPS + +For domain fronting rendezvous, use the `-url` and `-front` command-line options together. +[Domain fronting](https://www.bamsoftware.com/papers/fronting/) +hides the externally visible domain name from an external observer, +making it appear that the Snowflake client is communicating with some server +other than the Snowflake broker. + +* `-url` is the HTTPS URL of a forwarder to the broker, on some service that supports domain fronting, such as a CDN. +* `-front` is the domain name to show externally. It must be another domain on the same service. + +Example: +``` +-url https://snowflake-broker.torproject.net.global.prod.fastly.net/ \ +-front cdn.sstatic.net \ +``` + +#### AMP cache + +For AMP cache rendezvous, use the `-url`, `-ampcache`, and `-front` command-line options together. +[AMP](https://amp.dev/documentation/) is a standard for web pages for mobile computers. +An [AMP cache](https://amp.dev/documentation/guides-and-tutorials/learn/amp-caches-and-cors...) +is a cache and proxy specialized for AMP pages. +The Snowflake broker has the ability to make its client registration responses look like AMP pages, +so it can be accessed through an AMP cache. +When you use AMP cache rendezvous, it appears to an observer that the Snowflake client +is accessing an AMP cache, or some other domain operated by the same organization. +You still need to use the `-front` command-line option, because the +[format of AMP cache URLs](https://amp.dev/documentation/guides-and-tutorials/learn/amp-caches-and-cors...) +would otherwise reveal the domain name of the broker. + +There is only one AMP cache that works with this option, +the Google AMP cache at https://cdn.ampproject.org/. + +* `-url` is the HTTPS URL of the broker. +* `-ampcache` is `https://cdn.ampproject.org/%60. +* `-front` is any Google domain, such as `www.google.com`. + +Example: +``` +-url https://snowflake-broker.torproject.net/ \ +-ampcache https://cdn.ampproject.org/ \ +-front www.google.com \ +``` + +#### Direct access + +It is also possible to access the broker directly using HTTPS, without domain fronting, +for testing purposes. This mode is not suitable for circumvention, because the +broker is easily blocked by its address.