Filename: 132-browser-check-tor-service.txt Title: A Tor Web Service For Verifying Correct Browser Configuration Version: $Revision: 15122 $ Last-Modified: $Date: 2008-06-11 06:34:07 +0100 (Wed, 11 Jun 2008) $ 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 implementation of the service consists of a series of test pages launched from a home page. When the browser requests the image embedded in each test page the request for the image is intercepted by Tor, which serves the image itself. Each image has an text informing the user that non-display of the image means the test has probably failed. The web page containing the image allows the user to click a link to check if the test has passed, and if so to proceed to the next test. The test service can offer a manual test sequence and an automated test sequence. In the former, the user clicks through each test and is informed if a test has failed (at which point the testing ends and they are advised how to remedy the problem). In the latter, the test service supplies a html refresh tag in the pages it serves. This tells the browser to check the result of the test a configurable number of seconds after loading the test page. It is worth noting that in the case of tests 1 and 2 described below Tor will know almost instantly whether the test has passed or not, this is because it should take only a second or two for Tor to serve the image to the browser if the browser is properly configured. This makes an automated test a safe option even for misconfigured browsers. 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.html. 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'). The tests are presented in the order in which each piece of browser functionality can be isolated, tested and then used as a basis for a subsequent test. The test service first establishes that the browser is configured to connect to Tor properly. It then tests whether the browser is leaking DNS requests. It finally tests that the user's Tor installation can connect to the internet. 1. 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. The token [random ip] is a randomly generated, non-local, non-private IP address. If Tor sees a SOCKS request with [random ip] as its destination address and the test service is enabled, it marks the connection as TEST_PURPOSE_AP and allows the browser to proceed as normal. This will enable Tor to serve the browser's subsequent HTTP request without requiring the construction of a circuit. Once 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. If the browser's 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. If the browser is configured to use Tor as an HTTP proxy, Tor will respond to the HTTP GET request with an image warning of this problem. 2. 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 Tor sees a SOCKS request with [uniquesessionid] as its destination address and the test service is enabled, it marks the connection as TEST_PURPOSE_AP and allows the client to proceed as normal. This will enable Tor to serve the browser's subsequent HTTP request without requiring the construction of a circuit. Once 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. 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. In this test case, Tor will not mark the SOCKS request connection as TEST_PURPOSE_AP. Instead Tor will build a circuit as normal. Once the circuit is built, Tor will accept the HTTP request from the browser. (This is the way Tor behaves already). Once 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. Implementation Issues: We need to ensure the user receives some assurance that the test page they are viewing was actually served by Tor. Controllers are best placed to provide this by issuing a message to the user when Tor notifies it via a 'status event' that the page was requested and served. The user will receive this notification when they open the test page in their browser. The controller could also receive a status event when Tor determines that each or all of the test images have been successfully served. This will provide additional confirmation to the user that their browser is correctly configured. The controller should assign a random port for the service so that it cannot be guessed easily by an external attacker. Open Issues: 1.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. The Tor client can serve the image in test 3 if it has determined that a circuit has been successfully built. 2. 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 port. 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.