Regenerate user-manual with HOWTOs.
authorRoland Rosenfeld <roland@debian.org>
Mon, 20 Feb 2023 10:31:09 +0000 (11:31 +0100)
committerRoland Rosenfeld <roland@debian.org>
Mon, 20 Feb 2023 10:36:18 +0000 (11:36 +0100)
doc/webserver/user-manual/appendix.html
doc/webserver/user-manual/contact.html
doc/webserver/user-manual/copyright.html
doc/webserver/user-manual/howto.html [new file with mode: 0644]
doc/webserver/user-manual/index.html
doc/webserver/user-manual/seealso.html
doc/webserver/user-manual/templates.html

index e78842a..7efbff0 100644 (file)
@@ -25,9 +25,9 @@
     <hr align="left" width="100%">
   </div>
   <div class="SECT1">
-    <h1 class="SECT1"><a name="APPENDIX" id="APPENDIX">14. Appendix</a></h1>
+    <h1 class="SECT1"><a name="APPENDIX" id="APPENDIX">15. Appendix</a></h1>
     <div class="SECT2">
-      <h2 class="SECT2"><a name="REGEX" id="REGEX">14.1. Regular Expressions</a></h2>
+      <h2 class="SECT2"><a name="REGEX" id="REGEX">15.1. Regular Expressions</a></h2>
       <p><span class="APPLICATION">Privoxy</span> uses Perl-style <span class="QUOTE">"regular expressions"</span> in
       its <a href="actions-file.html">actions files</a> and <a href="filter-file.html">filter file</a>, through the
       <a href="http://www.pcre.org/" target="_top">PCRE</a> and <span class="APPLICATION">PCRS</span> libraries.</p>
       <a href="filter-file.html">filter file tutorial</a> in this manual.</p>
     </div>
     <div class="SECT2">
-      <h2 class="SECT2"><a name="INTERNAL-PAGES" id="INTERNAL-PAGES">14.2. Privoxy's Internal Pages</a></h2>
+      <h2 class="SECT2"><a name="INTERNAL-PAGES" id="INTERNAL-PAGES">15.2. Privoxy's Internal Pages</a></h2>
       <p>Since <span class="APPLICATION">Privoxy</span> proxies each requested web page, it is easy for <span class=
       "APPLICATION">Privoxy</span> to trap certain special URLs. In this way, we can talk directly to <span class=
       "APPLICATION">Privoxy</span>, and see how it is configured, see how our rules are being applied, change these
       these. If not, you will get a friendly error message. Internet access is not necessary either.</p>
       <ul>
         <li>
-          <p>Privoxy main page:</p><a name="AEN6438" id="AEN6438"></a>
+          <p>Privoxy main page:</p><a name="AEN6566" id="AEN6566"></a>
           <blockquote class="BLOCKQUOTE">
             <p><a href="http://config.privoxy.org/" target="_top">http://config.privoxy.org/</a></p>
           </blockquote>
           "APPLICATION">Privoxy</span>)</p>
         </li>
         <li>
-          <p>View and toggle client tags:</p><a name="AEN6446" id="AEN6446"></a>
+          <p>View and toggle client tags:</p><a name="AEN6574" id="AEN6574"></a>
           <blockquote class="BLOCKQUOTE">
             <p><a href="http://config.privoxy.org/client-tags" target=
             "_top">http://config.privoxy.org/client-tags</a></p>
         </li>
         <li>
           <p>Show information about the current configuration, including viewing and editing of actions
-          files:</p><a name="AEN6451" id="AEN6451"></a>
+          files:</p><a name="AEN6579" id="AEN6579"></a>
           <blockquote class="BLOCKQUOTE">
             <p><a href="http://config.privoxy.org/show-status" target=
             "_top">http://config.privoxy.org/show-status</a></p>
           </blockquote>
         </li>
         <li>
-          <p>Show the browser's request headers:</p><a name="AEN6456" id="AEN6456"></a>
+          <p>Show the browser's request headers:</p><a name="AEN6584" id="AEN6584"></a>
           <blockquote class="BLOCKQUOTE">
             <p><a href="http://config.privoxy.org/show-request" target=
             "_top">http://config.privoxy.org/show-request</a></p>
           </blockquote>
         </li>
         <li>
-          <p>Show which actions apply to a URL and why:</p><a name="AEN6461" id="AEN6461"></a>
+          <p>Show which actions apply to a URL and why:</p><a name="AEN6589" id="AEN6589"></a>
           <blockquote class="BLOCKQUOTE">
             <p><a href="http://config.privoxy.org/show-url-info" target=
             "_top">http://config.privoxy.org/show-url-info</a></p>
         <li>
           <p>Toggle Privoxy on or off. This feature can be turned off/on in the main <tt class="FILENAME">config</tt>
           file. When toggled <span class="QUOTE">"off"</span>, <span class="QUOTE">"Privoxy"</span> continues to run,
-          but only as a pass-through proxy, with no actions taking place:</p><a name="AEN6469" id="AEN6469"></a>
+          but only as a pass-through proxy, with no actions taking place:</p><a name="AEN6597" id="AEN6597"></a>
           <blockquote class="BLOCKQUOTE">
             <p><a href="http://config.privoxy.org/toggle" target="_top">http://config.privoxy.org/toggle</a></p>
           </blockquote>
-          <p>Short cuts. Turn off, then on:</p><a name="AEN6473" id="AEN6473"></a>
+          <p>Short cuts. Turn off, then on:</p><a name="AEN6601" id="AEN6601"></a>
           <blockquote class="BLOCKQUOTE">
             <p><a href="http://config.privoxy.org/toggle?set=disable" target=
             "_top">http://config.privoxy.org/toggle?set=disable</a></p>
-          </blockquote><a name="AEN6476" id="AEN6476"></a>
+          </blockquote><a name="AEN6604" id="AEN6604"></a>
           <blockquote class="BLOCKQUOTE">
             <p><a href="http://config.privoxy.org/toggle?set=enable" target=
             "_top">http://config.privoxy.org/toggle?set=enable</a></p>
       </ul>
     </div>
     <div class="SECT2">
-      <h2 class="SECT2"><a name="CHAIN" id="CHAIN">14.3. Chain of Events</a></h2>
+      <h2 class="SECT2"><a name="CHAIN" id="CHAIN">15.3. Chain of Events</a></h2>
       <p>Let's take a quick look at how some of <span class="APPLICATION">Privoxy's</span> core features are triggered,
       and the ensuing sequence of events when a web page is requested by your browser:</p>
       <ul>
       and simplicity, we have focused on <span class="APPLICATION">Privoxy's</span> core features only.</p>
     </div>
     <div class="SECT2">
-      <h2 class="SECT2"><a name="ACTIONSANAT" id="ACTIONSANAT">14.4. Troubleshooting: Anatomy of an Action</a></h2>
+      <h2 class="SECT2"><a name="ACTIONSANAT" id="ACTIONSANAT">15.4. Troubleshooting: Anatomy of an Action</a></h2>
       <p>The way <span class="APPLICATION">Privoxy</span> applies <a href="actions-file.html#ACTIONS">actions</a> and
       <a href="actions-file.html#FILTER">filters</a> to any given URL can be complex, and not always so easy to
       understand what is happening. And sometimes we need to be able to <span class="emphasis"><i class=
index 8f412b3..32e6813 100644 (file)
@@ -5,7 +5,7 @@
   <title>Contacting the Developers, Bug Reporting and Feature Requests</title>
   <meta name="GENERATOR" content="Modular DocBook HTML Stylesheet Version 1.79">
   <link rel="HOME" title="Privoxy 3.0.35 User Manual" href="index.html">
-  <link rel="PREVIOUS" title="Privoxy's Template Files" href="templates.html">
+  <link rel="PREVIOUS" title="HOWTOs" href="howto.html">
   <link rel="NEXT" title="Privoxy Copyright, License and History" href="copyright.html">
   <link rel="STYLESHEET" type="text/css" href="../p_doc.css">
   <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
@@ -18,7 +18,7 @@
         <th colspan="3" align="center">Privoxy 3.0.35 User Manual</th>
       </tr>
       <tr>
-        <td width="10%" align="left" valign="bottom"><a href="templates.html" accesskey="P">Prev</a></td>
+        <td width="10%" align="left" valign="bottom"><a href="howto.html" accesskey="P">Prev</a></td>
         <td width="80%" align="center" valign="bottom"></td>
         <td width="10%" align="right" valign="bottom"><a href="copyright.html" accesskey="N">Next</a></td>
       </tr>
     <hr align="left" width="100%">
   </div>
   <div class="SECT1">
-    <h1 class="SECT1"><a name="CONTACT" id="CONTACT">11. Contacting the Developers, Bug Reporting and Feature
+    <h1 class="SECT1"><a name="CONTACT" id="CONTACT">12. Contacting the Developers, Bug Reporting and Feature
     Requests</a></h1>
     <p>We value your feedback. In fact, we rely on it to improve <span class="APPLICATION">Privoxy</span> and its
     configuration. However, please note the following hints, so we can provide you with the best support.</p>
     <div class="SECT2">
-      <h2 class="SECT2"><a name="SUFFICIENT-INFORMATION" id="SUFFICIENT-INFORMATION">11.1. Please provide sufficient
+      <h2 class="SECT2"><a name="SUFFICIENT-INFORMATION" id="SUFFICIENT-INFORMATION">12.1. Please provide sufficient
       information</a></h2>
       <p>A lot of support requests don't contain enough information and can't be solved without a lot of back and forth
       which causes unnecessary delays. Reading this section should help to prevent that.</p>
       <tt class="LITERAL">action</tt> debugging.</p>
     </div>
     <div class="SECT2">
-      <h2 class="SECT2"><a name="CONTACT-SUPPORT" id="CONTACT-SUPPORT">11.2. Get Support</a></h2>
+      <h2 class="SECT2"><a name="CONTACT-SUPPORT" id="CONTACT-SUPPORT">12.2. Get Support</a></h2>
       <p>All users are welcome to discuss their issues on the <a href=
       "https://lists.privoxy.org/mailman/listinfo/privoxy-users" target="_top">users mailing list</a>, where the
       developers also hang around.</p>
       mailing list only, and you won't see them.</p>
     </div>
     <div class="SECT2">
-      <h2 class="SECT2"><a name="REPORTING" id="REPORTING">11.3. Reporting Problems</a></h2>
+      <h2 class="SECT2"><a name="REPORTING" id="REPORTING">12.3. Reporting Problems</a></h2>
       <p><span class="QUOTE">"Problems"</span> for our purposes, come in two forms:</p>
       <ul>
         <li>
         </li>
       </ul>
       <div class="SECT3">
-        <h3 class="SECT3"><a name="CONTACT-ADS" id="CONTACT-ADS">11.3.1. Reporting Ads or Other Configuration
+        <h3 class="SECT3"><a name="CONTACT-ADS" id="CONTACT-ADS">12.3.1. Reporting Ads or Other Configuration
         Problems</a></h3>
         <p>Please send feedback on ads that slipped through, innocent images that were blocked, sites that don't work
         properly, and other configuration related problem of <tt class="FILENAME">default.action</tt> file, to <a href=
         "_top">https://sourceforge.net/p/ijbswa/actionsfile-feedback/</a>, the Actions File Tracker.</p>
       </div>
       <div class="SECT3">
-        <h3 class="SECT3"><a name="CONTACT-BUGS" id="CONTACT-BUGS">11.3.2. Reporting Bugs</a></h3>
+        <h3 class="SECT3"><a name="CONTACT-BUGS" id="CONTACT-BUGS">12.3.2. Reporting Bugs</a></h3>
         <p>Before reporting bugs, please make sure that the bug has <span class="emphasis"><i class="EMPHASIS">not
         already been submitted</i></span> and observe the additional hints at the top of the <a href=
         "https://sourceforge.net/p/ijbswa/bugs/" target="_top">submit form</a>. If already submitted, please feel free
       </div>
     </div>
     <div class="SECT2">
-      <h2 class="SECT2"><a name="SECURITY-CONTACT" id="SECURITY-CONTACT">11.4. Reporting security problems</a></h2>
+      <h2 class="SECT2"><a name="SECURITY-CONTACT" id="SECURITY-CONTACT">12.4. Reporting security problems</a></h2>
       <p>If you discovered a security problem or merely suspect that a bug might be a security issue, please mail
       Fabian Keil &lt;fk@fabiankeil.de&#62; (OpenPGP fingerprint: 4F36 C17F 3816 9136 54A1 E850 6918 2291 8BA2
       371C).</p>
       didn't make it. If that happens, please mail to the developer list to request a status update.</p>
     </div>
     <div class="SECT2">
-      <h2 class="SECT2"><a name="MAILING-LISTS" id="MAILING-LISTS">11.5. Mailing Lists</a></h2>
+      <h2 class="SECT2"><a name="MAILING-LISTS" id="MAILING-LISTS">12.5. Mailing Lists</a></h2>
       <p>If you prefer to communicate through email, instead of using a web interface, feel free to use one of the
       mailing lists. To discuss issues that haven't been completely diagnosed yet, please use the Privoxy users list.
       Technically interested users and people who wish to contribute to the project are always welcome on the
       "https://sourceforge.net/p/ijbswa/mailman/" target="_top">https://sourceforge.net/p/ijbswa/mailman/</a>.</p>
     </div>
     <div class="SECT2">
-      <h2 class="SECT2"><a name="SF-TRACKERS" id="SF-TRACKERS">11.6. SourceForge support trackers</a></h2>
+      <h2 class="SECT2"><a name="SF-TRACKERS" id="SF-TRACKERS">12.6. SourceForge support trackers</a></h2>
       <p>The <a href="https://sourceforge.net/p/ijbswa/support-requests/" target="_top">SourceForge support
       trackers</a> may be used as well, but have various technical problems that are unlikely to be fixed anytime soon.
       If you don't get a timely response, please try the mailing list as well.</p>
     <hr align="left" width="100%">
     <table summary="Footer navigation table" width="100%" border="0" cellpadding="0" cellspacing="0">
       <tr>
-        <td width="33%" align="left" valign="top"><a href="templates.html" accesskey="P">Prev</a></td>
+        <td width="33%" align="left" valign="top"><a href="howto.html" accesskey="P">Prev</a></td>
         <td width="34%" align="center" valign="top"><a href="index.html" accesskey="H">Home</a></td>
         <td width="33%" align="right" valign="top"><a href="copyright.html" accesskey="N">Next</a></td>
       </tr>
       <tr>
-        <td width="33%" align="left" valign="top">Privoxy's Template Files</td>
+        <td width="33%" align="left" valign="top">HOWTOs</td>
         <td width="34%" align="center" valign="top">&nbsp;</td>
         <td width="33%" align="right" valign="top">Privoxy Copyright, License and History</td>
       </tr>
index 74ec3f1..d40237c 100644 (file)
@@ -26,7 +26,7 @@
     <hr align="left" width="100%">
   </div>
   <div class="SECT1">
-    <h1 class="SECT1"><a name="COPYRIGHT">12. Privoxy Copyright, License and History</a></h1>
+    <h1 class="SECT1"><a name="COPYRIGHT">13. Privoxy Copyright, License and History</a></h1>
     <p>Copyright &copy; 2001-2023 by Privoxy Developers <code class="EMAIL">&#60;<a href=
     "mailto:privoxy-devel@lists.privoxy.org">privoxy-devel@lists.privoxy.org</a>&#62;</code></p>
     <p>Some source code is based on code Copyright &copy; 1997 by Anonymous Coders and Junkbusters, Inc.</p>
@@ -40,9 +40,9 @@
     Software Foundation, either version 3 of the license, or (at your option) any later version.</p>
     <p>Both licenses are included in the next section.</p>
     <div class="SECT2">
-      <h2 class="SECT2"><a name="LICENSE">12.1. License</a></h2>
+      <h2 class="SECT2"><a name="LICENSE">13.1. License</a></h2>
       <div class="SECT3">
-        <h3 class="SECT3"><a name="GPLV2">12.1.1. GNU General Public License version 2</a></h3>
+        <h3 class="SECT3"><a name="GPLV2">13.1.1. GNU General Public License version 2</a></h3>
         <table border="0" bgcolor="#E0E0E0" width="100%">
           <tr>
             <td>
@@ -391,7 +391,7 @@ Public License instead of this License.
         </table>
       </div>
       <div class="SECT3">
-        <h3 class="SECT3"><a name="GPLV3">12.1.2. GNU General Public License version 3</a></h3>
+        <h3 class="SECT3"><a name="GPLV3">13.1.2. GNU General Public License version 3</a></h3>
         <table border="0" bgcolor="#E0E0E0" width="100%">
           <tr>
             <td>
@@ -1075,7 +1075,7 @@ Public License instead of this License.  But first, please read
         </table>
       </div>
       <div class="SECT3">
-        <h3 class="SECT3"><a name="THIRD-PARTY-LICENSES">12.1.3. Third-party licenses and copyrights</a></h3>
+        <h3 class="SECT3"><a name="THIRD-PARTY-LICENSES">13.1.3. Third-party licenses and copyrights</a></h3>
         <p>Privoxy depends on a couple of third-party libraries which have seperate licenses. Please refer to the
         third-party websites for up-to-date license and copyright information.</p>
         <p>Privoxy depends on <a href="https://pcre.org/" target="_top">pcre</a>.</p>
@@ -1090,7 +1090,7 @@ Public License instead of this License.  But first, please read
       </div>
     </div>
     <div class="SECT2">
-      <h2 class="SECT2"><a name="HISTORY">12.2. History</a></h2>
+      <h2 class="SECT2"><a name="HISTORY">13.2. History</a></h2>
       <p>A long time ago, there was the <span class="APPLICATION">Internet Junkbuster</span>, by Anonymous Coders and
       Junkbusters Corporation. This saved many users a lot of pain in the early days of web advertising and user
       tracking.</p>
@@ -1115,7 +1115,7 @@ Public License instead of this License.  But first, please read
       is still actively maintained.</p>
     </div>
     <div class="SECT2">
-      <h2 class="SECT2"><a name="AUTHORS">12.3. Authors</a></h2>
+      <h2 class="SECT2"><a name="AUTHORS">13.3. Authors</a></h2>
       <p>Current Privoxy Team:</p>
       <p class="LITERALLAYOUT">&nbsp;Fabian&nbsp;Keil,&nbsp;lead&nbsp;developer<br>
       &nbsp;David&nbsp;Schmidt<br>
diff --git a/doc/webserver/user-manual/howto.html b/doc/webserver/user-manual/howto.html
new file mode 100644 (file)
index 0000000..f33daee
--- /dev/null
@@ -0,0 +1,277 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
+"http://www.w3.org/TR/html4/loose.dtd">
+<html>
+<head>
+  <title>HOWTOs</title>
+  <meta name="GENERATOR" content="Modular DocBook HTML Stylesheet Version 1.79">
+  <link rel="HOME" title="Privoxy 3.0.35 User Manual" href="index.html">
+  <link rel="PREVIOUS" title="Privoxy's Template Files" href="templates.html">
+  <link rel="NEXT" title="Contacting the Developers, Bug Reporting and Feature Requests" href="contact.html">
+  <link rel="STYLESHEET" type="text/css" href="../p_doc.css">
+  <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
+  <link rel="STYLESHEET" type="text/css" href="p_doc.css">
+</head>
+<body class="SECT1" bgcolor="#EEEEEE" text="#000000" link="#0000FF" vlink="#840084" alink="#0000FF">
+  <div class="NAVHEADER">
+    <table summary="Header navigation table" width="100%" border="0" cellpadding="0" cellspacing="0">
+      <tr>
+        <th colspan="3" align="center">Privoxy 3.0.35 User Manual</th>
+      </tr>
+      <tr>
+        <td width="10%" align="left" valign="bottom"><a href="templates.html" accesskey="P">Prev</a></td>
+        <td width="80%" align="center" valign="bottom"></td>
+        <td width="10%" align="right" valign="bottom"><a href="contact.html" accesskey="N">Next</a></td>
+      </tr>
+    </table>
+    <hr align="left" width="100%">
+  </div>
+  <div class="SECT1">
+    <h1 class="SECT1"><a name="HOWTO" id="HOWTO">11. HOWTOs</a></h1>
+    <div class="SECT2">
+      <h2 class="SECT2"><a name="H2-HTTPS-INSPECTION" id="H2-HTTPS-INSPECTION">11.1. HTTPS-Inspection HOWTO</a></h2>
+      <div class="SECT3">
+        <h3 class="SECT3"><a name="H2-HI-TLS" id="H2-HI-TLS">11.1.1. How TLS Certificates for websites work</a></h3>
+        <p>The website owner generates a (private) TLS key and a Certificate Signing Request (CSR).</p>
+        <p>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.</p>
+        <p>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.</p>
+        <p>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.</p>
+        <p>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.</p>
+        <p>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.</p>
+      </div>
+      <div class="SECT3">
+        <h3 class="SECT3"><a name="H2-HI-WORKS" id="H2-HI-WORKS">11.1.2. How HTTPS inspection works</a></h3>
+        <p>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.</p>
+        <p>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.</p>
+        <p>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.</p>
+        <p>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.</p>
+      </div>
+      <div class="SECT3">
+        <h3 class="SECT3"><a name="H2-HI-INVALID-CERT" id="H2-HI-INVALID-CERT">11.1.3. What happens, if the original
+        certificate is invalid?</a></h3>
+        <p>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.</p>
+        <p>To check this behavior, simply go to <a href="https://badssl.com/" target="_top">https://badssl.com/</a></p>
+      </div>
+      <div class="SECT3">
+        <h3 class="SECT3"><a name="H2-HI-PREREQUISITES" id="H2-HI-PREREQUISITES">11.1.4. HTTPS inspection
+        prerequisites</a></h3>
+        <p>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 <a href="http://config.privoxy.org/show-status" target=
+        "_top">http://config.privoxy.org/show-status</a> in the "Conditional #defines" section.</p>
+        <p>If the feature is not enabled, you may need to <a href="installation.html#INSTALLATION-SOURCE">build Privoxy
+        from source</a> to enable it. You can use either <a href="https://www.trustedfirmware.org/projects/mbed-tls/"
+        target="_top">MbedTLS</a> or <a href="https://www.openssl.org/" target="_top">OpenSSL</a>. It's up to you,
+        which one to use, they both behave the same for HTTPS inspection.</p>
+        <p>After installing the development libraries for either OpenSSL or MbedTLS, you can run <b class=
+        "COMMAND">./configure</b> with either the <b class="COMMAND">--with-openssl</b> or <b class=
+        "COMMAND">--with-mbedtls</b> option.</p>
+        <p>Check the output of <b class="COMMAND">./configure</b>, it must contain one of these the following two
+        lines, otherwise HTTPS inspection will not work:</p>
+        <table border="0" bgcolor="#E0E0E0" width="100%">
+          <tr>
+            <td>
+              <pre class="SCREEN">  configure: Detected OpenSSL. Enabling https inspection.
+  configure: Detected mbedTLS. Enabling https inspection.</pre>
+            </td>
+          </tr>
+        </table>
+        <p>If you do not find any of these lines, the output of <b class="COMMAND">./configure</b> will tell you what
+        went wrong.</p>
+        <p>You should then proceed with the <a href="installation.html#INSTALLATION-SOURCE">source install</a>.
+        Finally, check the FEATURE_HTTPS_INSPECTION status in <a href="http://config.privoxy.org/show-status" target=
+        "_top">http://config.privoxy.org/show-status</a> again.</p>
+      </div>
+      <div class="SECT3">
+        <h3 class="SECT3"><a name="H2-HI-CONFIG" id="H2-HI-CONFIG">11.1.5. Configuring HTTPS inspection in
+        Privoxy</a></h3>
+        <p>First, you need to create the private key and certificate for the "Privoxy CA". This can be done using
+        openssl with the following command:</p>
+        <table border="0" bgcolor="#E0E0E0" width="100%">
+          <tr>
+            <td>
+              <pre class=
+              "SCREEN">  openssl req -new -x509 -extensions v3_ca -keyout privoxy.pem -out privoxy.crt -days 3650</pre>
+            </td>
+          </tr>
+        </table>
+        <p>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.</p>
+        <p>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!</p>
+        <p>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.</p>
+        <p>Copy the private key (<tt class="FILENAME">privoxy.pem</tt>) and the CA certificate (<tt class=
+        "FILENAME">privoxy.crt</tt>) into the <a href="config.html#CA-DIRECTORY">ca-directory</a> (defined in <a href=
+        "config.html">config</a>).</p>
+        <p>Make sure that the private key (<tt class="FILENAME">privoxy.pem</tt> in the above example) is only
+        accessible to the user running Privoxy (usually named "privoxy"):</p>
+        <table border="0" bgcolor="#E0E0E0" width="100%">
+          <tr>
+            <td>
+              <pre class="SCREEN">  chmod 600 privoxy.pem
+  chown privoxy privoxy.pem</pre>
+            </td>
+          </tr>
+        </table>
+        <p>Now adjust your Privoxy <a href="config.html">configuration</a>:</p>
+        <table border="0" bgcolor="#E0E0E0" width="100%">
+          <tr>
+            <td>
+              <pre class="SCREEN">  <a href="config.html#CA-DIRECTORY">ca-directory</a> /etc/privoxy/CA # read-only
+  <a href="config.html#CA-CERT-FILE">ca-cert-file</a> privoxy.crt     # in ca-directory
+  <a href="config.html#CA-KEY-FILE">ca-key-file</a> privoxy.pem      # in ca-directory
+  <a href="config.html#CA-PASSWORD">ca-password</a> passphrasefromabove
+  <a href="config.html#CERTIFICATE-DIRECTORY">certificate-directory</a> /var/lib/privoxy/certs
+  <a href="config.html#TRUSTED-CAS-FILE">trusted-cas-file</a> /etc/ssl/certs/ca-certificates.crt</pre>
+            </td>
+          </tr>
+        </table>
+        <p><a href="config.html#CERTIFICATE-DIRECTORY">certificate-directory</a> contains the (on the fly) created
+        webserver keys and certificates. It should only be readable by the privoxy user only:</p>
+        <table border="0" bgcolor="#E0E0E0" width="100%">
+          <tr>
+            <td>
+              <pre class="SCREEN">  chown privoxy /var/lib/privoxy/certs
+  chmod 700 /var/lib/privoxy/certs.</pre>
+            </td>
+          </tr>
+        </table>
+        <p><a href="config.html#TRUSTED-CAS-FILE">trusted-cas-file</a> is the trust store containing the certificates
+        of all CAs that should be accepted. Each browser comes with it's own trust store. Most Unix systems also ship
+        with a truststore. Debian ships it's truststore in <tt class=
+        "FILENAME">/etc/ssl/certs/ca-certificates.crt</tt>, which is installed by the ca-certificates package and can
+        be updated using update-ca-certificates(8). Alternatively, such a file (extracted from Mozilla) can be
+        downloaded from <a href="https://curl.se/docs/caextract.html" target=
+        "_top">https://curl.se/docs/caextract.html</a>.</p>
+      </div>
+      <div class="SECT3">
+        <h3 class="SECT3"><a name="H2-HI-BROWSER" id="H2-HI-BROWSER">11.1.6. Browser configuration</a></h3>
+        <p>As written above, each browser you use must now trust the newly created Privoxy CA certificate (<tt class=
+        "FILENAME">privoxy.crt</tt>).</p>
+        <p>In Firefox you can do this by opening the preferences "Edit" -&#62; "Settings" -&#62; "Privacy &#38;
+        Security" or by typing <a href="about:preferences#privacy" target="_top">about:preferences#privacy</a> in the
+        URL. Then go down to the "Certificates" section and click on "View Certificates". Click on the "Authorities"
+        tab and "Import..." your <tt class="FILENAME">privoxy.crt</tt>. In the "CA certificate trust settings" select
+        "This certificate can identify websites".</p>
+        <p>In Chrome based browsers, go to the settings and select "Privacy and security" (<a href=
+        "chrome://settings/privacy" target="_top">chrome://settings/privacy</a>). Click on "Security" and on the opened
+        sub-page on "Manage certificates". Now go to the "Authorities" tab and import <tt class=
+        "FILENAME">privoxy.crt</tt> and configure that you trust the certificate for website identification.</p>
+      </div>
+      <div class="SECT3">
+        <h3 class="SECT3"><a name="H2-HI-ENABLE" id="H2-HI-ENABLE">11.1.7. Enabeling HTTPS inspection</a></h3>
+        <p>Currently no pages use HTTPS inspection, you need to enable this for some (or all) domains first using
+        <a href="actions-file.html#USER-ACTION">user.action</a> (either by editing the file by hand or via the CGI
+        (this requires <a href="config.html#ENABLE-EDIT-ACTIONS">enable-edit-actions</a> to be enabled in config) at
+        <a href="http://config.privoxy.org/show-status" target="_top">http://config.privoxy.org/show-status</a> (click
+        on user.action Edit button).</p>
+        <p>Here you can enable HTTPS inspection for individual sites:</p>
+        <table border="0" bgcolor="#E0E0E0" width="100%">
+          <tr>
+            <td>
+              <pre class="SCREEN">  {+<a href="actions-file.html#HTTPS-INSPECTION">https-inspection</a>}
+  .badssl.com
+  clienttest.ssllabs.com</pre>
+            </td>
+          </tr>
+        </table>
+        <p>You can add more individual sites or wildcards (one per line).</p>
+        <p>Alternatively, you can use a client-tag to dynamically enable/disable this feature via the browser, as
+        described in the next chapter.</p>
+      </div>
+    </div>
+    <div class="SECT2">
+      <h2 class="SECT2"><a name="H2-CLIENT-TAGS" id="H2-CLIENT-TAGS">11.2. Client Tags HOWTO</a></h2>
+      <p>Client-Tags are a mechanism to dynamically/temporarily enable/disable features in Privoxy per browser.</p>
+      <p>In our example, we use this for the following two use cases:</p>
+      <ul>
+        <li>
+          <p>Enable TOR anonymous proxy</p>
+        </li>
+        <li>
+          <p>Enable https-inspection</p>
+        </li>
+      </ul>
+      <p>To use this feature, you must first define a tag name and a tag description for each client-tag in <a href=
+      "config.html">config</a>, like this:</p>
+      <table border="0" bgcolor="#E0E0E0" width="100%">
+        <tr>
+          <td>
+            <pre class="SCREEN">  <a href=
+            "config.html#CLIENT-SPECIFIC-TAG">client-specific-tag</a> tor Use Tor anonymous proxy
+  <a href="config.html#CLIENT-SPECIFIC-TAG">client-specific-tag</a> https-inspection Enable https-inspection</pre>
+          </td>
+        </tr>
+      </table>
+      <p>Now you can open <a href="http://config.privoxy.org/client-tags" target=
+      "_top">http://config.privoxy.org/client-tags</a> or <a href="http://p.p/client-tags" target=
+      "_top">http://p.p/client-tags</a> and can enable/disable the tag there (you may want to add a bookmark for this
+      in your browser for quick access, but it's also available as a link at <a href="http://p.p" target=
+      "_top">http://p.p</a>).</p>
+      <p>It's also possible to temporarily enable a tag, which by default means 3 minutes (=180 seconds) (and can be
+      changed via the <a href="config.html#CLIENT-TAG-LIFETIME">client-tag-lifetime</a> option in <a href=
+      "config.html">config</a>).</p>
+      <p>But before this has any effect, you have to use the client tag in your <a href=
+      "actions-file.html#USER-ACTION">user.action</a> like this:</p>
+      <table border="0" bgcolor="#E0E0E0" width="100%">
+        <tr>
+          <td>
+            <pre class="SCREEN">  {+<a href="actions-file.html#FORWARD-OVERRIDE">forward-override</a>{<a href=
+            "config.html#SOCKS">forward-socks5t</a> 127.0.0.1:9050 .} }
+  <a href="actions-file.html#CLIENT-TAG-PATTERN">CLIENT-TAG</a>:^tor$</pre>
+          </td>
+        </tr>
+      </table>
+      <p>This means, that if the "tor" client tag is enabled, all traffic is forwarded by Privoxy through socks5t to a
+      locally installed tor proxy listening on port 9050.</p>
+      <p>Similarly, you can specify to use the https-inspection client tag to enable https-inspection:</p>
+      <table border="0" bgcolor="#E0E0E0" width="100%">
+        <tr>
+          <td>
+            <pre class="SCREEN">  {+<a href="actions-file.html#HTTPS-INSPECTION">https-inspection</a>}
+  <a href="actions-file.html#CLIENT-TAG-PATTERN">CLIENT-TAG</a>:^https-inspection$</pre>
+          </td>
+        </tr>
+      </table>
+      <p>The tag will be set for all requests coming from clients that have requested it to be set. Note that "clients"
+      are distinguished by IP address, if the IP address changes, the tag must be requested again.</p>
+    </div>
+  </div>
+  <div class="NAVFOOTER">
+    <hr align="left" width="100%">
+    <table summary="Footer navigation table" width="100%" border="0" cellpadding="0" cellspacing="0">
+      <tr>
+        <td width="33%" align="left" valign="top"><a href="templates.html" accesskey="P">Prev</a></td>
+        <td width="34%" align="center" valign="top"><a href="index.html" accesskey="H">Home</a></td>
+        <td width="33%" align="right" valign="top"><a href="contact.html" accesskey="N">Next</a></td>
+      </tr>
+      <tr>
+        <td width="33%" align="left" valign="top">Privoxy's Template Files</td>
+        <td width="34%" align="center" valign="top">&nbsp;</td>
+        <td width="33%" align="right" valign="top">Contacting the Developers, Bug Reporting and Feature Requests</td>
+      </tr>
+    </table>
+  </div>
+</body>
+</html>
index 58edcc9..6bf8acc 100644 (file)
           </dl>
         </dd>
         <dt>10. <a href="templates.html">Privoxy's Template Files</a></dt>
-        <dt>11. <a href="contact.html">Contacting the Developers, Bug Reporting and Feature Requests</a></dt>
+        <dt>11. <a href="howto.html">HOWTOs</a></dt>
         <dd>
           <dl>
-            <dt>11.1. <a href="contact.html#SUFFICIENT-INFORMATION">Please provide sufficient information</a></dt>
-            <dt>11.2. <a href="contact.html#CONTACT-SUPPORT">Get Support</a></dt>
-            <dt>11.3. <a href="contact.html#REPORTING">Reporting Problems</a></dt>
+            <dt>11.1. <a href="howto.html#H2-HTTPS-INSPECTION">HTTPS-Inspection HOWTO</a></dt>
             <dd>
               <dl>
-                <dt>11.3.1. <a href="contact.html#CONTACT-ADS">Reporting Ads or Other Configuration Problems</a></dt>
-                <dt>11.3.2. <a href="contact.html#CONTACT-BUGS">Reporting Bugs</a></dt>
+                <dt>11.1.1. <a href="howto.html#H2-HI-TLS">How TLS Certificates for websites work</a></dt>
+                <dt>11.1.2. <a href="howto.html#H2-HI-WORKS">How HTTPS inspection works</a></dt>
+                <dt>11.1.3. <a href="howto.html#H2-HI-INVALID-CERT">What happens, if the original certificate is
+                invalid?</a></dt>
+                <dt>11.1.4. <a href="howto.html#H2-HI-PREREQUISITES">HTTPS inspection prerequisites</a></dt>
+                <dt>11.1.5. <a href="howto.html#H2-HI-CONFIG">Configuring HTTPS inspection in Privoxy</a></dt>
+                <dt>11.1.6. <a href="howto.html#H2-HI-BROWSER">Browser configuration</a></dt>
+                <dt>11.1.7. <a href="howto.html#H2-HI-ENABLE">Enabeling HTTPS inspection</a></dt>
               </dl>
             </dd>
-            <dt>11.4. <a href="contact.html#SECURITY-CONTACT">Reporting security problems</a></dt>
-            <dt>11.5. <a href="contact.html#MAILING-LISTS">Mailing Lists</a></dt>
-            <dt>11.6. <a href="contact.html#SF-TRACKERS">SourceForge support trackers</a></dt>
+            <dt>11.2. <a href="howto.html#H2-CLIENT-TAGS">Client Tags HOWTO</a></dt>
           </dl>
         </dd>
-        <dt>12. <a href="copyright.html">Privoxy Copyright, License and History</a></dt>
+        <dt>12. <a href="contact.html">Contacting the Developers, Bug Reporting and Feature Requests</a></dt>
         <dd>
           <dl>
-            <dt>12.1. <a href="copyright.html#LICENSE">License</a></dt>
+            <dt>12.1. <a href="contact.html#SUFFICIENT-INFORMATION">Please provide sufficient information</a></dt>
+            <dt>12.2. <a href="contact.html#CONTACT-SUPPORT">Get Support</a></dt>
+            <dt>12.3. <a href="contact.html#REPORTING">Reporting Problems</a></dt>
             <dd>
               <dl>
-                <dt>12.1.1. <a href="copyright.html#GPLV2">GNU General Public License version 2</a></dt>
-                <dt>12.1.2. <a href="copyright.html#GPLV3">GNU General Public License version 3</a></dt>
-                <dt>12.1.3. <a href="copyright.html#THIRD-PARTY-LICENSES">Third-party licenses and copyrights</a></dt>
+                <dt>12.3.1. <a href="contact.html#CONTACT-ADS">Reporting Ads or Other Configuration Problems</a></dt>
+                <dt>12.3.2. <a href="contact.html#CONTACT-BUGS">Reporting Bugs</a></dt>
               </dl>
             </dd>
-            <dt>12.2. <a href="copyright.html#HISTORY">History</a></dt>
-            <dt>12.3. <a href="copyright.html#AUTHORS">Authors</a></dt>
+            <dt>12.4. <a href="contact.html#SECURITY-CONTACT">Reporting security problems</a></dt>
+            <dt>12.5. <a href="contact.html#MAILING-LISTS">Mailing Lists</a></dt>
+            <dt>12.6. <a href="contact.html#SF-TRACKERS">SourceForge support trackers</a></dt>
           </dl>
         </dd>
-        <dt>13. <a href="seealso.html">See Also</a></dt>
-        <dt>14. <a href="appendix.html">Appendix</a></dt>
+        <dt>13. <a href="copyright.html">Privoxy Copyright, License and History</a></dt>
         <dd>
           <dl>
-            <dt>14.1. <a href="appendix.html#REGEX">Regular Expressions</a></dt>
-            <dt>14.2. <a href="appendix.html#INTERNAL-PAGES">Privoxy's Internal Pages</a></dt>
-            <dt>14.3. <a href="appendix.html#CHAIN">Chain of Events</a></dt>
-            <dt>14.4. <a href="appendix.html#ACTIONSANAT">Troubleshooting: Anatomy of an Action</a></dt>
+            <dt>13.1. <a href="copyright.html#LICENSE">License</a></dt>
+            <dd>
+              <dl>
+                <dt>13.1.1. <a href="copyright.html#GPLV2">GNU General Public License version 2</a></dt>
+                <dt>13.1.2. <a href="copyright.html#GPLV3">GNU General Public License version 3</a></dt>
+                <dt>13.1.3. <a href="copyright.html#THIRD-PARTY-LICENSES">Third-party licenses and copyrights</a></dt>
+              </dl>
+            </dd>
+            <dt>13.2. <a href="copyright.html#HISTORY">History</a></dt>
+            <dt>13.3. <a href="copyright.html#AUTHORS">Authors</a></dt>
+          </dl>
+        </dd>
+        <dt>14. <a href="seealso.html">See Also</a></dt>
+        <dt>15. <a href="appendix.html">Appendix</a></dt>
+        <dd>
+          <dl>
+            <dt>15.1. <a href="appendix.html#REGEX">Regular Expressions</a></dt>
+            <dt>15.2. <a href="appendix.html#INTERNAL-PAGES">Privoxy's Internal Pages</a></dt>
+            <dt>15.3. <a href="appendix.html#CHAIN">Chain of Events</a></dt>
+            <dt>15.4. <a href="appendix.html#ACTIONSANAT">Troubleshooting: Anatomy of an Action</a></dt>
           </dl>
         </dd>
       </dl>
index 65ea6df..57e74a2 100644 (file)
@@ -26,7 +26,7 @@
     <hr align="left" width="100%">
   </div>
   <div class="SECT1">
-    <h1 class="SECT1"><a name="SEEALSO" id="SEEALSO">13. See Also</a></h1>
+    <h1 class="SECT1"><a name="SEEALSO" id="SEEALSO">14. See Also</a></h1>
     <p>Other references and sites of interest to <span class="APPLICATION">Privoxy</span> users:</p>
     <table border="0">
       <tbody>
index 74bdf59..c7d5eaa 100644 (file)
@@ -6,7 +6,7 @@
   <meta name="GENERATOR" content="Modular DocBook HTML Stylesheet Version 1.79">
   <link rel="HOME" title="Privoxy 3.0.35 User Manual" href="index.html">
   <link rel="PREVIOUS" title="Filter Files" href="filter-file.html">
-  <link rel="NEXT" title="Contacting the Developers, Bug Reporting and Feature Requests" href="contact.html">
+  <link rel="NEXT" title="HOWTOs" href="howto.html">
   <link rel="STYLESHEET" type="text/css" href="../p_doc.css">
   <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
   <link rel="STYLESHEET" type="text/css" href="p_doc.css">
@@ -20,7 +20,7 @@
       <tr>
         <td width="10%" align="left" valign="bottom"><a href="filter-file.html" accesskey="P">Prev</a></td>
         <td width="80%" align="center" valign="bottom"></td>
-        <td width="10%" align="right" valign="bottom"><a href="contact.html" accesskey="N">Next</a></td>
+        <td width="10%" align="right" valign="bottom"><a href="howto.html" accesskey="N">Next</a></td>
       </tr>
     </table>
     <hr align="left" width="100%">
       <tr>
         <td width="33%" align="left" valign="top"><a href="filter-file.html" accesskey="P">Prev</a></td>
         <td width="34%" align="center" valign="top"><a href="index.html" accesskey="H">Home</a></td>
-        <td width="33%" align="right" valign="top"><a href="contact.html" accesskey="N">Next</a></td>
+        <td width="33%" align="right" valign="top"><a href="howto.html" accesskey="N">Next</a></td>
       </tr>
       <tr>
         <td width="33%" align="left" valign="top">Filter Files</td>
         <td width="34%" align="center" valign="top">&nbsp;</td>
-        <td width="33%" align="right" valign="top">Contacting the Developers, Bug Reporting and Feature Requests</td>
+        <td width="33%" align="right" valign="top">HOWTOs</td>
       </tr>
     </table>
   </div>