+
+<para>
+ These templates are stored in a subdirectory of the <link linkend="confdir">configuration
+ directory</link> called <filename>templates</filename>. On Unixish platforms,
+ this is typically
+ <ulink url="file:///etc/privoxy/templates/"><filename>/etc/privoxy/templates/</filename></ulink>.
+</para>
+
+<para>
+ The templates are basically normal HTML files, but with place-holders (called symbols
+ or exports), which <application>Privoxy</application> fills at run time. It
+ is possible to edit the templates with a normal text editor, should you want
+ to customize them. (<emphasis>Not recommended for the casual
+ user</emphasis>). Should you create your own custom templates, you should use
+ the <filename>config</filename> setting <link linkend="templdir">templdir</link>
+ to specify an alternate location, so your templates do not get overwritten
+ during upgrades.
+ </para>
+ <para>
+ Note that just like in configuration files, lines starting
+ with <literal>#</literal> are ignored when the templates are filled in.
+</para>
+
+<para>
+ The place-holders are of the form <literal>@name@</literal>, and you will
+ find a list of available symbols, which vary from template to template,
+ in the comments at the start of each file. Note that these comments are not
+ always accurate, and that it's probably best to look at the existing HTML
+ code to find out which symbols are supported and what they are filled in with.
+</para>
+
+<para>
+ A special application of this substitution mechanism is to make whole
+ blocks of HTML code disappear when a specific symbol is set. We use this
+ for many purposes, one of them being to include the beta warning in all
+ our user interface (CGI) pages when <application>Privoxy</application>
+ is in an alpha or beta development stage:
+</para>
+
+ <screen>
+<!-- @if-unstable-start -->
+
+ ... beta warning HTML code goes here ...
+
+<!-- if-unstable-end@ --></screen>
+
+<para>
+ If the "unstable" symbol is set, everything in between and including
+ <literal>@if-unstable-start</literal> and <literal>if-unstable-end@</literal>
+ will disappear, leaving nothing but an empty comment:
+</para>
+
+ <screen><!-- --></screen>
+
+<para>
+ There's also an if-then-else construct and an <literal>#include</literal>
+ mechanism, but you'll sure find out if you are inclined to edit the
+ templates ;-)
+</para>
+
+<para>
+ All templates refer to a style located at
+ <ulink url="http://config.privoxy.org/send-stylesheet"><literal>http://config.privoxy.org/send-stylesheet</literal></ulink>.
+ This is, of course, locally served by <application>Privoxy</application>
+ and the source for it can be found and edited in the
+ <filename>cgi-style.css</filename> template.
+</para>
+
+</sect1>
+
+<!-- ~ End section ~ -->
+
+
+<!-- ~~~~~ New section ~~~~~ -->
+
+<sect1 id="howto"><title>HOWTOs</title>
+
+<!-- ~~~~~~~~ New section Header ~~~~~~~~~ -->
+<sect2 id="h2-https-inspection"><title>HTTPS-Inspection HOWTO</title>
+<sect3 id="h2-hi-tls"><title>How TLS Certificates for websites work
+</title>
+<para>
+ The website owner generates a (private) TLS key and a Certificate
+ Signing Request (CSR).
+</para>
+<para>
+ The CSR is then sent to a Certification Authority (CA), which
+ verifies that the owner is the actual owner of the website. This can
+ be done by proving that the owner has technical write access to the
+ site or the site's DNS, or by verifying the identity of the
+ organization running the site using telephone and public databases.
+</para>
+<para>
+ If the verification is successful, the CA signs the CSR and creates a
+ certificate that certifies that the private TLS key actually belongs
+ to the website name and/or organization that owns the domain.
+</para>
+<para>
+ This TLS certificate is then added to the web server configuration,
+ and when a browser accesses the website, it verifies that the TLS
+ certificate presented to the browser is valid for that domain.
+</para>
+<para>
+ To do this, each browser has the certificates of multiple CAs in its
+ trust store. Only if the certificate of the CA, that signed the web
+ server is in the trust store, the browser will accept the
+ certificate, otherwise the browser will complain about a broken
+ certificate.
+</para>
+<para>
+ If this check passes, the browser sends a random number encrypted
+ with the server's public key to the server, and both compute a shared
+ secret using the Diffie-Hellman key exchange algorithm. Now server
+ and browser can communicate, but no one else can break that
+ communication because it's encrypted between them.
+</para>
+</sect3>
+
+<sect3 id="h2-hi-works"><title>How HTTPS inspection works</title>
+<para>
+ When we try to inspect HTTPS traffic, we have to break the TLS
+ encryption between browser and web server without being the browser
+ or the web server. This is exactly what TLS tries to avoid, as it's
+ a man-in-the-middle-attack.
+</para>
+<para>
+ To do this, Privoxy uses it's own (private) CA (let's call it
+ "Privoxy CA"), which has to be added to the trust store of every
+ single browser that should be used with Privoxy and HTTPS inspection.
+</para>
+<para>
+ Now Privoxy breaks the connection between browser and webserver by
+ acting as a browser/client when talking to the webserver (including
+ checking the webserver's TLS certificate against it's own trust
+ store). Now Privoxy can read and modify the traffic from the
+ webserver.
+</para>
+<para>
+ On the other hand, Privoxy itself encrypts the traffic it sends to
+ the browser using an on the fly self-created TLS server certificate
+ that is signed by Privoxy CA.
+</para>
+</sect3>
+
+<sect3 id="h2-hi-invalid-cert"><title>What happens, if the original
+ certificate is invalid?</title>
+<para>
+ If Privoxy detects, that a TLS certificate is not valid, because the
+ certificate is expired, doesn't match the hostname, is self signed or
+ similar, Privoxy blocks the requests and returns an error message
+ explaining the problem to avoid that the user/browser communicates
+ over an insecure communication channel.
+</para>
+<para>
+ To check this behavior, simply go to
+ <ulink url="https://badssl.com/">https://badssl.com/</ulink>
+</para>
+</sect3>
+
+<sect3 id="h2-hi-prerequisites"><title>HTTPS inspection prerequisites
+</title>
+<para>
+ HTTPS inspection in Privoxy can only be used, if Privoxy is built
+ with FEATURE_HTTPS_INSPECTION. You can check if this feature
+ is enabled at
+ <ulink url="http://config.privoxy.org/show-status">http://config.privoxy.org/show-status</ulink>
+ in the "Conditional #defines" section.
+</para>
+<para>
+ If the feature is not enabled, you may need to
+ <link linkend="installation-source">build Privoxy from source</link>
+ to enable it. You can use either
+ <ulink url="https://www.trustedfirmware.org/projects/mbed-tls/">MbedTLS</ulink>
+ or <ulink url="https://www.openssl.org/">OpenSSL</ulink>. It's up to
+ you, which one to use, they both behave the same for HTTPS inspection.
+</para>
+<para>
+ After installing the development libraries for either OpenSSL or
+ MbedTLS, you can run <command>./configure</command> with
+ either the <command>--with-openssl</command> or
+ <command>--with-mbedtls</command> option.
+</para>
+<para>
+ Check the output of <command>./configure</command>, it must contain
+ one of these the following two lines, otherwise HTTPS inspection will
+ not work:
+</para>
+ <screen>
+configure: Detected OpenSSL. Enabling https inspection.
+configure: Detected mbedTLS. Enabling https inspection.
+</screen>
+<para>
+ If you do not find any of these lines, the output of
+ <command>./configure</command> will tell you what went wrong.
+</para>
+<para>
+ You should then proceed with the
+ <link linkend="installation-source">source install</link>.
+ Finally, check the FEATURE_HTTPS_INSPECTION status in
+ <ulink url="http://config.privoxy.org/show-status">http://config.privoxy.org/show-status</ulink>
+ again.
+</para>
+</sect3>
+
+<sect3 id="h2-hi-config"><title>Configuring HTTPS inspection in Privoxy
+</title>
+<para>
+ First, you need to create the private key and certificate for the
+ "Privoxy CA". This can be done using openssl with the following
+ command:
+ <screen>
+openssl req -new -x509 -extensions v3_ca -keyout privoxy.pem -out privoxy.crt -days 3650
+</screen>
+</para>
+<para>
+ Here we have defined a CA validity of 10 years (3650 days). You
+ should decide for yourself what is a good validity. A shorter
+ validity makes your system more secure (it doesn't hurt that long if
+ the key gets lost to an attacker), but if the certificate expires
+ before you have replaced it with a new one in Privoxy and in all
+ browsers, the communication will fail.
+</para>
+<para>
+ During the key generation you will be asked for a "pass phrase".
+ This pass phrase will appear in the Privoxy config CGI, so don't
+ reuse it elsewhere!
+</para>
+<para>
+ Then you will be asked for Country Name, State/Province, Locality,
+ Orginzation Name, Common Name, and Email Address. You should add
+ some useful data here, because these entries are shown by the browser
+ as "Issuer Name" when you inspect a certificate from an
+ https-inspection site. Especially the "Common Name" will be shown as
+ the name of your CA, so it's good if you (and other users of your
+ Privoxy instance) are able to identify this CA.
+</para>
+<para>
+ Copy the private key (<filename>privoxy.pem</filename>) and the CA
+ certificate (<filename>privoxy.crt</filename>) into
+ the <link linkend="ca-directory">ca-directory</link> (defined
+ in <link linkend="config">config</link>).
+</para>
+<para>
+ Make sure that the private key (<filename>privoxy.pem</filename> in
+ the above example) is only accessible to the user running Privoxy
+ (usually named "privoxy"):
+</para>
+ <screen>
+chmod 600 privoxy.pem
+chown privoxy privoxy.pem
+</screen>
+<para>
+ Now adjust your Privoxy <link linkend="config">configuration</link>:
+</para>
+ <screen>
+<link linkend="ca-directory">ca-directory</link> /etc/privoxy/CA # read-only
+<link linkend="ca-cert-file">ca-cert-file</link> privoxy.crt # in ca-directory
+<link linkend="ca-key-file">ca-key-file</link> privoxy.pem # in ca-directory
+<link linkend="ca-password">ca-password</link> passphrasefromabove
+<link linkend="certificate-directory">certificate-directory</link> /var/lib/privoxy/certs
+<link linkend="trusted-cas-file">trusted-cas-file</link> /etc/ssl/certs/ca-certificates.crt
+</screen>