Proxy auto-config: Difference between revisions

Revision as of 22:21, 11 October 2017

Latest revision as of 13:41, 15 April 2025

(117 intermediate revisions by 77 users not shown)

Line 1:

{{Short description|Configuration file for computer networking}}

{{About|the browser file||PAC (disambiguation){{!}}PAC}}

A '''proxy auto-config''' ('''PAC''') file defines how [[web browser]]s and other [[user agent]]s can automatically choose the appropriate [[proxy server]] (access method) for fetching a given [[Uniform Resource Locator|URL]].

A PAC file contains a [[JavaScript]] [[Function (computer science)|function]] “<code>FindProxyForURL(url, host)</code>”. This function returns a string with one or more access method specifications. These specifications cause the user agent to use a particular proxy server or to connect directly.<ref>{{Cite web |date=2023-04-23 |title=Proxy Auto-Configuration (PAC) file - HTTP {{!}} MDN |url=https://developer.mozilla.org/en-US/docs/Web/HTTP/Proxy_servers_and_tunneling/Proxy_Auto-Configuration_PAC_file |access-date=2023-07-02 |website=developer.mozilla.org |language=en-US}}</ref>

Multiple specifications provide a fall-backfallback when a proxy fails to respond. The browser fetches this PAC file before requesting other URLs. The URL of the PAC file is either configured manually or determined automatically by the [[Web Proxy AutodiscoveryAuto-Discovery Protocol]].

== Context ==

Line 12 ⟶ 13:

* Automatic proxy selection: Specify a host-name and a port number to be used for all URLs. Most browsers allow you to specify a list of domains (such as <code>localhost</code>) that will bypass this proxy.

* Proxy auto-configuration (PAC): Specify the URL for a PAC file with a JavaScript function that determines the appropriate proxy for each URL. This method is more suitable for laptop users who need several different proxy configurations, or complex corporate setups with many different proxies.

* [[Web Proxy AutodiscoveryAuto-Discovery Protocol]] (WPAD): Let the browser guess the ___location of the PAC file through [[DHCP]] and [[Domain Name System|DNS]] lookups.

== Proxy configurationHistory ==

The Proxy auto-config file format was originally designed by [[Netscape]] in 1996 for the [[Netscape Navigator|Netscape Navigator 2.0]]<ref>{{cite web|date=March 1996|title=Navigator Proxy Auto-Config File Format|url=http://wp.netscape.com/eng/mozilla/2.0/relnotes/demo/proxy-live.html|url-status=dead|archive-url=https://web.archive.org/web/20070602031929/http://wp.netscape.com/eng/mozilla/2.0/relnotes/demo/proxy-live.html|archive-date=2007-06-02|access-date=2013-07-05|work=Netscape Navigator Documentation}}</ref> and is a [[text file]] that defines at least one JavaScript function.

Computer [[operating system]]s (e.g., [[Microsoft Windows]], [[Mac OS X]], [[Linux]]) require a number of settings to communicate over the [[Internet]]. These settings are typically obtained from an [[Internet service provider|Internet Service Provider]] (ISP). Either anonymous (proxy to use a [[proxy server]]) or real settings may be used to establish a network connection.

== The PAC Filefile ==

By convention, the PAC file is normally named '''<code>proxy.pac</code>'''. The [[Web Proxy Autodiscovery Protocol|WPAD standard]] uses '''<code>wpad.dat</code>'''. The {{code|.pac}} file is expected to contain at least one function:

The Proxy auto-config file format was originally designed by [[Netscape]] in 1996 for the [[Netscape Navigator|Netscape Navigator 2.0]]<ref>{{cite web

| url=http://wp.netscape.com/eng/mozilla/2.0/relnotes/demo/proxy-live.html

| title=Navigator Proxy Auto-Config File Format

| date=March 1996

| work = Netscape Navigator Documentation

| archiveurl=https://web.archive.org/web/20070602031929/http://wp.netscape.com/eng/mozilla/2.0/relnotes/demo/proxy-live.html

| archivedate=2007-06-02

| deadurl=yes

| accessdate=2013-07-05}}</ref> and is a [[text file]] that defines at least one JavaScript function, '''<code>FindProxyForURL(url, host)</code>''', with two arguments: '''<code>url</code>''' is the URL of the object and '''<code>host</code>''' is the host-name derived from that URL. By convention, the PAC file is normally named '''<code>proxy.pac</code>'''. The [[Web Proxy Autodiscovery Protocol|WPAD standard]] uses '''<code>wpad.dat</code>'''.

: '''{{code|FindProxyForURL(url, host)}}''', with two arguments and return value in specific format:

To use it, a PAC file is published to a [[HTTP server]], and client user agents are instructed to use it, either by entering the URL in the proxy connection settings of the browser or through the use of the WPAD protocol.

: * '''{{code|url}}''' is the URL of the object

: * '''{{code|host}}''' is the host-name derived from that URL. Syntactically it is the same string as between <code>://</code> and the first <code>:</code> or <code>/</code> after that.<ref>{{Cite web|url=https://developer.mozilla.org/en-US/docs/Web/HTTP/Proxy_servers_and_tunneling/Proxy_Auto-Configuration_(PAC)_file|title = Proxy Auto-Configuration (PAC) file - HTTP &#124; MDN| date=23 April 2023 }}</ref>

: * '''{{code|return "..."}}''' is a string of signatures in the following format (see examples below):<ref group="note">[[EBNF]] by [[W3C]] notation</ref>

:: <syntaxhighlight lang="ebnf">

returnValue = type host,":",port,[{ ";",returnValue }];

type = "DIRECT" | "PROXY" | "SOCKS" | "HTTP" | "HTTPS" | "SOCKS4" | "SOCKS5"

host = UTF16String (* ECMA262-compatible UTF16 string *)

port = UTF16String (* Digits *)

</syntaxhighlight>

To use it, a PAC file is published to a [[HTTP server]], and client user agents are instructed to use it, either by entering the URL in the proxy connection settings of the browser or through the use of the WPAD protocol. The URL may also reference a local file as for example: '''<code>file:///etc/proxy.pac</code>'''.

Even though most clients will process the script regardless of the [[MIME type]] returned in the [[HTTP reply]], for the sake of completeness and to maximize compatibility, the HTTP server should be configured to declare the MIME type of this file to be either '''<code>application/x-ns-proxy-autoconfig</code>''' or '''<code>application/x-javascript-config</code>'''.

Line 34 ⟶ 40:

There is little evidence to favor the use of one MIME type over the other. It would be, however, reasonable to assume that '''<code>application/x-ns-proxy-autoconfig</code>''' will be supported in more clients than '''<code>application/x-javascript-config</code>''' as it was defined in the original Netscape specification, the latter type coming into use more recently.

=== Example ===

A very simple example of a PAC file is:

<sourcesyntaxhighlight lang="javascript">

function FindProxyForURL(url, host) {

return 'PROXY proxy.example.com:8080; DIRECT';

{

return "PROXY proxy.example.com:8080; DIRECT";

}

</syntaxhighlight>

</source>

This function instructs the browser to retrieve all pages through the proxy on [[port (computer networking)|port]] 8080 of the server <code>proxy.example.com</code>. Should this proxy fail to respond, the browser contacts the Web-site directly, without using a proxy. The latter may fail if [[firewall (computing)|firewalls]], or other intermediary network devices, reject requests from sources other than the proxy—a common configuration in corporate networks.

A more complicated example demonstrates some available JavaScript functions to be used in the <code>FindProxyForURL</code> function:

<sourcesyntaxhighlight lang="javascript">

function FindProxyForURL(url, host) {

// our local URLs from the domains below example.com don't need a proxy:

if (shExpMatch(host, "'*.example.com"')) {

return 'DIRECT';

{

}

return "DIRECT";

}

// URLs within this network are accessed through

// port 8080 on fastproxy.example.com:

if (isInNet(host, "'10.0.0.0"', "'255.255.248.0"')) {

return 'PROXY fastproxy.example.com:8080';

{

}

return "PROXY fastproxy.example.com:8080";

}

// All other requests go through port 8080 of proxy.example.com.

// should that fail to respond, go directly to the WWW:

return "'PROXY proxy.example.com:8080; DIRECT"';

}

</syntaxhighlight>

</source>

By default, the PROXY keyword means that a proxy corresponding to the protocol of the original request, be it http, https, or ftp, is used. Other supported keyword and proxy types include:

; SOCKS: Use a [[SOCKS]] proxy.

; HTTP, HTTPS: Introduced in more recent versions of Firefox. Specifies an HTTP(S) proxy.

; SOCKS4, SOCKS5: Introduced in more recent versions of Firefox. Specifies the SOCKS protocol version.

=== Limitations ===

==== PAC Character-Encoding ====

The encoding of PAC scripts is generally unspecified, and different browsers and network stacks have different rules for how PAC scripts may be encoded. In general, wholly [[ASCII]] PAC scripts will work with any browser or network stack. [[Mozilla Firefox]] 66 and later additionally supports PAC scripts encoded as [[UTF-8]].<ref>{{cite web

Browsers, such as [[Mozilla Firefox]] and [[Internet Explorer]], support only system default [[Character encoding|encoding]] PAC files,{{citation needed|date=April 2013}} and cannot support [[Unicode]] encodings, such as [[UTF-8]].{{citation needed|date=April 2013}}

| url=https://bugzilla.mozilla.org/show_bug.cgi?id=1492938

| title=Bug 1492938 - Proxy autoconfig scripts should be loaded as UTF-8 if they are valid UTF-8, otherwise as Latin-1 (a byte is a code point)

| access-date=2019-04-10}}</ref>

==== <code>DnsResolve</code> ====

The function <code>dnsResolve</code> (and similar other functions) performs a [[Domain name system|DNS]] lookup that can block the browser for a long time if the DNS server does not respond.

==== <code>myIpAddress</code> ====

Caching of proxy auto-configuration results by ___domain name in Microsoft's [[Internet Explorer]] 5.5 or newer limits the flexibility of the PAC standard. In effect, you can choose the proxy based on the ___domain name, but not on the path of the URL. Alternatively, you need to disable caching of proxy auto-configuration results by editing the [[Windows Registry|registry]], a process described by de Boyne Pollard (listed in [[#Further reading|further reading]]).

The <code>myIpAddress</code> function has often been reported to give incorrect or unusable results, e.g. '''<code>127.0.0.1</code>''', the IP address of the localhost.<ref>{{cite web

| url=https://bugzilla.mozilla.org/show_bug.cgi?id=347307

| title=Bug 347307 - Need a way to determine the best local IP address for PAC files to use

| access-date=2022-04-18

}}

</ref>

It may help to remove on the system's host file (e.g. '''<code>/etc/hosts</code>''' on Linux) any lines referring to the machine host-name, while the line '''<code>127.0.0.1 localhost</code>''' can, and should, stay.{{Citation needed|date=April 2021}}

==== Security ====

In 2013, researchers began warning about the security risks of proxy auto-config.<ref>{{cite web

| url=https://www.darkreading.com/vulnerabilities-threats/cybercriminals-likely-to-expand-use-of-browser-proxies

| title=Cybercriminals Likely To Expand Use Of Browser Proxies

| first=Robert

| last=Lemos

| date=2013-03-06

| access-date=2016-04-20}}</ref> The threat involves using a PAC, discovered automatically by the system, to redirect the victim's browser traffic to an attacker-controlled server instead.

Another issue with pac-file is that the typical implementation involve clear text http retrieval, which does not include any security features such as code signing or web certificates. Attackers can perform [[Man-in-the-middle attack|man-in-the-middle attacks]] easily.

==== Old Microsoft problems ====

Caching of proxy auto-configuration results by ___domain name in Microsoft's [[Internet Explorer]] 5.5 or newer limits the flexibility of the PAC standard. In effect, you can choose the proxy based on the ___domain name, but not on the path of the URL. Alternatively, you need to disable caching of proxy auto-configuration results by editing the [[Windows Registry|registry]].<ref>{{cite web

| url=https://support.microsoft.com/en-us/topic/how-to-disable-automatic-proxy-caching-in-internet-explorer-92735c9c-8a26-d0d8-7f8a-1b46595cbaba

| title=Microsoft KB 271361 - How to disable automatic proxy caching in Internet Explorer

| access-date=2024-06-27

}}</ref>

It is recommended to always use [[IP address]]es instead of host ___domain names in the <code>isInNet</code> function for compatibility with other Windows components which make use of the Internet Explorer PAC configuration, such as [[.NET Framework|.NET 2.0 Framework]]. For example,

<sourcesyntaxhighlight lang="javascript">

if (isInNet(host, dnsResolve(sampledomain), "'255.255.248.0"')) {} // .NET 2.0 will resolve proxy properly

if (isInNet(host, sampledomain, "'255.255.248.0"')) {} // .NET 2.0 will not resolve proxy properly

</syntaxhighlight>

</source>

The current convention is to fail over to direct connection when a PAC file is unavailable.

Line 89 ⟶ 127:

For instance, Firefox usually keeps 20 ___domain entries cached for 60 seconds. This may be configured via the '''<code>network.dnsCacheEntries</code>''' and '''<code>network.dnsCacheExpiration</code>''' configuration variables. Flushing the system's [[DNS cache]] may also help, which can be achieved e.g. in Linux with '''<kbd>sudo service dns-clean start</kbd>''' or in Windows with '''<kbd>ipconfig /flushdns</kbd>'''.

On Internet Explorer 9, <code>isInNet('localHostName', 'second.ip', '255.255.255.255')</code> returns <code>true</code> and can be used as a workaround.

==== <code>myIpAddress</code> ====

The <code>myIpAddress</code> function has often been reported to give incorrect or unusable results, e.g. '''<code>127.0.0.1</code>''', the IP address of the localhost.

It may help to remove on the system's host file (e.g. '''<code>/etc/hosts</code>''' on Linux) any lines referring to the machine host-name, while the line '''<code>127.0.0.1 localhost</code>''' can, and [[Weasel word|should]], stay.

On Internet Explorer 9, <code>isInNet("localHostName", "second.ip", "255.255.255.255")</code> returns <code>true</code> and can be used as a workaround.

The <code>myIpAddress</code> function assumes that the device has a single IPv4 address. The results are undefined if the device has more than one IPv4 address or has IPv6 addresses.

==== Security ====

In 2013, researchers began warning about the security risks of proxy auto-config.<ref>{{cite web

| url=http://www.darkreading.com/vulnerabilities---threats/cybercriminals-likely-to-expand-use-of-browser-proxies/d/d-id/1139313?print=yes

| title=Cybercriminals Likely To Expand Use Of Browser Proxies

| first=Robert

| last=Lemos

| date=2013-03-06

| accessdate=2016-04-20}}</ref> The threat involves using a PAC to redirect the victim's browser traffic to an attacker-controlled server instead.

==== Others ====

Further limitations are related to the [[JavaScript engine]] on the local machine.

Apple OS X v10.10 and above operating system in some cases can ignore .pac file to use it in native Cocoa apps such as Safari web browser.<ref>

{{cite web

|title=Safari and several other apps won't connect to proxy server

|website=CERN

|url=https://espace.cern.ch/webservices-help/CERNLibraryProxy/BrowserConfiguration/Pages/Safari.aspx

}}</ref>

=== Advanced functionality ===

Line 120 ⟶ 138:

One can return multiple proxies:

<sourcesyntaxhighlight lang="javascript">

return "'PROXY proxy1.example.com:80; PROXY proxy2.example.com:8080"';

</syntaxhighlight>

</source>

The above will try proxy1 first and if unavailable it will then try proxy2.

== Notes ==

{{Reflist|group=note}}

== References ==

<references />

== FurtherExternal readinglinks ==

{{cite web

| url=http://jdebp.eu./FGA/web-browser-auto-proxy-configuration.html

| title=Automatic proxy HTTP server configuration in web browsers

| author-first=Jonathan

| author-last=de Boyne Pollard

| year=2004

| work=Frequently Given Answers

| accessdate=2013-07-05}}

* {{ cite web

== External links ==

| url=https://developer.mozilla.org/docs/web/http/proxy_servers_and_tunneling/proxy_auto-configuration_pac_file

| title=Proxy Auto-Configuration (PAC) file

| work=developer.mozilla.org

| date=2019-01-27}}

* {{cite web

Line 144 ⟶ 163:

| work=Netscape Proxy Server Administrator's Guide: Chapter 11

| date=1998-02-25

| archiveurlarchive-url=https://web.archive.org/web/20040810122331/http://developer.netscape.com/docs/manuals/proxy/adminux/autoconf.htm

| archivedatearchive-date=2004-08-10

| deadurlurl-status=yesdead}}

* {{cite web

Line 152 ⟶ 171:

| title=Chapter 26 - Using Automatic Configuration, Automatic Proxy, and Automatic Detection

| publisher=[[Microsoft TechNet]]

| accessdateaccess-date=2013-07-05}}

* {{cite web

| url=https://calomel.org/proxy_auto_config.html

| title=Proxy Auto Config for Firefox (PAC). Fully working examples including anti-ad and anti-adult filter rules

| date=2012-05-12}}

| access-date=2009-05-24

| archive-url=https://web.archive.org/web/20150701185956/https://calomel.org/proxy_auto_config.html

| archive-date=2015-07-01

| url-status=dead

}}

* {{cite web

| url=https://jdebp.uk/FGA/web-browser-auto-proxy-configuration.html

| title=Automatic proxy HTTP server configuration in web browsers

| author-first=Jonathan

| author-last=de Boyne Pollard

| year=2004

| work=Frequently Given Answers

| access-date=2013-07-05

}}

{{Web browsers}}

Line 164 ⟶ 199:

[[Category:Web browsers]]

[[Category:Proxy servers|*]]

[[Category:JavaScript]]

[[Category:Computer files]]