From: Roland Rosenfeld <roland@debian.org>
Date: Fri, 11 Oct 2024 15:47:19 +0000 (+0200)
Subject: rebuild doc/webserver/user-manual
X-Git-Tag: v_4_0_0~60^2~3
X-Git-Url: http://www.privoxy.org/gitweb/%22https:/developer-manual/@default-cgi@send-stylesheet?a=commitdiff_plain;h=3698b35c27cb633afdbb3eb72115b5fcf9df0f8c;p=privoxy.git
rebuild doc/webserver/user-manual
---
diff --git a/doc/webserver/user-manual/appendix.html b/doc/webserver/user-manual/appendix.html
index 7efbff08..2e232098 100644
--- a/doc/webserver/user-manual/appendix.html
+++ b/doc/webserver/user-manual/appendix.html
@@ -202,7 +202,7 @@
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="AEN6566" id="AEN6566"></a>
+ <p>Privoxy main page:</p><a name="AEN6567" id="AEN6567"></a>
<blockquote class="BLOCKQUOTE">
<p><a href="http://config.privoxy.org/" target="_top">http://config.privoxy.org/</a></p>
</blockquote>
@@ -211,7 +211,7 @@
"APPLICATION">Privoxy</span>)</p>
</li>
<li>
- <p>View and toggle client tags:</p><a name="AEN6574" id="AEN6574"></a>
+ <p>View and toggle client tags:</p><a name="AEN6575" id="AEN6575"></a>
<blockquote class="BLOCKQUOTE">
<p><a href="http://config.privoxy.org/client-tags" target=
"_top">http://config.privoxy.org/client-tags</a></p>
@@ -219,21 +219,21 @@
</li>
<li>
<p>Show information about the current configuration, including viewing and editing of actions
- files:</p><a name="AEN6579" id="AEN6579"></a>
+ files:</p><a name="AEN6580" id="AEN6580"></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="AEN6584" id="AEN6584"></a>
+ <p>Show the browser's request headers:</p><a name="AEN6585" id="AEN6585"></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="AEN6589" id="AEN6589"></a>
+ <p>Show which actions apply to a URL and why:</p><a name="AEN6590" id="AEN6590"></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>
@@ -242,15 +242,15 @@
<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="AEN6597" id="AEN6597"></a>
+ but only as a pass-through proxy, with no actions taking place:</p><a name="AEN6598" id="AEN6598"></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="AEN6601" id="AEN6601"></a>
+ <p>Short cuts. Turn off, then on:</p><a name="AEN6602" id="AEN6602"></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="AEN6604" id="AEN6604"></a>
+ </blockquote><a name="AEN6605" id="AEN6605"></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>
diff --git a/doc/webserver/user-manual/copyright.html b/doc/webserver/user-manual/copyright.html
index d40237c4..b65d793f 100644
--- a/doc/webserver/user-manual/copyright.html
+++ b/doc/webserver/user-manual/copyright.html
@@ -1084,7 +1084,8 @@ Public License instead of this License. But first, please read
<p>When compiled with FEATURE_HTTPS_INSPECTION (optional), Privoxy depends on a TLS library. The supported
libraries are <a href="https://www.openssl.org/" target="_top">LibreSSL</a>, <a href=
"https://github.com/Mbed-TLS/mbedtls/tags" target="_top">mbed TLS 2.28.x</a> and <a href=
- "https://www.openssl.org/" target="_top">OpenSSL</a>.</p>
+ "https://www.openssl.org/" target="_top">OpenSSL</a> and <a href="https://www.wolfssl.com/" target=
+ "_top">wolfSSL</a>.</p>
<p>When compiled with FEATURE_ZLIB (optional), Privoxy depends on <a href="https://zlib.net/" target=
"_top">zlib</a>.</p>
</div>
@@ -1163,6 +1164,7 @@ Public License instead of this License. But first, please read
Devin Bayer<br>
Havard Berland<br>
David Binderman<br>
+ Ingo Blechschmidt<br>
David Bo<br>
Gergely Bor<br>
Francois Botha<br>
@@ -1172,6 +1174,7 @@ Public License instead of this License. But first, please read
Andrew J. Caines<br>
Clifford Caoile<br>
Edward Carrel<br>
+ Laurent Caumont<br>
Celejar<br>
Chakib Benziane<br>
Pak Chan<br>
@@ -1194,6 +1197,7 @@ Public License instead of this License. But first, please read
Markus Elfring<br>
Ryan Farmer<br>
Matthew Fischer<br>
+ Fabrice Fontaine<br>
T Ford<br>
Dean Gaudet<br>
Stephen Gildea<br>
@@ -1234,6 +1238,7 @@ Public License instead of this License. But first, please read
Zeno Kugy<br>
David Laight<br>
Bert van Leeuwen<br>
+ Aaron Li<br>
Don Libes<br>
Paul Lieverse<br>
Adele Lime<br>
@@ -1286,8 +1291,10 @@ Public License instead of this License. But first, please read
Mark Seward<br>
Franz Schwartau<br>
Chung-chieh Shan<br>
+ Gagan Sidhu<br>
Johan Sintorn<br>
Benjamin C. Wiley Sittler<br>
+ Juliusz Sosinowicz<br>
DRS David Soft<br>
Simon South<br>
Dan Stahlke<br>
@@ -1314,6 +1321,7 @@ Public License instead of this License. But first, please read
David Wagner<br>
Glenn Washburn<br>
Song Weijia<br>
+ Florian Weimer<br>
Jörg Weinmann<br>
Darren Wiebe<br>
Anduin Withers<br>
diff --git a/doc/webserver/user-manual/howto.html b/doc/webserver/user-manual/howto.html
index f33daeee..2c7e75d3 100644
--- a/doc/webserver/user-manual/howto.html
+++ b/doc/webserver/user-manual/howto.html
@@ -40,9 +40,9 @@
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>To do this, each browser has the certificates of multiple CAs in its trust store. The browser will only
+ accept the certificate if the CA that signed it is in its trust store, otherwise it will warn that the
+ certificate is not valid.</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>
@@ -50,11 +50,11 @@
<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
+ without being the browser or the web server. This is exactly what TLS is designed to prevent, because it's a
+ man-in-the-middle attack.</p>
+ <p>To do this, Privoxy uses its own (private) CA (let's call it "Privoxy CA"), which needs to be added to the
+ trust store of every single browser that you want to use with Privoxy and HTTPS inspection.</p>
+ <p>Privoxy then 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
@@ -63,10 +63,10 @@
<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>
+ <p>If Privoxy detects that a TLS certificate is invalid, because it's expired, doesn't match the hostname, is
+ self-signed, or similar, Privoxy will block the requests and return an error message explaining the problem to
+ prevent the user/browser from communicating over an insecure channel.</p>
+ <p>To test this behavior, just 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
@@ -75,9 +75,10 @@
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>
+ from source</a> to enable it. You can choose to 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>. You can choose either one, as 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>
@@ -110,21 +111,21 @@
</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>In this example, a CA validity of 10 years (3650 days) is defined. You should set the appropriate validity
+ period based on your needs. 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 key generation you will be asked to provide a "PEM pass phrase". This passphrase 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>
+ Address. You should fill in some useful data here, because these entries will be 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
+ <p>Make sure that the private key (<tt class="FILENAME">privoxy.pem</tt> in the example above) is only
accessible to the user running Privoxy (usually named "privoxy"):</p>
<table border="0" bgcolor="#E0E0E0" width="100%">
<tr>
@@ -134,7 +135,7 @@
</td>
</tr>
</table>
- <p>Now adjust your Privoxy <a href="config.html">configuration</a>:</p>
+ <p>Now customize your Privoxy <a href="config.html">configuration</a>:</p>
<table border="0" bgcolor="#E0E0E0" width="100%">
<tr>
<td>
@@ -153,7 +154,7 @@
<tr>
<td>
<pre class="SCREEN"> chown privoxy /var/lib/privoxy/certs
- chmod 700 /var/lib/privoxy/certs.</pre>
+ chmod 700 /var/lib/privoxy/certs</pre>
</td>
</tr>
</table>
@@ -167,8 +168,8 @@
</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>As mentioned earlier, 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" -> "Settings" -> "Privacy &
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"
@@ -177,7 +178,7 @@
<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>
+ "FILENAME">privoxy.crt</tt> and configure it to 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>
@@ -203,7 +204,8 @@
</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>Client Tags are a mechanism to dynamically or temporarily enable and disable features in Privoxy for each
+ browser instance.</p>
<p>In our example, we use this for the following two use cases:</p>
<ul>
<li>
@@ -226,13 +228,12 @@
</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=
+ "_top">http://p.p/client-tags</a> and enable or disable the tag there (you may want to bookmark this page for
+ quick access, though it is also available via a link at <a href="http://p.p" target="_top">http://p.p</a>).</p>
+ <p>You can also temporarily enable a tag, which by default means 3 minutes (180 seconds) (and can be changed
+ using 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=
+ <p>Before this takes effect, you must reference 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>
@@ -243,8 +244,8 @@
</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>This means that if the "tor" client tag is enabled, all traffic will be 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>
@@ -255,7 +256,7 @@
</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>
+ are distinguished by their IP address. If the IP address changes, the tag must be requested again.</p>
</div>
</div>
<div class="NAVFOOTER">