Filename: 132-browser-check-tor-service.txt Title: A Tor Web Service For Verifying Correct Browser Configuration Version: $Revision$ Last-Modified: $Date$ Author: Robert Hogan Created: 2008-03-08 Status: Draft Overview: Tor should operate a primitive web service on the loopback network device that tests the operation of user's browser, privacy proxy and Tor client. The tests are performed by serving unique, randomly generated elements in image URLs embedded in static HTML. The images are only displayed if the DNS and HTTP requests for them are routed through Tor, otherwise the 'alt' text may be displayed. The proposal assumes that 'alt' text is not displayed on all browsers so suggests that text and links should accompany each image advising the user on next steps in case the test fails. The service is primarily for the use of controllers, since presumably users aren't going to want to edit text files and then type something exotic like 127.0.0.1:9999 into their address bar. In the main use case the controller will have configured the actual port for the webservice so will know where to direct the request. It would also be the responsibility of the controller to ensure the webservice is available, and tor is running, before allowing the user to access the page through their browser. Motivation: This is a complementary approach to proposal 131. It overcomes some of the limitations of the approach described in proposal 131: reliance on a permanent, real IP address and compatibility with older versions of Tor. Unlike 131, it is not as useful to Tor users who are not running a controller. Objective: Provide a reliable means of helping users to determine if their Tor installation, privacy proxy and browser are properly configured for anonymous browsing. Proposal: When configured to do so, Tor should run a basic web service available on a configured port on 127.0.0.1. The purpose of this web service is to serve a number of basic test images that will allow the user to determine if their browser is properly configured and that Tor is working normally. The service can consist of a single web page with two columns. The left column contains images, the right column contains advice on what the display/non-display of the column means. The rest of this proposal assumes that the service is running on port 9999. The port should be configurable, and configuring the port enables the service. The service must run on 127.0.0.1. In all the examples below [uniquesessionid] refers to a random, base64 encoded string that is unique to the URL it is contained in. Tor only ever stores the most recently generated [uniquesessionid] for each URL, storing 3 in total. Tor should generate a [uniquesessionid] for each of the test URLs below every time a HTTP GET is received at 127.0.0.1:9999 for index.htm. The most suitable image for each test case is an implementation decision. Tor will need to store and serve images for the first and second test images, and possibly the third (see 'Open Issues'). 1. DNS Request Test Image This is a HTML element embedded in the page served by Tor at http://127.0.0.1:9999: If you can see
  this text, your browser's DNS requests are not being routed through Tor. If the browser's DNS request for [uniquesessionid] is routed through Tor, Tor will intercept the request and return 127.0.0.1 as the resolved IP address. This will shortly be followed by a HTTP request from the browser for http://127.0.0.1:9999/torlogo.jpg. This request should be served with the appropriate image. If the browser's DNS request for [uniquesessionid] is not routed through Tor the browser may display the 'alt' text specified in the html element. The HTML served by Tor should also contain text accompanying the image to advise users what it means if they do not see an image. It should also provide a link to click that provides information on how to remedy the problem. This behaviour also applies to the images described in 2. and 3. below, so should be assumed there as well. 2. Proxy Configuration Test Image This is a HTML element embedded in the page served by Tor at http://127.0.0.1:9999: If you can see
  this text, your browser is not configured to work with Tor. If the HTTP request for the resource [uniquesessionid].jpg is received by Tor it will serve the appropriate image in response. It should serve this image itself, without attempting to retrieve anything from the Internet. If Tor can identify the name of the proxy application requesting the resource then it could store and serve an image identifying the proxy to the user. 3. Tor Connectivity Test Image This is a HTML element embedded in the page served by Tor at http://127.0.0.1:9999: If you
  can see this text, your Tor installation cannot connect to the Internet. The referenced image should actually exist on the Tor project website. If Tor receives the request for the above resource it should remove the random base64 encoded digest from the request (i.e. [uniquesessionid]-) and attempt to retrieve the real image. Even on a fully operational Tor client this test may not always succeed. The user should be advised that one or more attempts to retrieve this image may be necessary to confirm a genuine problem. Open Issues: The final connectivity test relies on an externally maintained resource, if this resource becomes unavailable the connectivity test will always fail. Either the text accompanying the test should advise of this possibility or Tor clients should be advised of the location of the test resource in the main network directory listings. Any number of misconfigurations may make the web service unreachable, it is the responsibility of the user's controller to recognize these and assist the user in eliminating them. Tor can mitigate against the specific misconfiguration of routing HTTP traffic to 127.0.0.1 to Tor itself by serving such requests through the SOCKS port as well as the configured web service report. Now Tor is inspecting the URLs requested on its SOCKS port and 'dropping' them. It already inspects for raw IP addresses (to warn of DNS leaks) but maybe the behaviour proposed here is qualitatively different. Maybe this is an unwelcome precedent that can be used to beat the project over the head in future. Or maybe it's not such a bad thing, Tor is merely attempting to make normally invalid resource requests valid for a given purpose.