doc/webserver/user-manual/howto.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
   2 "http://www.w3.org/TR/html4/loose.dtd">
   3 <html>
   4 <head>
   5   <title>HOWTOs</title>
   6   <meta name="GENERATOR" content="Modular DocBook HTML Stylesheet Version 1.79">
   7   <link rel="HOME" title="Privoxy 3.0.35 User Manual" href="index.html">
   8   <link rel="PREVIOUS" title="Privoxy's Template Files" href="templates.html">
   9   <link rel="NEXT" title="Contacting the Developers, Bug Reporting and Feature Requests" href="contact.html">
  10   <link rel="STYLESHEET" type="text/css" href="../p_doc.css">
  11   <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
  12   <link rel="STYLESHEET" type="text/css" href="p_doc.css">
  13 </head>
  14 <body class="SECT1" bgcolor="#EEEEEE" text="#000000" link="#0000FF" vlink="#840084" alink="#0000FF">
  15   <div class="NAVHEADER">
  16     <table summary="Header navigation table" width="100%" border="0" cellpadding="0" cellspacing="0">
  17       <tr>
  18         <th colspan="3" align="center">Privoxy 3.0.35 User Manual</th>
  19       </tr>
  20       <tr>
  21         <td width="10%" align="left" valign="bottom"><a href="templates.html" accesskey="P">Prev</a></td>
  22         <td width="80%" align="center" valign="bottom"></td>
  23         <td width="10%" align="right" valign="bottom"><a href="contact.html" accesskey="N">Next</a></td>
  24       </tr>
  25     </table>
  26     <hr align="left" width="100%">
  27   </div>
  28   <div class="SECT1">
  29     <h1 class="SECT1"><a name="HOWTO" id="HOWTO">11. HOWTOs</a></h1>
  30     <div class="SECT2">
  31       <h2 class="SECT2"><a name="H2-HTTPS-INSPECTION" id="H2-HTTPS-INSPECTION">11.1. HTTPS-Inspection HOWTO</a></h2>
  32       <div class="SECT3">
  33         <h3 class="SECT3"><a name="H2-HI-TLS" id="H2-HI-TLS">11.1.1. How TLS Certificates for websites work</a></h3>
  34         <p>The website owner generates a (private) TLS key and a Certificate Signing Request (CSR).</p>
  35         <p>The CSR is then sent to a Certification Authority (CA), which verifies that the owner is the actual owner of
  36         the website. This can be done by proving that the owner has technical write access to the site or the site's
  37         DNS, or by verifying the identity of the organization running the site using telephone and public
  38         databases.</p>
  39         <p>If the verification is successful, the CA signs the CSR and creates a certificate that certifies that the
  40         private TLS key actually belongs to the website name and/or organization that owns the domain.</p>
  41         <p>This TLS certificate is then added to the web server configuration, and when a browser accesses the website,
  42         it verifies that the TLS certificate presented to the browser is valid for that domain.</p>
  43         <p>To do this, each browser has the certificates of multiple CAs in its trust store. Only if the certificate of
  44         the CA, that signed the web server is in the trust store, the browser will accept the certificate, otherwise
  45         the browser will complain about a broken certificate.</p>
  46         <p>If this check passes, the browser sends a random number encrypted with the server's public key to the
  47         server, and both compute a shared secret using the Diffie-Hellman key exchange algorithm. Now server and
  48         browser can communicate, but no one else can break that communication because it's encrypted between them.</p>
  49       </div>
  50       <div class="SECT3">
  51         <h3 class="SECT3"><a name="H2-HI-WORKS" id="H2-HI-WORKS">11.1.2. How HTTPS inspection works</a></h3>
  52         <p>When we try to inspect HTTPS traffic, we have to break the TLS encryption between browser and web server
  53         without being the browser or the web server. This is exactly what TLS tries to avoid, as it's a
  54         man-in-the-middle-attack.</p>
  55         <p>To do this, Privoxy uses it's own (private) CA (let's call it "Privoxy CA"), which has to be added to the
  56         trust store of every single browser that should be used with Privoxy and HTTPS inspection.</p>
  57         <p>Now Privoxy breaks the connection between browser and webserver by acting as a browser/client when talking
  58         to the webserver (including checking the webserver's TLS certificate against it's own trust store). Now Privoxy
  59         can read and modify the traffic from the webserver.</p>
  60         <p>On the other hand, Privoxy itself encrypts the traffic it sends to the browser using an on the fly
  61         self-created TLS server certificate that is signed by Privoxy CA.</p>
  62       </div>
  63       <div class="SECT3">
  64         <h3 class="SECT3"><a name="H2-HI-INVALID-CERT" id="H2-HI-INVALID-CERT">11.1.3. What happens, if the original
  65         certificate is invalid?</a></h3>
  66         <p>If Privoxy detects, that a TLS certificate is not valid, because the certificate is expired, doesn't match
  67         the hostname, is self signed or similar, Privoxy blocks the requests and returns an error message explaining
  68         the problem to avoid that the user/browser communicates over an insecure communication channel.</p>
  69         <p>To check this behavior, simply go to <a href="https://badssl.com/" target="_top">https://badssl.com/</a></p>
  70       </div>
  71       <div class="SECT3">
  72         <h3 class="SECT3"><a name="H2-HI-PREREQUISITES" id="H2-HI-PREREQUISITES">11.1.4. HTTPS inspection
  73         prerequisites</a></h3>
  74         <p>HTTPS inspection in Privoxy can only be used, if Privoxy is built with FEATURE_HTTPS_INSPECTION. You can
  75         check if this feature is enabled at <a href="http://config.privoxy.org/show-status" target=
  76         "_top">http://config.privoxy.org/show-status</a> in the "Conditional #defines" section.</p>
  77         <p>If the feature is not enabled, you may need to <a href="installation.html#INSTALLATION-SOURCE">build Privoxy
  78         from source</a> to enable it. You can use either <a href="https://www.trustedfirmware.org/projects/mbed-tls/"
  79         target="_top">MbedTLS</a> or <a href="https://www.openssl.org/" target="_top">OpenSSL</a>. It's up to you,
  80         which one to use, they both behave the same for HTTPS inspection.</p>
  81         <p>After installing the development libraries for either OpenSSL or MbedTLS, you can run <b class=
  82         "COMMAND">./configure</b> with either the <b class="COMMAND">--with-openssl</b> or <b class=
  83         "COMMAND">--with-mbedtls</b> option.</p>
  84         <p>Check the output of <b class="COMMAND">./configure</b>, it must contain one of these the following two
  85         lines, otherwise HTTPS inspection will not work:</p>
  86         <table border="0" bgcolor="#E0E0E0" width="100%">
  87           <tr>
  88             <td>
  89               <pre class="SCREEN">  configure: Detected OpenSSL. Enabling https inspection.
  90   configure: Detected mbedTLS. Enabling https inspection.</pre>
  91             </td>
  92           </tr>
  93         </table>
  94         <p>If you do not find any of these lines, the output of <b class="COMMAND">./configure</b> will tell you what
  95         went wrong.</p>
  96         <p>You should then proceed with the <a href="installation.html#INSTALLATION-SOURCE">source install</a>.
  97         Finally, check the FEATURE_HTTPS_INSPECTION status in <a href="http://config.privoxy.org/show-status" target=
  98         "_top">http://config.privoxy.org/show-status</a> again.</p>
  99       </div>
 100       <div class="SECT3">
 101         <h3 class="SECT3"><a name="H2-HI-CONFIG" id="H2-HI-CONFIG">11.1.5. Configuring HTTPS inspection in
 102         Privoxy</a></h3>
 103         <p>First, you need to create the private key and certificate for the "Privoxy CA". This can be done using
 104         openssl with the following command:</p>
 105         <table border="0" bgcolor="#E0E0E0" width="100%">
 106           <tr>
 107             <td>
 108               <pre class=
 109               "SCREEN">  openssl req -new -x509 -extensions v3_ca -keyout privoxy.pem -out privoxy.crt -days 3650</pre>
 110             </td>
 111           </tr>
 112         </table>
 113         <p>Here we have defined a CA validity of 10 years (3650 days). You should decide for yourself what is a good
 114         validity. A shorter validity makes your system more secure (it doesn't hurt that long if the key gets lost to
 115         an attacker), but if the certificate expires before you have replaced it with a new one in Privoxy and in all
 116         browsers, the communication will fail.</p>
 117         <p>During the key generation you will be asked for a "pass phrase". This pass phrase will appear in the Privoxy
 118         config CGI, so don't reuse it elsewhere!</p>
 119         <p>Then you will be asked for Country Name, State/Province, Locality, Orginzation Name, Common Name, and Email
 120         Address. You should add some useful data here, because these entries are shown by the browser as "Issuer Name"
 121         when you inspect a certificate from an https-inspection site. Especially the "Common Name" will be shown as the
 122         name of your CA, so it's good if you (and other users of your Privoxy instance) are able to identify this
 123         CA.</p>
 124         <p>Copy the private key (<tt class="FILENAME">privoxy.pem</tt>) and the CA certificate (<tt class=
 125         "FILENAME">privoxy.crt</tt>) into the <a href="config.html#CA-DIRECTORY">ca-directory</a> (defined in <a href=
 126         "config.html">config</a>).</p>
 127         <p>Make sure that the private key (<tt class="FILENAME">privoxy.pem</tt> in the above example) is only
 128         accessible to the user running Privoxy (usually named "privoxy"):</p>
 129         <table border="0" bgcolor="#E0E0E0" width="100%">
 130           <tr>
 131             <td>
 132               <pre class="SCREEN">  chmod 600 privoxy.pem
 133   chown privoxy privoxy.pem</pre>
 134             </td>
 135           </tr>
 136         </table>
 137         <p>Now adjust your Privoxy <a href="config.html">configuration</a>:</p>
 138         <table border="0" bgcolor="#E0E0E0" width="100%">
 139           <tr>
 140             <td>
 141               <pre class="SCREEN">  <a href="config.html#CA-DIRECTORY">ca-directory</a> /etc/privoxy/CA # read-only
 142   <a href="config.html#CA-CERT-FILE">ca-cert-file</a> privoxy.crt     # in ca-directory
 143   <a href="config.html#CA-KEY-FILE">ca-key-file</a> privoxy.pem      # in ca-directory
 144   <a href="config.html#CA-PASSWORD">ca-password</a> passphrasefromabove
 145   <a href="config.html#CERTIFICATE-DIRECTORY">certificate-directory</a> /var/lib/privoxy/certs
 146   <a href="config.html#TRUSTED-CAS-FILE">trusted-cas-file</a> /etc/ssl/certs/ca-certificates.crt</pre>
 147             </td>
 148           </tr>
 149         </table>
 150         <p><a href="config.html#CERTIFICATE-DIRECTORY">certificate-directory</a> contains the (on the fly) created
 151         webserver keys and certificates. It should only be readable by the privoxy user only:</p>
 152         <table border="0" bgcolor="#E0E0E0" width="100%">
 153           <tr>
 154             <td>
 155               <pre class="SCREEN">  chown privoxy /var/lib/privoxy/certs
 156   chmod 700 /var/lib/privoxy/certs.</pre>
 157             </td>
 158           </tr>
 159         </table>
 160         <p><a href="config.html#TRUSTED-CAS-FILE">trusted-cas-file</a> is the trust store containing the certificates
 161         of all CAs that should be accepted. Each browser comes with it's own trust store. Most Unix systems also ship
 162         with a truststore. Debian ships it's truststore in <tt class=
 163         "FILENAME">/etc/ssl/certs/ca-certificates.crt</tt>, which is installed by the ca-certificates package and can
 164         be updated using update-ca-certificates(8). Alternatively, such a file (extracted from Mozilla) can be
 165         downloaded from <a href="https://curl.se/docs/caextract.html" target=
 166         "_top">https://curl.se/docs/caextract.html</a>.</p>
 167       </div>
 168       <div class="SECT3">
 169         <h3 class="SECT3"><a name="H2-HI-BROWSER" id="H2-HI-BROWSER">11.1.6. Browser configuration</a></h3>
 170         <p>As written above, each browser you use must now trust the newly created Privoxy CA certificate (<tt class=
 171         "FILENAME">privoxy.crt</tt>).</p>
 172         <p>In Firefox you can do this by opening the preferences "Edit" -&#62; "Settings" -&#62; "Privacy &#38;
 173         Security" or by typing <a href="about:preferences#privacy" target="_top">about:preferences#privacy</a> in the
 174         URL. Then go down to the "Certificates" section and click on "View Certificates". Click on the "Authorities"
 175         tab and "Import..." your <tt class="FILENAME">privoxy.crt</tt>. In the "CA certificate trust settings" select
 176         "This certificate can identify websites".</p>
 177         <p>In Chrome based browsers, go to the settings and select "Privacy and security" (<a href=
 178         "chrome://settings/privacy" target="_top">chrome://settings/privacy</a>). Click on "Security" and on the opened
 179         sub-page on "Manage certificates". Now go to the "Authorities" tab and import <tt class=
 180         "FILENAME">privoxy.crt</tt> and configure that you trust the certificate for website identification.</p>
 181       </div>
 182       <div class="SECT3">
 183         <h3 class="SECT3"><a name="H2-HI-ENABLE" id="H2-HI-ENABLE">11.1.7. Enabeling HTTPS inspection</a></h3>
 184         <p>Currently no pages use HTTPS inspection, you need to enable this for some (or all) domains first using
 185         <a href="actions-file.html#USER-ACTION">user.action</a> (either by editing the file by hand or via the CGI
 186         (this requires <a href="config.html#ENABLE-EDIT-ACTIONS">enable-edit-actions</a> to be enabled in config) at
 187         <a href="http://config.privoxy.org/show-status" target="_top">http://config.privoxy.org/show-status</a> (click
 188         on user.action Edit button).</p>
 189         <p>Here you can enable HTTPS inspection for individual sites:</p>
 190         <table border="0" bgcolor="#E0E0E0" width="100%">
 191           <tr>
 192             <td>
 193               <pre class="SCREEN">  {+<a href="actions-file.html#HTTPS-INSPECTION">https-inspection</a>}
 194   .badssl.com
 195   clienttest.ssllabs.com</pre>
 196             </td>
 197           </tr>
 198         </table>
 199         <p>You can add more individual sites or wildcards (one per line).</p>
 200         <p>Alternatively, you can use a client-tag to dynamically enable/disable this feature via the browser, as
 201         described in the next chapter.</p>
 202       </div>
 203     </div>
 204     <div class="SECT2">
 205       <h2 class="SECT2"><a name="H2-CLIENT-TAGS" id="H2-CLIENT-TAGS">11.2. Client Tags HOWTO</a></h2>
 206       <p>Client-Tags are a mechanism to dynamically/temporarily enable/disable features in Privoxy per browser.</p>
 207       <p>In our example, we use this for the following two use cases:</p>
 208       <ul>
 209         <li>
 210           <p>Enable TOR anonymous proxy</p>
 211         </li>
 212         <li>
 213           <p>Enable https-inspection</p>
 214         </li>
 215       </ul>
 216       <p>To use this feature, you must first define a tag name and a tag description for each client-tag in <a href=
 217       "config.html">config</a>, like this:</p>
 218       <table border="0" bgcolor="#E0E0E0" width="100%">
 219         <tr>
 220           <td>
 221             <pre class="SCREEN">  <a href=
 222             "config.html#CLIENT-SPECIFIC-TAG">client-specific-tag</a> tor Use Tor anonymous proxy
 223   <a href="config.html#CLIENT-SPECIFIC-TAG">client-specific-tag</a> https-inspection Enable https-inspection</pre>
 224           </td>
 225         </tr>
 226       </table>
 227       <p>Now you can open <a href="http://config.privoxy.org/client-tags" target=
 228       "_top">http://config.privoxy.org/client-tags</a> or <a href="http://p.p/client-tags" target=
 229       "_top">http://p.p/client-tags</a> and can enable/disable the tag there (you may want to add a bookmark for this
 230       in your browser for quick access, but it's also available as a link at <a href="http://p.p" target=
 231       "_top">http://p.p</a>).</p>
 232       <p>It's also possible to temporarily enable a tag, which by default means 3 minutes (=180 seconds) (and can be
 233       changed via the <a href="config.html#CLIENT-TAG-LIFETIME">client-tag-lifetime</a> option in <a href=
 234       "config.html">config</a>).</p>
 235       <p>But before this has any effect, you have to use the client tag in your <a href=
 236       "actions-file.html#USER-ACTION">user.action</a> like this:</p>
 237       <table border="0" bgcolor="#E0E0E0" width="100%">
 238         <tr>
 239           <td>
 240             <pre class="SCREEN">  {+<a href="actions-file.html#FORWARD-OVERRIDE">forward-override</a>{<a href=
 241             "config.html#SOCKS">forward-socks5t</a> 127.0.0.1:9050 .} }
 242   <a href="actions-file.html#CLIENT-TAG-PATTERN">CLIENT-TAG</a>:^tor$</pre>
 243           </td>
 244         </tr>
 245       </table>
 246       <p>This means, that if the "tor" client tag is enabled, all traffic is forwarded by Privoxy through socks5t to a
 247       locally installed tor proxy listening on port 9050.</p>
 248       <p>Similarly, you can specify to use the https-inspection client tag to enable https-inspection:</p>
 249       <table border="0" bgcolor="#E0E0E0" width="100%">
 250         <tr>
 251           <td>
 252             <pre class="SCREEN">  {+<a href="actions-file.html#HTTPS-INSPECTION">https-inspection</a>}
 253   <a href="actions-file.html#CLIENT-TAG-PATTERN">CLIENT-TAG</a>:^https-inspection$</pre>
 254           </td>
 255         </tr>
 256       </table>
 257       <p>The tag will be set for all requests coming from clients that have requested it to be set. Note that "clients"
 258       are distinguished by IP address, if the IP address changes, the tag must be requested again.</p>
 259     </div>
 260   </div>
 261   <div class="NAVFOOTER">
 262     <hr align="left" width="100%">
 263     <table summary="Footer navigation table" width="100%" border="0" cellpadding="0" cellspacing="0">
 264       <tr>
 265         <td width="33%" align="left" valign="top"><a href="templates.html" accesskey="P">Prev</a></td>
 266         <td width="34%" align="center" valign="top"><a href="index.html" accesskey="H">Home</a></td>
 267         <td width="33%" align="right" valign="top"><a href="contact.html" accesskey="N">Next</a></td>
 268       </tr>
 269       <tr>
 270         <td width="33%" align="left" valign="top">Privoxy's Template Files</td>
 271         <td width="34%" align="center" valign="top">&nbsp;</td>
 272         <td width="33%" align="right" valign="top">Contacting the Developers, Bug Reporting and Feature Requests</td>
 273       </tr>
 274     </table>
 275   </div>
 276 </body>
 277 </html>