Mention that FEATURE_HTTPS_INSPECTION is required for https inspection to work

[privoxy.git] / doc / source / p-config.sgml

diff --git a/doc/source/p-config.sgml b/doc/source/p-config.sgml
index 1a53c69..5b82d39 100644 (file)
--- a/doc/source/p-config.sgml
+++ b/doc/source/p-config.sgml
@@ -107,7 +107,7 @@ Copyright (C) 2001-2020 Privoxy Developers https://www.privoxy.org/
       4. ACCESS CONTROL AND SECURITY                             #
       5. FORWARDING                                              #
       6. MISCELLANEOUS                                           #
-      7. TLS                                                     #
+      7. HTTPS INSPECTION (EXPERIMENTAL)                         #
       8. WINDOWS GUI OPTIONS                                     #
                                                                  #
 ##################################################################
@@ -1630,7 +1630,7 @@ actionsfile
   </listitem>
  </varlistentry>
  <varlistentry>
-  <term>Examples:</term>
+  <term>Example:</term>
   <listitem>
    <para>
     enforce-blocks 1
@@ -2508,7 +2508,7 @@ forward-socks4, forward-socks4a, forward-socks5 and forward-socks5t</title>
   </listitem>
  </varlistentry>
  <varlistentry>
-  <term>Examples:</term>
+  <term>Example:</term>
   <listitem>
    <para>
     forwarded-connect-retries 1
@@ -2585,7 +2585,7 @@ forward-socks4, forward-socks4a, forward-socks5 and forward-socks5t</title>
   </listitem>
  </varlistentry>
  <varlistentry>
-  <term>Examples:</term>
+  <term>Example:</term>
   <listitem>
    <para>
     accept-intercepted-requests 1
@@ -2643,7 +2643,7 @@ forward-socks4, forward-socks4a, forward-socks5 and forward-socks5t</title>
   </listitem>
  </varlistentry>
  <varlistentry>
-  <term>Examples:</term>
+  <term>Example:</term>
   <listitem>
    <para>
     allow-cgi-request-crunching 1
@@ -2710,7 +2710,7 @@ forward-socks4, forward-socks4a, forward-socks5 and forward-socks5t</title>
   </listitem>
  </varlistentry>
  <varlistentry>
-  <term>Examples:</term>
+  <term>Example:</term>
   <listitem>
    <para>
     split-large-forms 1
@@ -2793,7 +2793,7 @@ forward-socks4, forward-socks4a, forward-socks5 and forward-socks5t</title>
   </listitem>
  </varlistentry>
  <varlistentry>
-  <term>Examples:</term>
+  <term>Example:</term>
   <listitem>
    <para>
     keep-alive-timeout 300
@@ -2862,7 +2862,7 @@ forward-socks4, forward-socks4a, forward-socks5 and forward-socks5t</title>
   </listitem>
  </varlistentry>
  <varlistentry>
-  <term>Examples:</term>
+  <term>Example:</term>
   <listitem>
    <para>
     tolerate-pipelining 1
@@ -2943,7 +2943,7 @@ forward-socks4, forward-socks4a, forward-socks5 and forward-socks5t</title>
   </listitem>
  </varlistentry>
  <varlistentry>
-  <term>Examples:</term>
+  <term>Example:</term>
   <listitem>
    <para>
     default-server-timeout 60
@@ -2951,7 +2951,7 @@ forward-socks4, forward-socks4a, forward-socks5 and forward-socks5t</title>
   </listitem>
  </varlistentry>
 </variablelist>
-<![%config-file;[<literallayout>@@#default-server-timeout 60</literallayout>]]>
+<![%config-file;[<literallayout>@@#default-server-timeout 5</literallayout>]]>
 </sect3>
 
 
@@ -3042,7 +3042,7 @@ forward-socks4, forward-socks4a, forward-socks5 and forward-socks5t</title>
   </listitem>
  </varlistentry>
  <varlistentry>
-  <term>Examples:</term>
+  <term>Example:</term>
   <listitem>
    <para>
     connection-sharing 1
@@ -3098,7 +3098,7 @@ forward-socks4, forward-socks4a, forward-socks5 and forward-socks5t</title>
   </listitem>
  </varlistentry>
  <varlistentry>
-  <term>Examples:</term>
+  <term>Example:</term>
   <listitem>
    <para>
     socket-timeout 300
@@ -3186,7 +3186,7 @@ forward-socks4, forward-socks4a, forward-socks5 and forward-socks5t</title>
   </listitem>
  </varlistentry>
  <varlistentry>
-  <term>Examples:</term>
+  <term>Example:</term>
   <listitem>
    <para>
     max-client-connections 256
@@ -3265,7 +3265,7 @@ forward-socks4, forward-socks4a, forward-socks5 and forward-socks5t</title>
   </listitem>
  </varlistentry>
  <varlistentry>
-  <term>Examples:</term>
+  <term>Example:</term>
   <listitem>
    <para>
     listen-backlog 4096
@@ -3336,7 +3336,7 @@ forward-socks4, forward-socks4a, forward-socks5 and forward-socks5t</title>
   </listitem>
  </varlistentry>
  <varlistentry>
-  <term>Examples:</term>
+  <term>Example:</term>
   <listitem>
    <para>
     enable-accept-filter 1
@@ -3739,7 +3739,7 @@ forward-socks4, forward-socks4a, forward-socks5 and forward-socks5t</title>
   </listitem>
  </varlistentry>
  <varlistentry>
-  <term>Examples:</term>
+  <term>Example:</term>
   <listitem>
     <screen>
       # Increase the time to life for temporarily enabled tags to 3 minutes
@@ -3811,7 +3811,7 @@ forward-socks4, forward-socks4a, forward-socks5 and forward-socks5t</title>
   </listitem>
  </varlistentry>
  <varlistentry>
-  <term>Examples:</term>
+  <term>Example:</term>
   <listitem>
     <screen>
       # Allow systems that can reach Privoxy to provide the client
@@ -3884,7 +3884,7 @@ forward-socks4, forward-socks4a, forward-socks5 and forward-socks5t</title>
   </listitem>
  </varlistentry>
  <varlistentry>
-  <term>Examples:</term>
+  <term>Example:</term>
   <listitem>
     <screen>
       # Increase the receive buffer size
@@ -3900,8 +3900,14 @@ forward-socks4, forward-socks4a, forward-socks5 and forward-socks5t</title>
 </sect2>
 
 
-<sect2 id="tls">
-<title>TLS/SSL Inspection</title>
+<sect2 id="https-inspection-directives">
+<title>HTTPS Inspection (Experimental)</title>
+
+<para>
+  HTTPS inspection allows to filter encrypted requests.
+  This is only supported when <application>Privoxy</application>
+  has been built with FEATURE_HTTPS_INSPECTION.
+</para>
 
 <!--   ~~~~~       New section      ~~~~~     -->
 
@@ -3952,7 +3958,7 @@ forward-socks4, forward-socks4a, forward-socks5 and forward-socks5t</title>
   </listitem>
  </varlistentry>
  <varlistentry>
-  <term>Examples:</term>
+  <term>Example:</term>
   <listitem>
    <para>
     ca-directory /usr/local/etc/privoxy/CA
@@ -4023,7 +4029,7 @@ forward-socks4, forward-socks4a, forward-socks5 and forward-socks5t</title>
   </listitem>
  </varlistentry>
  <varlistentry>
-  <term>Examples:</term>
+  <term>Example:</term>
   <listitem>
    <para>
     ca-cert-file root.crt
@@ -4081,7 +4087,7 @@ forward-socks4, forward-socks4a, forward-socks5 and forward-socks5t</title>
   </listitem>
  </varlistentry>
  <varlistentry>
-  <term>Examples:</term>
+  <term>Example:</term>
   <listitem>
    <para>
     ca-key-file cakey.pem
@@ -4143,7 +4149,7 @@ forward-socks4, forward-socks4a, forward-socks5 and forward-socks5t</title>
   </listitem>
  </varlistentry>
  <varlistentry>
-  <term>Examples:</term>
+  <term>Example:</term>
   <listitem>
    <para>
     ca-password blafasel
@@ -4206,13 +4212,26 @@ forward-socks4, forward-socks4a, forward-socks5 and forward-socks5t</title>
     and the <ulink url="#CA-CERT-KEY">ca-cert-key</ulink>.
    </para>
    <para>
-    The permissions should only let &my-app; and the  &my-app;
+    The permissions should only let &my-app; and the &my-app;
     admin access the directory.
    </para>
+   <warning>
+    <para>
+     &my-app; currently does not garbage-collect obsolete keys
+     and certificates and does not keep track of how may keys
+     and certificates exist.
+    </para>
+    <para>
+     &my-app; admins should monitor the size of the directory
+     and/or make sure there is sufficient space available.
+     A cron job to limit the number of keys and certificates
+     to a certain number may be worth considering.
+    </para>
+   </warning>
   </listitem>
  </varlistentry>
  <varlistentry>
-  <term>Examples:</term>
+  <term>Example:</term>
   <listitem>
    <para>
     certificate-directory /usr/local/var/privoxy/certs
@@ -4227,6 +4246,131 @@ forward-socks4, forward-socks4a, forward-socks5 and forward-socks5t</title>
 
 <!--   ~~~~~       New section      ~~~~~     -->
 
+<sect3 renderas="sect4" id="cipher-list"><title>cipher-list</title>
+<variablelist>
+ <varlistentry>
+  <term>Specifies:</term>
+  <listitem>
+   <para>
+    A list of ciphers to use in TLS handshakes
+   </para>
+  </listitem>
+ </varlistentry>
+ <varlistentry>
+  <term>Type of value:</term>
+  <listitem>
+   <para>
+    Text
+   </para>
+  </listitem>
+ </varlistentry>
+ <varlistentry>
+  <term>Default value:</term>
+  <listitem>
+   <para>None</para>
+  </listitem>
+ </varlistentry>
+ <varlistentry>
+  <term>Effect if unset:</term>
+  <listitem>
+   <para>
+    A default value is inherited from the TLS library.
+   </para>
+  </listitem>
+ </varlistentry>
+ <varlistentry>
+  <term>Notes:</term>
+  <listitem>
+   <para>
+    This directive allows to specify a non-default list of ciphers to use
+    in TLS handshakes with clients and servers.
+   </para>
+   <para>
+    Ciphers are separated by colons. Which ciphers are supported
+    depends on the TLS library. When using OpenSSL, unsupported ciphers
+    are skipped. When using MbedTLS they are rejected.
+   </para>
+   <warning>
+    <para>
+     Specifying an unusual cipher list makes fingerprinting easier.
+     Note that the default list provided by the TLS library may
+     be unusual when compared to the one used by modern browsers
+     as well.
+    </para>
+   </warning>
+  </listitem>
+ </varlistentry>
+ <varlistentry>
+  <term>Examples:</term>
+  <listitem>
+   <screen>
+    # Explicitly set a couple of ciphers with names used by MbedTLS
+    cipher-list cipher-list TLS-ECDHE-RSA-WITH-CHACHA20-POLY1305-SHA256:\
+TLS-ECDHE-ECDSA-WITH-CHACHA20-POLY1305-SHA256:\
+TLS-DHE-RSA-WITH-CHACHA20-POLY1305-SHA256:\
+TLS-ECDHE-ECDSA-WITH-AES-128-GCM-SHA256:\
+TLS-ECDHE-ECDSA-WITH-AES-256-GCM-SHA384:\
+TLS-ECDHE-ECDSA-WITH-AES-256-CCM:\
+TLS-ECDHE-ECDSA-WITH-AES-256-CCM-8:\
+TLS-ECDHE-ECDSA-WITH-AES-128-CCM:\
+TLS-ECDHE-ECDSA-WITH-AES-128-CCM-8:\
+TLS-ECDHE-ECDSA-WITH-CAMELLIA-128-GCM-SHA256:\
+TLS-ECDHE-ECDSA-WITH-CAMELLIA-256-GCM-SHA384:\
+TLS-ECDHE-RSA-WITH-AES-128-GCM-SHA256:\
+TLS-ECDHE-RSA-WITH-AES-256-GCM-SHA384:\
+TLS-ECDHE-RSA-WITH-CAMELLIA-128-GCM-SHA256:\
+TLS-ECDHE-RSA-WITH-CAMELLIA-256-GCM-SHA384:\
+TLS-DHE-RSA-WITH-AES-256-GCM-SHA384:\
+TLS-DHE-RSA-WITH-AES-128-GCM-SHA256:\
+TLS-DHE-RSA-WITH-AES-256-CCM:\
+TLS-DHE-RSA-WITH-AES-256-CCM-8:\
+TLS-DHE-RSA-WITH-AES-128-CCM:\
+TLS-DHE-RSA-WITH-AES-128-CCM-8:\
+TLS-DHE-RSA-WITH-CAMELLIA-128-GCM-SHA256:\
+TLS-DHE-RSA-WITH-CAMELLIA-256-GCM-SHA384:\
+TLS-ECDH-RSA-WITH-AES-128-GCM-SHA256:\
+TLS-ECDH-RSA-WITH-AES-256-GCM-SHA384:\
+TLS-ECDH-RSA-WITH-CAMELLIA-128-GCM-SHA256:\
+TLS-ECDH-RSA-WITH-CAMELLIA-256-GCM-SHA384:\
+TLS-ECDH-ECDSA-WITH-AES-128-GCM-SHA256:\
+TLS-ECDH-ECDSA-WITH-AES-256-GCM-SHA384:\
+TLS-ECDH-ECDSA-WITH-CAMELLIA-128-GCM-SHA256:\
+TLS-ECDH-ECDSA-WITH-CAMELLIA-256-GCM-SHA384
+   </screen>
+   <screen>
+    # Explicitly set a couple of ciphers with names used by OpenSSL
+cipher-list ECDHE-RSA-AES256-GCM-SHA384:\
+ECDHE-ECDSA-AES256-GCM-SHA384:\
+DH-DSS-AES256-GCM-SHA384:\
+DHE-DSS-AES256-GCM-SHA384:\
+DH-RSA-AES256-GCM-SHA384:\
+DHE-RSA-AES256-GCM-SHA384:\
+ECDH-RSA-AES256-GCM-SHA384:\
+ECDH-ECDSA-AES256-GCM-SHA384:\
+ECDHE-RSA-AES128-GCM-SHA256:\
+ECDHE-ECDSA-AES128-GCM-SHA256:\
+DH-DSS-AES128-GCM-SHA256:\
+DHE-DSS-AES128-GCM-SHA256:\
+DH-RSA-AES128-GCM-SHA256:\
+DHE-RSA-AES128-GCM-SHA256:\
+ECDH-RSA-AES128-GCM-SHA256:\
+ECDH-ECDSA-AES128-GCM-SHA256:\
+ECDHE-RSA-AES256-GCM-SHA384:\
+AES128-SHA
+   </screen>
+   <screen>
+    # Use keywords instead of explicity naming the ciphers (Does not work with MbedTLS)
+    cipher-list ALL:!EXPORT:!EXPORT40:!EXPORT56:!aNULL:!LOW:!RC4:@STRENGTH
+   </screen>
+  </listitem>
+ </varlistentry>
+</variablelist>
+</sect3>
+
+<!--  ~  End section  ~  -->
+
+<!--   ~~~~~       New section      ~~~~~     -->
+
 <sect3 renderas="sect4" id="trusted-cas-file"><title>trusted-cas-file</title>
 <variablelist>
  <varlistentry>
@@ -4273,7 +4417,7 @@ forward-socks4, forward-socks4a, forward-socks5 and forward-socks5t</title>
   </listitem>
  </varlistentry>
  <varlistentry>
-  <term>Examples:</term>
+  <term>Example:</term>
   <listitem>
    <para>
     trusted-cas-file trusted_cas_file.pem