Merge pull request #529 from mirokuratczyk/master

Caveats for WebRTC and i18n in WebViews

MobileLibrary/Android/SampleApps/TunneledWebView/README.md

@@ -7,6 +7,27 @@ Overview
 TunneledWebView is a sample app that demonstrates embedding the Psiphon Library in
 an Android app. TunneledWebView proxies a WebView through the Psiphon tunnel.
 
+Caveats
+--------------------------------------------------------------------------------
+
+### i18n API Leaks Timezone
+
+The Internationalization API (i18n) provides websites, though a JavaScript API, with access to the timezone used by
+the user's browser (in this case WebView). This does not reveal the precise location of the user, but can be accurate
+enough to identify the city in which the user is located.
+
+The i18n API cannot be disabled without disabling JavaScript.
+
+### Untunneled WebRTC
+
+WebRTC requests do not use the configured proxy settings of a WebView. JavaScript must be disabled in a WebView to
+effectively disable WebRTC. If not disabled, WebRTC will leak the untunneled client IP address and the WebRTC connection
+may be performed entirely outside of the tunnel.
+
+One solution would be to use a WebRTC library which allows setting a proxy; or use 
+[Mozilla's GeckoView](https://wiki.mozilla.org/Mobile/GeckoView), which is a WebView alternative which allows disabling
+WebRTC.
+
 Integration
 --------------------------------------------------------------------------------
 

MobileLibrary/iOS/SampleApps/TunneledWebView/README.md

@@ -16,15 +16,29 @@ We use a slightly modified version of JiveAuthenticatingProtocol (https://github
 
 ## *\*\* Caveats \*\*\*
 
-### Challenges
+### i18n API Leaks Timezone
 
-***NSURLProtocol is only partially supported by UIWebView (https://bugs.webkit.org/show_bug.cgi?id=138169) and in 
-some versions of iOS audio and video are fetched out of process in mediaserverd and therefore are
-not intercepted by NSURLProtocol.***
+The Internationalization API (i18n) provides websites, though a JavaScript API, with access to the timezone used by
+the user's browser (in this case UIWebView). This does not reveal the precise location of the user, but can be accurate
+enough to identify the city in which the user is located.
+
+Like the "Untunneled WebRTC" issue mentioned below, the i18n API cannot be disabled without disabling JavaScript.         
+
+### NSURLProtocol Challenges
+
+***NSURLProtocol is only partially supported by UIWebView (https://bugs.webkit.org/show_bug.cgi?id=138169) and iOS,
+meaning that some network requests are made out of process and are consequently untunneled.***
+
+Below we address the exceptions we have encountered, but there may be more.
+
+### Untunneled Media
+
+***In some versions of iOS audio and video are fetched out of process in mediaserverd and therefore are not intercepted 
+by NSURLProtocol.***
 
 *In our limited testing iOS 9/10 leak and iOS 11 does not leak.*
 
-### Workarounds
+#### Workarounds
 
 ***It is worth noting that this fix is inexact and may not always work. If one has control over the HTML being rendered and resources being fetched with XHR it is preferable to alter 
 the media source URLs directly beforehand instead of relying on the javascript injection trick.***
@@ -60,6 +74,21 @@ to include a nonce generated for our injected javascript, which is [included in
 
 *Requests to localhost (`127.0.0.1`) should be [excluded from being proxied](https://github.com/Psiphon-Labs/psiphon-tunnel-core/blob/master/MobileLibrary/iOS/SampleApps/TunneledWebView/External/JiveAuthenticatingHTTPProtocol/JAHPAuthenticatingHTTPProtocol.m#L283-L287) so the system does not attempt to proxy loading the rewritten URLs. They will be correctly proxied through PsiphonTunnel's reverse proxy.*
 
+### Untunneled OCSP Requests
+
+See "Online Certificate Status Protocol (OCSP) Leaks" in [../../USAGE.md](../../USAGE.md).
+
+### Untunneled WebRTC
+
+WebRTC in UIWebView does not follow NSURLProtocol and cannot be disabled without disabling JavaScript. If not disabled, 
+WebRTC will leak the untunneled client IP address and the WebRTC connection may be performed entirely outside of the
+tunnel.
+
+One solution would be to use a WebRTC library which allows setting a proxy; or allows all requests to be intercepted, and
+subsequently proxied, through NSURLProtocol.
+
+More details can be found in this issue: https://github.com/OnionBrowser/OnionBrowser/issues/117.
+
 ## Configuring, Building, Running
 
 The sample app requires some extra files and configuration before building.