From f7d918acfdaf09adba5fe00dc108effff2432bbf Mon Sep 17 00:00:00 2001 From: Roland Rosenfeld Date: Mon, 20 Feb 2023 11:31:09 +0100 Subject: [PATCH] Regenerate user-manual with HOWTOs. --- doc/webserver/user-manual/appendix.html | 26 +-- doc/webserver/user-manual/contact.html | 26 +-- doc/webserver/user-manual/copyright.html | 14 +- doc/webserver/user-manual/howto.html | 277 +++++++++++++++++++++++ doc/webserver/user-manual/index.html | 63 ++++-- doc/webserver/user-manual/seealso.html | 2 +- doc/webserver/user-manual/templates.html | 8 +- 7 files changed, 356 insertions(+), 60 deletions(-) create mode 100644 doc/webserver/user-manual/howto.html diff --git a/doc/webserver/user-manual/appendix.html b/doc/webserver/user-manual/appendix.html index e78842a8..7efbff08 100644 --- a/doc/webserver/user-manual/appendix.html +++ b/doc/webserver/user-manual/appendix.html @@ -25,9 +25,9 @@
-

14. Appendix

+

15. Appendix

-

14.1. Regular Expressions

+

15.1. Regular Expressions

Privoxy uses Perl-style "regular expressions" in its actions files and filter file, through the PCRE and PCRS libraries.

@@ -191,7 +191,7 @@ filter file tutorial in this manual.

-

14.2. Privoxy's Internal Pages

+

15.2. Privoxy's Internal Pages

Since Privoxy proxies each requested web page, it is easy for Privoxy to trap certain special URLs. In this way, we can talk directly to Privoxy, and see how it is configured, see how our rules are being applied, change these @@ -202,7 +202,7 @@ these. If not, you will get a friendly error message. Internet access is not necessary either.

-

14.3. Chain of Events

+

15.3. Chain of Events

Let's take a quick look at how some of Privoxy's core features are triggered, and the ensuing sequence of events when a web page is requested by your browser:

    @@ -336,7 +336,7 @@ and simplicity, we have focused on Privoxy's core features only.

-

14.4. Troubleshooting: Anatomy of an Action

+

15.4. Troubleshooting: Anatomy of an Action

The way Privoxy applies actions and filters 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 Contacting the Developers, Bug Reporting and Feature Requests - + @@ -18,7 +18,7 @@ Privoxy 3.0.35 User Manual - Prev + Prev Next @@ -26,12 +26,12 @@

-

11. Contacting the Developers, Bug Reporting and Feature +

12. Contacting the Developers, Bug Reporting and Feature Requests

We value your feedback. In fact, we rely on it to improve Privoxy and its configuration. However, please note the following hints, so we can provide you with the best support.

-

11.1. Please provide sufficient +

12.1. Please provide sufficient information

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.

@@ -128,7 +128,7 @@ action debugging.

-

11.2. Get Support

+

12.2. Get Support

All users are welcome to discuss their issues on the users mailing list, where the developers also hang around.

@@ -146,7 +146,7 @@ mailing list only, and you won't see them.

-

11.3. Reporting Problems

+

12.3. Reporting Problems

"Problems" for our purposes, come in two forms:

  • @@ -161,7 +161,7 @@
-

11.3.1. Reporting Ads or Other Configuration +

12.3.1. Reporting Ads or Other Configuration Problems

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 default.action file, to https://sourceforge.net/p/ijbswa/actionsfile-feedback/, the Actions File Tracker.

-

11.3.2. Reporting Bugs

+

12.3.2. Reporting Bugs

Before reporting bugs, please make sure that the bug has not already been submitted and observe the additional hints at the top of the submit form. If already submitted, please feel free @@ -177,7 +177,7 @@

-

11.4. Reporting security problems

+

12.4. Reporting security problems

If you discovered a security problem or merely suspect that a bug might be a security issue, please mail Fabian Keil <fk@fabiankeil.de> (OpenPGP fingerprint: 4F36 C17F 3816 9136 54A1 E850 6918 2291 8BA2 371C).

@@ -185,7 +185,7 @@ didn't make it. If that happens, please mail to the developer list to request a status update.

-

11.5. Mailing Lists

+

12.5. Mailing Lists

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 @@ -196,7 +196,7 @@ "https://sourceforge.net/p/ijbswa/mailman/" target="_top">https://sourceforge.net/p/ijbswa/mailman/.

-

11.6. SourceForge support trackers

+

12.6. SourceForge support trackers

The SourceForge support trackers 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.

@@ -206,12 +206,12 @@
- + - + diff --git a/doc/webserver/user-manual/copyright.html b/doc/webserver/user-manual/copyright.html index 74ec3f12..d40237c4 100644 --- a/doc/webserver/user-manual/copyright.html +++ b/doc/webserver/user-manual/copyright.html @@ -26,7 +26,7 @@
-

12. Privoxy Copyright, License and History

+

13. Privoxy Copyright, License and History

Copyright © 2001-2023 by Privoxy Developers

Some source code is based on code Copyright © 1997 by Anonymous Coders and Junkbusters, Inc.

@@ -40,9 +40,9 @@ Software Foundation, either version 3 of the license, or (at your option) any later version.

Both licenses are included in the next section.

-

12.1. License

+

13.1. License

-

12.1.1. GNU General Public License version 2

+

13.1.1. GNU General Public License version 2

PrevPrev Home Next
Privoxy's Template FilesHOWTOs   Privoxy Copyright, License and History
@@ -391,7 +391,7 @@ Public License instead of this License.
-

12.1.2. GNU General Public License version 3

+

13.1.2. GNU General Public License version 3

@@ -1075,7 +1075,7 @@ Public License instead of this License. But first, please read
-

12.1.3. Third-party licenses and copyrights

+

13.1.3. Third-party licenses and copyrights

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.

Privoxy depends on pcre.

@@ -1090,7 +1090,7 @@ Public License instead of this License. But first, please read

-

12.2. History

+

13.2. History

A long time ago, there was the Internet Junkbuster, by Anonymous Coders and Junkbusters Corporation. This saved many users a lot of pain in the early days of web advertising and user tracking.

@@ -1115,7 +1115,7 @@ Public License instead of this License. But first, please read is still actively maintained.

-

12.3. Authors

+

13.3. Authors

Current Privoxy Team:

 Fabian Keil, lead developer
 David Schmidt
diff --git a/doc/webserver/user-manual/howto.html b/doc/webserver/user-manual/howto.html new file mode 100644 index 00000000..f33daeee --- /dev/null +++ b/doc/webserver/user-manual/howto.html @@ -0,0 +1,277 @@ + + + + HOWTOs + + + + + + + + + +

+ + + + + + + + + +
Privoxy 3.0.35 User Manual
PrevNext
+
+
+
+

11. HOWTOs

+
+

11.1. HTTPS-Inspection HOWTO

+
+

11.1.1. How TLS Certificates for websites work

+

The website owner generates a (private) TLS key and a Certificate Signing Request (CSR).

+

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.

+

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.

+

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.

+

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.

+

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.

+
+
+

11.1.2. How HTTPS inspection works

+

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.

+

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.

+

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.

+

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.

+
+
+

11.1.3. 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.

+

To check this behavior, simply go to https://badssl.com/

+
+
+

11.1.4. HTTPS inspection + prerequisites

+

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 http://config.privoxy.org/show-status in the "Conditional #defines" section.

+

If the feature is not enabled, you may need to build Privoxy + from source to enable it. You can use either MbedTLS or OpenSSL. It's up to you, + which one to use, they both behave the same for HTTPS inspection.

+

After installing the development libraries for either OpenSSL or MbedTLS, you can run ./configure with either the --with-openssl or --with-mbedtls option.

+

Check the output of ./configure, it must contain one of these the following two + lines, otherwise HTTPS inspection will not work:

+ + + + +
+ 
  configure: Detected OpenSSL. Enabling https inspection.
+  configure: Detected mbedTLS. Enabling https inspection.
+
+

If you do not find any of these lines, the output of ./configure will tell you what + went wrong.

+

You should then proceed with the source install. + Finally, check the FEATURE_HTTPS_INSPECTION status in http://config.privoxy.org/show-status again.

+
+
+

11.1.5. Configuring HTTPS inspection in + Privoxy

+

First, you need to create the private key and certificate for the "Privoxy CA". This can be done using + openssl with the following command:

+ + + + +
+ 
  openssl req -new -x509 -extensions v3_ca -keyout privoxy.pem -out privoxy.crt -days 3650
+
+

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.

+

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!

+

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.

+

Copy the private key (privoxy.pem) and the CA certificate (privoxy.crt) into the ca-directory (defined in config).

+

Make sure that the private key (privoxy.pem in the above example) is only + accessible to the user running Privoxy (usually named "privoxy"):

+ + + + +
+ 
  chmod 600 privoxy.pem
+  chown privoxy privoxy.pem
+
+

Now adjust your Privoxy configuration:

+ + + + +
+ 
  ca-directory /etc/privoxy/CA # read-only
+  ca-cert-file privoxy.crt     # in ca-directory
+  ca-key-file privoxy.pem      # in ca-directory
+  ca-password passphrasefromabove
+  certificate-directory /var/lib/privoxy/certs
+  trusted-cas-file /etc/ssl/certs/ca-certificates.crt
+
+

certificate-directory contains the (on the fly) created + webserver keys and certificates. It should only be readable by the privoxy user only:

+ + + + +
+ 
  chown privoxy /var/lib/privoxy/certs
+  chmod 700 /var/lib/privoxy/certs.
+
+

trusted-cas-file 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 /etc/ssl/certs/ca-certificates.crt, 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 https://curl.se/docs/caextract.html.

+
+
+

11.1.6. Browser configuration

+

As written above, each browser you use must now trust the newly created Privoxy CA certificate (privoxy.crt).

+

In Firefox you can do this by opening the preferences "Edit" -> "Settings" -> "Privacy & + Security" or by typing about:preferences#privacy in the + URL. Then go down to the "Certificates" section and click on "View Certificates". Click on the "Authorities" + tab and "Import..." your privoxy.crt. In the "CA certificate trust settings" select + "This certificate can identify websites".

+

In Chrome based browsers, go to the settings and select "Privacy and security" (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 the certificate for website identification.

+
+
+

11.1.7. Enabeling HTTPS inspection

+

Currently no pages use HTTPS inspection, you need to enable this for some (or all) domains first using + user.action (either by editing the file by hand or via the CGI + (this requires enable-edit-actions to be enabled in config) at + http://config.privoxy.org/show-status (click + on user.action Edit button).

+

Here you can enable HTTPS inspection for individual sites:

+ + + + +
+ 
  {+https-inspection}
+  .badssl.com
+  clienttest.ssllabs.com
+
+

You can add more individual sites or wildcards (one per line).

+

Alternatively, you can use a client-tag to dynamically enable/disable this feature via the browser, as + described in the next chapter.

+
+
+
+

11.2. Client Tags HOWTO

+

Client-Tags are a mechanism to dynamically/temporarily enable/disable features in Privoxy per browser.

+

In our example, we use this for the following two use cases:

+
    +
  • +

    Enable TOR anonymous proxy

    +
    • +
  • +

    Enable https-inspection

    +
    • +
+

To use this feature, you must first define a tag name and a tag description for each client-tag in config, like this:

+ + + + +
+ 
  client-specific-tag tor Use Tor anonymous proxy
+  client-specific-tag https-inspection Enable https-inspection
+
+

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).

+

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).

+

But before this has any effect, you have to use the client tag in your user.action like this:

+ + + + +
+ 
  {+forward-override{forward-socks5t 127.0.0.1:9050 .} }
+  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.

+

Similarly, you can specify to use the https-inspection client tag to enable https-inspection:

+ + + + +
+ 
  {+https-inspection}
+  CLIENT-TAG:^https-inspection$
+
+

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.

+
+
+
+
+ + + + + + + + + + + +
PrevHomeNext
Privoxy's Template Files Contacting the Developers, Bug Reporting and Feature Requests
+
+ + diff --git a/doc/webserver/user-manual/index.html b/doc/webserver/user-manual/index.html index 58edcc90..6bf8acc9 100644 --- a/doc/webserver/user-manual/index.html +++ b/doc/webserver/user-manual/index.html @@ -291,46 +291,65 @@
10. Privoxy's Template Files
-
11. Contacting the Developers, Bug Reporting and Feature Requests
+
11. HOWTOs
-
11.1. Please provide sufficient information
-
11.2. Get Support
-
11.3. Reporting Problems
+
11.1. HTTPS-Inspection HOWTO
-
11.3.1. Reporting Ads or Other Configuration Problems
-
11.3.2. Reporting Bugs
+
11.1.1. How TLS Certificates for websites work
+
11.1.2. How HTTPS inspection works
+
11.1.3. What happens, if the original certificate is + invalid?
+
11.1.4. HTTPS inspection prerequisites
+
11.1.5. Configuring HTTPS inspection in Privoxy
+
11.1.6. Browser configuration
+
11.1.7. Enabeling HTTPS inspection
-
11.4. Reporting security problems
-
11.5. Mailing Lists
-
11.6. SourceForge support trackers
+
11.2. Client Tags HOWTO
-
12. Privoxy Copyright, License and History
+
12. Contacting the Developers, Bug Reporting and Feature Requests
-
12.1. License
+
12.1. Please provide sufficient information
+
12.2. Get Support
+
12.3. Reporting Problems
-
12.1.1. GNU General Public License version 2
-
12.1.2. GNU General Public License version 3
-
12.1.3. Third-party licenses and copyrights
+
12.3.1. Reporting Ads or Other Configuration Problems
+
12.3.2. Reporting Bugs
-
12.2. History
-
12.3. Authors
+
12.4. Reporting security problems
+
12.5. Mailing Lists
+
12.6. SourceForge support trackers
-
13. See Also
-
14. Appendix
+
13. Privoxy Copyright, License and History
-
14.1. Regular Expressions
-
14.2. Privoxy's Internal Pages
-
14.3. Chain of Events
-
14.4. Troubleshooting: Anatomy of an Action
+
13.1. License
+
+
+
13.1.1. GNU General Public License version 2
+
13.1.2. GNU General Public License version 3
+
13.1.3. Third-party licenses and copyrights
+
+
+
13.2. History
+
13.3. Authors
+
+
+
14. See Also
+
15. Appendix
+
+
+
15.1. Regular Expressions
+
15.2. Privoxy's Internal Pages
+
15.3. Chain of Events
+
15.4. Troubleshooting: Anatomy of an Action
diff --git a/doc/webserver/user-manual/seealso.html b/doc/webserver/user-manual/seealso.html index 65ea6df3..57e74a20 100644 --- a/doc/webserver/user-manual/seealso.html +++ b/doc/webserver/user-manual/seealso.html @@ -26,7 +26,7 @@
-

13. See Also

+

14. See Also

Other references and sites of interest to Privoxy users:

diff --git a/doc/webserver/user-manual/templates.html b/doc/webserver/user-manual/templates.html index 74bdf594..c7d5eaa5 100644 --- a/doc/webserver/user-manual/templates.html +++ b/doc/webserver/user-manual/templates.html @@ -6,7 +6,7 @@ - + @@ -20,7 +20,7 @@ - +
Prev NextNext
@@ -85,12 +85,12 @@ Prev Home - Next + Next Filter Files   - Contacting the Developers, Bug Reporting and Feature Requests + HOWTOs
-- 2.39.2