robust_time_syncing.md

@@ -111,6 +111,60 @@ tl;dr:
 
  - Else, when the user chooses to hide Tor, ask them fix the time zone and clock manually.
 
+Reasons for failure of the automatic time sync
+----------------------------------------------
+
+### Symptoms
+
+*   A) HTTP connection times out
+
+*   B) no route to host
+
+*   C) DNS resolution fails
+
+*   D) DNS resolution times out
+
+*   E) invalid HTTPS certificate (if we allow redirects, otherwise cannot possibly happen because the test URL is cleartext HTTP)
+
+*   F) HTTP error code
+
+*   G) missing HTTP `Date` header
+
+*   H) response is not the expected content (so likely does not come from the intended server
+
+### Reasons
+
+*   captive portal working as intended: E, F, G, H
+
+*   needs proxy configuration: A, B, C, D. Or, less probably: F
+
+*   broken IP connectivity: B
+
+*   upstream DNS is giving incorrect answers (without being a captive portal): anything can happen
+
+*   slow network: A, D
+
+*   unreliable network: A, B, C, D
+
+*   mangling the network traffic upstream without being a "legitimate" captive portal: anything can happen
+    *   e.g. not very clever malicious active attacker: a more clever attacker would give the expected reply and give Tails the wrong date
+
+    *   network censor
+
+### Observations
+
+*   captive portal is hard to distinguish from other "network mangler"
+    *   But maybe in some cases we might know for sure e.g. when something like [https://tools.ietf.org/id/draft-nottingham-http-new-status-01.html#status-code](https://tools.ietf.org/id/draft-nottingham-http-new-status-01.html#status-code) is implemented; or for 407 Proxy Authentication Required.
+
+    *   NetworkManager does not bother checking for status code 428.
+
+    *   See also [https://github.com/ooni/spec/blob/master/nettests/ts-010-captive-portal.md#version-040-implemented-in-mk-but-not-deployed](https://github.com/ooni/spec/blob/master/nettests/ts-010-captive-portal.md#version-040-implemented-in-mk-but-not-deployed)
+
+*   a network where a proxy is needed can be a realistic example of such a network mangler
+    *   ⇒ if we want to support this use case, when we see a captive portal, we must still propose the user to configure their proxy
+
+*   our time-checking code should return, in case of errors, a list of possible reasons for failure
+
 Old plan
 ========