From: Fabian Keil <fk@fabiankeil.de>
Date: Mon, 26 Aug 2019 11:34:55 +0000 (+0200)
Subject: Document the cors-allowed-origin directive
X-Git-Tag: v_3_0_29~609
X-Git-Url: http://www.privoxy.org/gitweb/?p=privoxy.git;a=commitdiff_plain;h=2ffad2c58cd9db229d50c5c84ed1a66005df4ecd;hp=9fd58c0d3a56323ce94837f217e6609e9c7b2402

Document the cors-allowed-origin directive
---

diff --git a/doc/source/p-config.sgml b/doc/source/p-config.sgml
index ba974539..ce1c4ade 100644
--- a/doc/source/p-config.sgml
+++ b/doc/source/p-config.sgml
@@ -1983,6 +1983,11 @@ ACLs: permit-access and deny-access</title>
     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
@@ -1997,6 +2002,74 @@ ACLs: permit-access and deny-access</title>
 <![%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  ~  -->