Purpose : Used with other docs and files only.
- Copyright (C) 2001-2018 Privoxy Developers https://www.privoxy.org/
+ Copyright (C) 2001-2019 Privoxy Developers https://www.privoxy.org/
See LICENSE.
========================================================================
Sample Configuration File for Privoxy &p-version;
</title>
<para>
-Copyright (C) 2001-2018 Privoxy Developers https://www.privoxy.org/
+Copyright (C) 2001-2019 Privoxy Developers https://www.privoxy.org/
</para>
<literallayout>
4. ACCESS CONTROL AND SECURITY #
5. FORWARDING #
6. MISCELLANEOUS #
- 7. WINDOWS GUI OPTIONS #
+ 7. TLS #
+ 8. WINDOWS GUI OPTIONS #
#
##################################################################
Requests are accepted if the specified trusted-cgi-refer is the prefix
of the Referer.
</para>
+ <para>
+ If the trusted source is supposed to access the CGI pages via
+ JavaScript the <link linkend="cors-allowed-origin">cors-allowed-origin</link>
+ option can be used.
+ </para>
<warning>
<para>
Declaring pages the admin doesn't control trustworthy may allow
<![%config-file;[<literallayout>@@#trusted-cgi-referer http://www.example.org/local-privoxy-control-page</literallayout>]]>
</sect3>
+
+<!-- ~~~~~ New section ~~~~~ -->
+<sect3 renderas="sect4" id="cors-allowed-origin"><title>cors-allowed-origin</title>
+<variablelist>
+ <varlistentry>
+ <term>Specifies:</term>
+ <listitem>
+ <para>
+ A trusted website which can access &my-app;'s CGI pages through JavaScript.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Type of value:</term>
+ <listitem>
+ <para>URL</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Default value:</term>
+ <listitem>
+ <para>Unset</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Effect if unset:</term>
+ <listitem>
+ <para>
+ No external sites get access via cross-origin resource sharing.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ Modern browsers by default prevent cross-origin requests made
+ via JavaScript to &my-app;'s CGI interface even if &my-app;
+ would trust the referer because it's white listed via the
+ <link linkend="trusted-cgi-referer">trusted-cgi-referer</link>
+ directive.
+ </para>
+ <para>
+ <ulink url="https://en.wikipedia.org/wiki/Cross-origin_resource_sharing"
+ >Cross-origin resource sharing (CORS)</ulink> is a mechanism to allow
+ cross-origin requests.
+ </para>
+ <para>
+ The <quote>cors-allowed-origin</quote> option can be used to specify
+ a domain that is allowed to make requests to Privoxy CGI interface
+ via JavaScript. It is used in combination with the
+ <link linkend="trusted-cgi-referer">trusted-cgi-referer</link>
+ directive.
+ </para>
+ <warning>
+ <para>
+ Declaring domains the admin doesn't control trustworthy may allow
+ malicious third parties to modify Privoxy's internal state against
+ the user's wishes and without the user's knowledge.
+ </para>
+ </warning>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<![%config-file;[<literallayout>@@#cors-allowed-origin http://www.example.org/</literallayout>]]>
+</sect3>
+
</sect2>
<!-- ~ End section ~ -->
<listitem>
<para>
<replaceable class="parameter">target_pattern</replaceable>
- <replaceable class="parameter">socks_proxy</replaceable>[:<replaceable class="parameter">port</replaceable>]
+ [<replaceable class="parameter">user</replaceable>:<replaceable class="parameter">pass</replaceable>@]<replaceable class="parameter">socks_proxy</replaceable>[:<replaceable class="parameter">port</replaceable>]
<replaceable class="parameter">http_parent</replaceable>[:<replaceable class="parameter">port</replaceable>]
</para>
<para>
(<replaceable class="parameter">http_parent</replaceable>
may be <quote>.</quote> to denote <quote>no HTTP forwarding</quote>), and the optional
<replaceable class="parameter">port</replaceable> parameters are TCP ports,
- i.e. integer values from 1 to 65535
+ i.e. integer values from 1 to 65535. <replaceable class="parameter">user</replaceable> and
+ <replaceable class="parameter">pass</replaceable> can be used for SOCKS5 authentication if required.
</para>
</listitem>
</varlistentry>
forward-socks4 / socks-gw.example.com:1080 .
</screen>
+ <para>
+ To connect SOCKS5 proxy which requires username/password authentication:
+ </para>
+ <screen>
+ forward-socks5 / user:pass@socks-gw.example.com:1080 .
+</screen>
+
<para>
To chain Privoxy and Tor, both running on the same system, you would use
something like:
# Define a couple of tags, the described effect requires action sections
# that are enabled based on CLIENT-TAG patterns.
client-specific-tag circumvent-blocks Overrule blocks but do not affect other actions
- disable-content-filters Disable content-filters but do not affect other actions
+ client-specific-tag disable-content-filters Disable content-filters but do not affect other actions
</screen>
</listitem>
</varlistentry>
</sect2>
+
+<sect2 id="tls">
+<title>TLS/SSL</title>
+
+<!-- ~~~~~ New section ~~~~~ -->
+
+<sect3 renderas="sect4" id="ca-directory"><title>ca-directory</title>
+<variablelist>
+ <varlistentry>
+ <term>Specifies:</term>
+ <listitem>
+ <para>
+ Directory with the CA key, the CA certificate and the trusted CAs file.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Type of value:</term>
+ <listitem>
+ <para>
+ Text
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Default value:</term>
+ <listitem>
+ <para><emphasis>Empty string</emphasis></para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Effect if unset:</term>
+ <listitem>
+ <para>
+ Default value is used.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ This directive specifies the directory where the
+ CA key, the CA certificate and the trusted CAs file
+ are located.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Examples:</term>
+ <listitem>
+ <para>
+ ca-directory /usr/local/etc/privoxy/CA
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<![%config-file;[<literallayout>@@#ca-directory /usr/local/etc/privoxy/CA</literallayout>]]>
+</sect3>
+
+<!-- ~ End section ~ -->
+
+<!-- ~~~~~ New section ~~~~~ -->
+
+<sect3 renderas="sect4" id="ca-cert-file"><title>ca-cert-file</title>
+<variablelist>
+ <varlistentry>
+ <term>Specifies:</term>
+ <listitem>
+ <para>
+ The CA certificate file in ".crt" format.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Type of value:</term>
+ <listitem>
+ <para>
+ Text
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Default value:</term>
+ <listitem>
+ <para><emphasis>cacert.crt</emphasis></para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Effect if unset:</term>
+ <listitem>
+ <para>
+ Default value is used.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ This directive specifies the name of the CA certificate file
+ in ".crt" format.
+ </para>
+ <para>
+ It can be generated with: openssl req -new -x509 -extensions v3_ca -keyout cakey.pem -out cacert.crt -days 3650
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Examples:</term>
+ <listitem>
+ <para>
+ ca-cert-file root.crt
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<![%config-file;[<literallayout>@@#ca-cert-file cacert.crt</literallayout>]]>
+</sect3>
+
+<!-- ~ End section ~ -->
+
+<!-- ~~~~~ New section ~~~~~ -->
+
+<sect3 renderas="sect4" id="ca-key-file"><title>ca-key-file</title>
+<variablelist>
+ <varlistentry>
+ <term>Specifies:</term>
+ <listitem>
+ <para>
+ The CA key file in ".pem" format.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Type of value:</term>
+ <listitem>
+ <para>
+ Text
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Default value:</term>
+ <listitem>
+ <para><emphasis>cacert.pem</emphasis></para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Effect if unset:</term>
+ <listitem>
+ <para>
+ Default value is used.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ This directive specifies the name of the CA key file
+ in ".pem" format. See the <ulink url="#CA-CERT-FILE">ca-cert-file</ulink>
+ for a command to generate it.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Examples:</term>
+ <listitem>
+ <para>
+ ca-key-file cakey.pem
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<![%config-file;[<literallayout>@@#ca-key-file root.pem</literallayout>]]>
+</sect3>
+
+<!-- ~ End section ~ -->
+
+<!-- ~~~~~ New section ~~~~~ -->
+
+<sect3 renderas="sect4" id="ca-password"><title>ca-password</title>
+<variablelist>
+ <varlistentry>
+ <term>Specifies:</term>
+ <listitem>
+ <para>
+ The password for the CA keyfile.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Type of value:</term>
+ <listitem>
+ <para>
+ Text
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Default value:</term>
+ <listitem>
+ <para><emphasis>Empty string</emphasis></para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Effect if unset:</term>
+ <listitem>
+ <para>
+ Default value is used.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ This directive specifies the password for the CA keyfile
+ that is used when Privoxy generates certificates for intercepted
+ requests.
+ </para>
+ <para>
+ Note that the password is shown on the CGI page so don't
+ reuse an important one.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Examples:</term>
+ <listitem>
+ <para>
+ ca-password blafasel
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<![%config-file;[<literallayout>@@#ca-password swordfish</literallayout>]]>
+</sect3>
+
+<!-- ~ End section ~ -->
+
+<!-- ~~~~~ New section ~~~~~ -->
+
+<sect3 renderas="sect4" id="certificate-directory"><title>certificate-directory</title>
+<variablelist>
+ <varlistentry>
+ <term>Specifies:</term>
+ <listitem>
+ <para>
+ Directory to safe generated keys and certificates.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Type of value:</term>
+ <listitem>
+ <para>
+ Text
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Default value:</term>
+ <listitem>
+ <para><emphasis>./certs</emphasis></para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Effect if unset:</term>
+ <listitem>
+ <para>
+ Default value is used.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ This directive specifies the directory where generated
+ TLS/SSL keys and certificates are saved.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Examples:</term>
+ <listitem>
+ <para>
+ certificate-directory /usr/local/var/privoxy/certs
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<![%config-file;[<literallayout>@@#certificate-directory /usr/local/var/privoxy/certs</literallayout>]]>
+</sect3>
+
+<!-- ~ End section ~ -->
+
+<!-- ~~~~~ New section ~~~~~ -->
+
+<sect3 renderas="sect4" id="trusted-cas-file"><title>trusted-cas-file</title>
+<variablelist>
+ <varlistentry>
+ <term>Specifies:</term>
+ <listitem>
+ <para>
+ The trusted CAs file in ".pem" format.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Type of value:</term>
+ <listitem>
+ <para>
+ File name relative to ca-directory
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Default value:</term>
+ <listitem>
+ <para><emphasis>trustedCAs.pem</emphasis></para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Effect if unset:</term>
+ <listitem>
+ <para>
+ Default value is used.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Notes:</term>
+ <listitem>
+ <para>
+ This directive specifies the trusted CAs file that is used when validating
+ certificates for intercepted TLS/SSL request.
+ </para>
+ <para>
+ An example file can be downloaded from
+ <ulink url="https://curl.haxx.se/ca/cacert.pem">https://curl.haxx.se/ca/cacert.pem</ulink>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Examples:</term>
+ <listitem>
+ <para>
+ trusted-cas-file trusted_cas_file.pem
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<![%config-file;[<literallayout>@@#trusted-cas-file trustedCAs.pem</literallayout>]]>
+</sect3>
+
+<!-- ~ End section ~ -->
+
+</sect2>
+
<!-- ~~~~~ New section ~~~~~ -->
<sect2 id="windows-gui">
projects / privoxy.git / blobdiff