From: Roland Rosenfeld Date: Fri, 11 Oct 2024 14:01:05 +0000 (+0200) Subject: Improve wording of the HOWTOs. X-Git-Tag: v_4_0_0~60^2~5 X-Git-Url: http://www.privoxy.org/gitweb/?a=commitdiff_plain;h=a7a1342ccad1ac931967e70bf55a277f51e53d76;p=privoxy.git Improve wording of the HOWTOs. --- diff --git a/doc/source/user-manual.sgml b/doc/source/user-manual.sgml index a1b86b18..10a61ae9 100644 --- a/doc/source/user-manual.sgml +++ b/doc/source/user-manual.sgml @@ -35,7 +35,7 @@ Purpose : user manual - Copyright (C) 2001-2023 Privoxy Developers https://www.privoxy.org/ + Copyright (C) 2001-2024 Privoxy Developers https://www.privoxy.org/ See LICENSE. ======================================================================== @@ -8209,10 +8209,9 @@ EXTERNAL-FILTER: citation-needed Adds a "[citation needed]" tag to an image. The 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. + 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. If this check passes, the browser sends a random number encrypted @@ -8227,16 +8226,16 @@ EXTERNAL-FILTER: citation-needed Adds a "[citation needed]" tag to an image. The 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. + or the web server. This is exactly what TLS is designed to prevent, + because it's a man-in-the-middle attack. - 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. + 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. - Now Privoxy breaks the connection between browser and webserver by + 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 @@ -8252,14 +8251,14 @@ EXTERNAL-FILTER: citation-needed Adds a "[citation needed]" tag to an image. The What happens, if the original certificate is invalid? - 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. + 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. - To check this behavior, simply go to + To test this behavior, just go to https://badssl.com/ @@ -8276,10 +8275,10 @@ EXTERNAL-FILTER: citation-needed Adds a "[citation needed]" tag to an image. The If the feature is not enabled, you may need to build Privoxy from source - to enable it. You can use either + to enable it. You can choose to use either MbedTLS - or OpenSSL. It's up to - you, which one to use, they both behave the same for HTTPS inspection. + or OpenSSL. You can + choose either one, as they both behave the same for HTTPS inspection. After installing the development libraries for either OpenSSL or @@ -8320,23 +8319,23 @@ openssl req -new -x509 -extensions v3_ca -keyout privoxy.pem -out privoxy.crt -d - 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. + 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. - 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! + 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! 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 + Orginzation Name, Common Name, and Email 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. @@ -8349,7 +8348,7 @@ openssl req -new -x509 -extensions v3_ca -keyout privoxy.pem -out privoxy.crt -d Make sure that the private key (privoxy.pem in - the above example) is only accessible to the user running Privoxy + the example above) is only accessible to the user running Privoxy (usually named "privoxy"): @@ -8357,7 +8356,7 @@ chmod 600 privoxy.pem chown privoxy privoxy.pem - Now adjust your Privoxy configuration: + Now customize your Privoxy configuration: ca-directory /etc/privoxy/CA # read-only @@ -8374,7 +8373,7 @@ chown privoxy privoxy.pem chown privoxy /var/lib/privoxy/certs -chmod 700 /var/lib/privoxy/certs. +chmod 700 /var/lib/privoxy/certs trusted-cas-file is the trust @@ -8391,7 +8390,7 @@ chmod 700 /var/lib/privoxy/certs. Browser configuration - As written above, each browser you use must now trust the newly + As mentioned earlier, each browser you use must now trust the newly created Privoxy CA certificate (privoxy.crt). @@ -8409,7 +8408,7 @@ chmod 700 /var/lib/privoxy/certs. (chrome://settings/privacy). Click on "Security" and on the opened sub-page on "Manage certificates". Now go to the "Authorities" tab and - import privoxy.crt and configure that you trust + import privoxy.crt and configure it to trust the certificate for website identification. @@ -8447,8 +8446,8 @@ clienttest.ssllabs.com Client Tags HOWTO - Client-Tags are a mechanism to dynamically/temporarily enable/disable - features in Privoxy per browser. + Client Tags are a mechanism to dynamically or temporarily enable and + disable features in Privoxy for each browser instance. In our example, we use this for the following two use cases: @@ -8470,18 +8469,18 @@ clienttest.ssllabs.com Now you can open http://config.privoxy.org/client-tags or http://p.p/client-tags - 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 http://p.p). + 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 http://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 - client-tag-lifetime option - in config). + You can also temporarily enable a tag, which by default means 3 + minutes (180 seconds) (and can be changed using the + client-tag-lifetime + option in config). - But before this has any effect, you have to use the client tag in + Before this takes effect, you must reference the client tag in your user.action like this: @@ -8489,9 +8488,9 @@ clienttest.ssllabs.com CLIENT-TAG:^tor$ - 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. + 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. Similarly, you can specify to use the https-inspection client tag to @@ -8503,8 +8502,9 @@ clienttest.ssllabs.com 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. + requested it to be set. Note that "clients" are distinguished by + their IP address. If the IP address changes, the tag must be + requested again.