Lines Matching +full:no +full:- +full:proxy
1 # Proxy support in Chrome
3 This document establishes basic proxy terminology and describes Chrome-specific
4 proxy behaviors.
8 ## Proxy server identifiers
10 A proxy server is an intermediary used for network requests. A proxy server can
11 be described by its address, along with the proxy scheme that should be used to
17 The PAC format is how one names a proxy server in [Proxy
18 auto-config](https://en.wikipedia.org/wiki/Proxy_auto-config) scripts. For
20 * `PROXY foo:2138`
30 The port number is optional in both formats. When omitted, a per-scheme default
33 See the [Proxy server schemes](#Proxy-server-schemes) section for details on
37 formatted proxy server identifiers. However outside of Chrome, proxy servers
38 are generally identified less precisely by just an address -- the proxy
41 In Windows' proxy settings there are host and port fields for the
42 "HTTP", "Secure", "FTP", and "SOCKS" proxy. With the exception of "SOCKS",
43 those are all identifiers for insecure HTTP proxy servers (proxy scheme is
46 ## Proxy resolution
51 to send the request to. This can be either a proxy server, or the target host.
53 This is called proxy resolution. The input to proxy resolution is a URL, and
54 the output is an ordered list of [proxy server
55 identifiers](#Proxy-server-identifiers).
59 * [Manual proxy settings](#Manual-proxy-settings) - proxy resolution is defined
61 URL scheme to proxy server identifier(s), and a list of proxy bypass rules for
62 when to go DIRECT instead of using the mapped proxy.
64 * PAC script - proxy resolution is defined using a JavaScript program, that is
65 invoked whenever fetching a URL to get the list of proxy server identifiers
68 * Auto-detect - the WPAD protocol is used to probe the network (using DHCP/DNS)
71 ## Proxy server schemes
73 When using an explicit proxy in the browser, multiple layers of the network
75 of the proxy scheme are:
77 * Is communication to the proxy done over a secure channel?
78 * Is name resolution (ex: DNS) done client side, or proxy side?
79 * What authentication schemes to the proxy server are supported?
80 * What network traffic can be sent through the proxy?
82 Chrome supports these proxy server schemes:
84 * [DIRECT](#DIRECT-proxy-scheme)
85 * [HTTP](#HTTP-proxy-scheme)
86 * [HTTPS](#HTTPS-proxy-scheme)
87 * [SOCKSv4](#SOCKSv4-proxy-scheme)
88 * [SOCKSv5](#SOCKSv5-proxy-scheme)
90 ### DIRECT proxy scheme
96 This is a pseudo proxy scheme that indicates instead of using a proxy we are
99 It is imprecise to call this a "proxy server", but it is a convenient abstraction.
101 ### HTTP proxy scheme
104 * Example identifier (PAC): `PROXY proxy:8080`, `proxy` (non-standard; don't use)
105 * Example identifiers (URI): `http://proxy:8080`, `proxy:8080` (can omit scheme)
107 Generally when one refers to a "proxy server" or "web proxy", they are talking
108 about an HTTP proxy.
110 When using an HTTP proxy in Chrome, name resolution is always deferred to the
111 proxy. HTTP proxies can proxy `http://`, `https://`, `ws://` and `wss://` URLs.
113 Communication to HTTP proxy servers is insecure, meaning proxied `http://`
115 HTTP proxy, the TLS exchange is forwarded through the proxy using the `CONNECT`
116 method, so end-to-end encryption is not broken. However when establishing the
117 tunnel, the hostname of the target URL is sent to the proxy server in the
123 ### HTTPS proxy scheme
126 * Example identifier (PAC): `HTTPS proxy:8080`
127 * Example identifier (URI): `https://proxy:8080`
129 This works like an [HTTP proxy](#HTTP-proxy-scheme), except the
130 communication to the proxy server is protected by TLS, and may negotiate
133 Because the connection to the proxy server is secure, https:// requests
134 sent through the proxy are not sent in the clear as with an HTTP proxy.
142 regular HTTP proxy due to higher connection limits (HTTP/1.1 proxies in Chrome
148 Specifying an HTTPS proxy is generally not possible through system proxy
149 settings. Instead, one must use either a PAC script or a Chrome proxy setting
153 proxies](http://dev.chromium.org/developers/design-documents/secure-web-proxy)
154 for tips on how to run and test against an HTTPS proxy.
156 ### SOCKSv4 proxy scheme
159 * Example identifiers (PAC): `SOCKS4 proxy:8080`, `SOCKS proxy:8080`
160 * Example identifier (URI): `socks4://proxy:8080`
162 SOCKSv4 is a simple transport layer proxy that wraps a TCP socket. Its use
164 handshake when connecting the TCP socket (to the proxy), the rest of the
167 No proxy authentication methods are supported for SOCKSv4.
169 When using a SOCKSv4 proxy, name resolution for target hosts is always done
173 There are extensions to SOCKSv4 that allow for proxy side name resolution, and
180 ### SOCKSv5 proxy scheme
183 * Example identifier (PAC): `SOCKS5 proxy:8080`
184 * Example identifiers (URI): `socks://proxy:8080`, `socks5://proxy:8080`
186 [SOCKSv5](https://tools.ietf.org/html/rfc1928) is a transport layer proxy that
187 wraps a TCP socket, and allows for name resolution to be deferred to the proxy.
189 In Chrome when a proxy's scheme is set to SOCKSv5, name resolution is always
190 done proxy side (even though the protocol allows for client side as well). In
191 Firefox client side vs proxy side name resolution can be configured with
192 `network.proxy.socks_remote_dns`; Chrome has no equivalent option and will
193 always use proxy side resolution.
195 No authentication methods are supported for SOCKSv5 in Chrome (although some do
198 A handy way to create a SOCKSv5 proxy is with `ssh -D`, which can be used to
201 In Chrome SOCKSv5 is only used to proxy TCP-based URL requests. It cannot be
204 ## Manual proxy settings
206 The simplest way to configure proxy resolution is by providing a static list of
209 1. A mapping of URL schemes to [proxy server identifiers](#Proxy-server-identifiers).
210 2. A list of [proxy bypass rules](#Proxy-bypass-rules)
212 We refer to this mode of configuration as "manual proxy settings".
214 Manual proxy settings can succinctly describe setups like:
216 * Use proxy `http://foo:8080` for all requests
217 * Use proxy `http://foo:8080` for all requests except those to a `google.com`
219 * Use proxy `http://foo:8080` for all `https://` requests, and proxy
222 Although manual proxy settings are a ubiquituous way to configure proxies
223 across platforms, there is no standard representation or feature set.
225 Chrome's manual proxy settings most closely resembles that of WinInet. But it
226 also supports idioms from other platforms -- for instance KDE's notion of
230 When defining manual proxy settings in Chrome, we specify three (possibly
231 empty) lists of [proxy server identifiers](#Proxy-server-identifiers).
233 * proxies for HTTP - A list of proxy server identifiers to use for `http://`
234 requests, if non-empty.
235 * proxies for HTTPS - A list of proxy server identifiers to use for
236 `https://` requests, if non-empty.
237 * other proxies - A list of proxy server identifiers to use for everything
240 There are a lot of ways to end up with manual proxy settings in Chrome
244 `--proxy-server=XXX` (and optionally `--proxy-bypass-list=YYY`)
246 Example: To use proxy `http://foo:8080` for all requests we can launch
247 Chrome with `--proxy-server="http://foo:8080"`. This translates to:
249 * proxies for HTTP - *empty*
250 * proxies for HTTPS - *empty*
251 * other proxies - `http://foo:8080`
253 With the above configuration, if the proxy server was unreachable all requests
256 `--proxy-server="http://foo:8080,direct://"` (note the comma separated list).
259 * proxies for HTTP - *empty*
260 * proxies for HTTPS - *empty*
261 * other proxies - `http://foo:8080`, `direct://`
263 If instead we wanted to proxy only `http://` URLs through the
264 HTTPS proxy `https://foo:443`, and have everything else use the SOCKSv5 proxy
266 `--proxy-server="http=https://foo:443;socks=socks5://mysocks:1080"`. This now
269 * proxies for HTTP - `https://foo:443`
270 * proxies for HTTPS - *empty*
271 * other proxies - `socks5://mysocks:1080`
273 The command line above uses WinInet's proxy map format, with some additional
276 * Instead of naming proxy servers by just a hostname:port, you can use Chrome's
277 URI format for proxy server identifiers. In other words, you can prefix the
278 proxy scheme so it doesn't default to HTTP.
280 subsequent proxy list can include proxies of any scheme, however if the
283 ### Mapping WebSockets URLs to a proxy
285 [Manual proxy settings](#Manual-proxy-settings) don't have mappings for `ws://`
288 Selecting a proxy for these URL schemes is a bit different from other URL
291 * If "other proxies" is non-empty use it
292 * If "proxies for HTTPS" is non-empty use it
300 ### Proxy credentials in manual proxy settings
302 Most platforms' [manual proxy settings](#Manual-proxy-settings) allow
303 specifying a cleartext username/password for proxy sign in. Chrome does not
304 implement this, and will not use any credentials embedded in the proxy
307 Proxy authentication will instead go through the ordinary flow to find
310 ## Proxy bypass rules
312 In addition to specifying three lists of [proxy server
313 identifiers](#proxy-server-identifiers), Chrome's [manual proxy
314 settings](#Manual-proxy-settings) lets you specify a list of "proxy bypass
317 This ruleset determines whether a given URL should skip use of a proxy all
318 together, even when a proxy is otherwise defined for it.
321 "no proxy list".
323 Proxy bypass rules can be written as an ordered list of strings. Ordering
326 When manual proxy settings are specified from the command line, the
327 `--proxy-bypass-list="RULES"` switch can be used, where `RULES` is a semicolon
331 supports. They can be used when defining a Chrome manual proxy settings from
334 When using system proxy settings, one should use the platform's rule format and
348 * `foobar.com` - Matches URL of any scheme and port, whose normalized host is
350 * `*foobar.com` - Matches URL of any scheme and port, whose normalized host
352 * `*.org:443` - Matches URLs of any scheme, using port 443 and whose top level
354 * `https://x.*.y.com:99` - Matches https:// URLs on port 99 whose normalized
368 * `.google.com` - Matches `calendar.google.com` and `foo.bar.google.com`, but
370 * `http://.google.com` - Matches only http:// URLs that are a subdomain of `google.com`.
387 * `[::1]` - Matches any URL to the IPv6 loopback address.
388 * `[0:0::1]` - Same as above
389 * `http://[::1]:99` - Matches any http:// URL to the IPv6 loopback on port 99
401 literals](#Meaning-of-IP-address-range-bypass-rules).
417 literals](#Meaning-of-IP-address-range-bypass-rules).
422 * `[fefe::]/40` -- WRONG! IPv6 literals must not be bracketed.
431 is a naive string search -- meaning that periods appearing *anywhere* count
435 the "Don't use proxy server for local (intranet) addresses" on Windows.
440 implicitly](#Implicit-bypass-rules).
445 <-loopback>
448 *Subtracts* the [implicit proxy bypass rules](#Implicit-bypass-rules)
453 use the proxy, this rule has the opposite effect and tells the browser to
454 instead *use* the proxy.
457 in a left-to-right order. `<-loopback>;127.0.0.1` has a subtly different effect
458 than `127.0.0.1;<-loopback>`.
462 The IP address range bypass rules in manual proxy settings applies only to URL
467 Say we have have configured a proxy for all requests, but added a bypass rule
469 to `192.168.1.5` in our setup) will the browser connect directly (bypass proxy)
472 It will go through the proxy.
475 actually does a name resolution for `foo`. Proxy resolution happens before
476 name resolution, and depending on what proxy scheme is subsequently chosen,
479 The usefulness of IP range proxy bypass rules is rather limited, as they only
482 If proxy decisions need to be made based on the resolved IP address(es) of a
487 Requests to certain hosts will not be sent through a proxy, and will instead be
491 whose host portion is either a localhost name or a link-local IP literal.
506 This concept of implicit proxy bypass rules is consistent with the
507 platform-level proxy support on Windows and macOS (albeit with some differences
508 due to their implementation quirks - see compatibility notes in
511 Why apply implicit proxy bypass rules in the first place? Certainly there are
514 ability to proxy it grants extra powers. This is [especially
516 proxy settings are externally controllable, as when using PAC scripts.
520 * Prior to M71 there were no implicit proxy bypass rules, except if using
521 [`--winhttp-proxy-resolver`](#winhttp_proxy_resolver-command-line-switch).
522 * In M71 Chrome applied implicit proxy bypass rules to PAC scripts
523 * In M72 Chrome generalized the implicit proxy bypass rules to manually
528 If you want traffic to `localhost` to be sent through a proxy despite the
529 security concerns, it can be done by adding the special proxy bypass rule
530 `<-loopback>`. This has the effect of _subtracting_ the implicit rules.
535 --proxy-bypass-list="<-loopback>"
538 Note that there currently is no mechanism to disable the implicit proxy bypass
539 rules when using a PAC script. Proxy bypass lists only apply to manual
541 proxy for localhost URLs.
543 ## Evaluating proxy lists (proxy fallback)
545 Proxy resolution results in a _list_ of [proxy server
546 identifiers](#Proxy-server-identifiers) to use for a
547 given request, not just a single proxy server identifier.
554 return "PROXY proxy1; HTTPS proxy2; SOCKS5 proxy3";
561 What proxy will Chrome use for connections to `www.example.com`, given that
562 we have a choice of three separate proxy server identifiers to choose from
573 Proxy fallback is stateful. The actual order of proxy attempts made be Chrome
574 is influenced by the past responsiveness of proxy servers.
577 resolves to a list of three proxy server identifiers:
582 left-to-right order.
587 means that `http://proxy1:80` is de-prioritized with respect to
588 other proxy server identifiers (including `direct://`) that are not marked as
599 What constitutes a "failure" when it comes to triggering proxy fallback depends
600 on the proxy type. Generally speaking, only connection level failures
601 are deemed eligible for proxy fallback. This includes:
603 * Failure resolving the proxy server's DNS
604 * Failure connecting a TCP socket to the proxy server
610 CONNECT tunnel as an error eligible for proxy fallback. This policy [resulted
614 establishment. The problem would occur when a working proxy fallback option
615 like DIRECT was given, since the failing proxy would then be marked as bad.
617 Currently there are no options to configure proxy fallback (including disabling
622 To investigate issues relating to proxy fallback, one can [collect a NetLog
624 chrome://net-export/](https://dev.chromium.org/for-testers/providing-network-details).
626 viewer](https://netlog-viewer.appspot.com/).
630 * The "Proxy" tab will show which proxies (if any) were marked as bad at the
632 * The "Events" tab notes what the resolved proxy list was, and what the
633 re-ordered proxy list was after taking into account bad proxies.
634 * The "Events" tab notes when a proxy is marked as bad and why (provided the
640 [chrome://net-internals/#proxy](chrome://net-internals/#proxy). Note the UI
687 There is currently no option to turn off sanitization of URLs passed to PAC
702 This API is [inherently ambiguous when used on multi-homed
703 hosts](#myIpAddress_myIpAddressEx_and-multi_homed-hosts), as such hosts can
708 ordered steps and short-circuiting once the first candidate IP is found:
722 Note that when searching for candidate IP addresses, link-local and loopback
723 addresses are skipped over. Link-local or loopback address will only be returned as a
724 last resort when no other IP address was found by following these steps.
735 extension](https://docs.microsoft.com/en-us/windows/desktop/winhttp/myipaddressex)
739 can return multiple IP addresses. It returns a string containing a semi-colon
741 no results (whereas `myIpAddress()` returns `127.0.0.1`).
748 interfaces](#myIpAddress_myIpAddressEx_and-multi_homed-hosts)
749 * Chrome does not return link-local or loopback addresses (except if no other
768 Note that short-circuiting happens whenever steps 1-3 find a candidate IP. So
770 public Internet, only those IPs will be returned, and steps 2-3 will not run.
772 ## myIpAddress() / myIpAddressEx() and multi-homed hosts
784 and may not address all use-cases.
789 Moreover, note that Chrome does not support the Firefox-specific
790 `pacUseMultihomedDNS` option, so adding that global to a PAC script has no
791 special side-effect in Chrome. Whereas in Firefox it reconfigures
797 Proxy resolving via PAC works differently on Android than other desktop Chrome
801 out-of-process as on Desktop Chrome. This architectural difference is
811 PAC, Android WebView's net code will see the proxy settings as being a
812 single HTTP proxy on `localhost`. The system localhost proxy will in turn
814 proxy. This translation has a number of effects, including what proxy
815 schemes are supported, the maximum connection limits, how proxy fallback
827 When a network context is configured to use a PAC script, proxy resolution will
837 * Are never fetched through a proxy
849 a long-lived Java Script context) will be assumed to be fresh until either:
853 * A user explicitly invalidates PAC through `chrome://net-internals#proxy`
855 Once considered stale, the PAC URL will be re-fetched the next time proxy
860 When the proxy settings are configured to use a PAC URL, and that PAC URL
861 cannot be fetched, proxy resolution will fallback to the next option, which is
864 * If using system proxy settings, and the platform supports fallback to manual
865 proxy settings (e.g. Windows), the specified manual proxy servers will be
867 * If using Chrome's proxy settings, and the PAC script was marked as
868 [mandatory](https://developer.chrome.com/extensions/proxy), fallback to
869 `DIRECT` is not permitted. Subsequent network requests will fail proxy
871 * Otherwise proxy resolution will silently fall back to `DIRECT`.
876 re-fetch it:
884 incoming proxy resolution request, so it will not trigger work when the browser
887 Similarly to successful fetches, the PAC URL will be also be re-fetched
888 whenever the network changes, the proxy settings change, or it was manually
889 invalidated via `chrome://net-internals#proxy`.
893 Note that UTF-8 is *not* the default interpretation of PAC response bodies.
897 1. The `charset` property of the HTTP response's `Content-Type`
899 3. Otherwise defaults to ISO-8859-1.
901 When setting the `Content-Type`, servers should prefer using a mime type of
902 `application/x-ns-proxy-autoconfig` or `application/x-javascript-config`.
905 ## Capturing a Net Log for debugging proxy resolution issues
907 Issues in proxy resolution are best investigated using a Net Log.
910 net-export](https://www.chromium.org/for-testers/providing-network-details),
915 3. In a new tab, navigate to `chrome://net-internals/#proxy` and click both
916 buttons ("Re-apply settings" and "Clear bad proxies").
922 Viewer](https://netlog-viewer.appspot.com/). See the next section for some tips
925 ## Analyzing Net Logs for proxy issues
927 Load saved Net Logs using [Net Log Viewer](https://netlog-viewer.appspot.com/).
929 ### Proxy overview tab
931 Start by getting a big-picture view of the proxy settings by clicking to the
932 "Proxy" tab on the left. This summarizes the proxy settings at the time the
935 * Does the _original_ proxy settings match expectation?
936 The proxy settings might be coming from:
938 * Command line flags (ex: `--proxy-server`)
939 …* (per-profile) Chrome extensions (ex: [chrome.proxy](https://developer.chrome.com/extensions/prox…
940 * (per-network) System proxy settings
942 * Was [proxy autodetect (WPAD)](#Web-Proxy-Auto_Discovery-WPAD) specified? In
946 * Internally, proxy settings are per-NetworkContext. The proxy
948 one associated with the Profile used to navigate to `chrome://net-export`. For
949 instance if the net-export was initiated from an Incognito window, it may
950 show different proxy settings here than a net-export capture initiated by a
951 non-Incognito window. When the net-export was triggered from command line
952 (`--log-net-log`) no particular NetworkContext is associated with the
953 capture and hence no proxy settings will be shown in this overview.
960 field trials. A find-in-page for `proxy` is a good starting point. Be on the lookout for
961 [`--winhttp-proxy-resolver`](#winhttp_proxy_resolver-command-line-switch) which
966 To deep dive into proxy resolution, switch to the Events tab.
970 trace the proxy resolution steps and outcome.
978 Network change events can also be key to understanding proxy issues. After
979 switching networks (ex VPN), the effective proxy settings, as well as content
980 of any PAC scripts/auto-detect can change.
982 ## Web Proxy Auto-Discovery (WPAD)
984 When configured to use WPAD (aka "autotmaticaly detect proxy settings"), Chrome
987 1. DHCP-based WPAD (option 252)
988 2. DNS-based WPAD
990 These are tried in order, however DHCP-based WPAD is only supported for Chrome
995 ### Chrome on macOS support for DHCP-based WPAD
997 Chrome on macOS does not support DHCP-based WPAD when configured to use
1000 However, macOS might perform DHCP-based WPAD and embed this discovered PAC URL
1001 as part of the system proxy settings. So effectively when Chrome is configured
1002 to "use system proxy settings" it may behave as if it supports DHCP-based WPAD.
1004 ### Dangers of DNS-based WPAD and DNS search suffix list
1006 DNS-based WPAD involves probing for the non-FQDN `wpad`. This means
1017 funnel the user's traffic through a proxy server of their choice. The
1021 Vulnerability](https://www.us-cert.gov/ncas/alerts/TA16-144A)
1023 ## --winhttp-proxy-resolver command line switch
1025 Passing the `--winhttp-proxy-resolver` command line argument instructs Chrome
1026 to use the system libraries for *one narrow part of proxy resolution*: evaluating
1031 can break Chrome extensions (`chrome.proxy` API), the interpretation of
1032 Proxy policies, hurt performance, and doesn't ensure full fidelity
1033 interpretation of system proxy settings.
1036 smilar meaning on other platforms (macOS), despite its Windows-specific naming.
1042 Although Chrome would like full fidelity with Windows proxy settings, there are
1043 limits to those integrations. Dependencies like NRPT for proxy
1044 resolution necessitate using Windows proxy resolution libraries directly