www/nginx: add TLS fingerprint detection (#98)

source/manual/how-tos/nginx_tls_fingerprints.rst

@@ -0,0 +1,103 @@
+=======================
+nginx: TLS Fingerprints
+=======================
+
+.. Warning::
+
+    This manual page is for advanced users only as the feature is not designed to be used by beginners.
+    Maybe the curves are not provided by the TLS implementation and you get an empty string.
+    If this is the case, it is normal but you should expect trouble if you use them as a later
+    version of the software may implement them and then all your connections will be flagged
+    as intercepted.
+    
+Requirements
+============
+
+* To use this feature, you must have an HTTPS server running which writes some logs.
+* Different browsers from different operating systems as clients
+
+
+Analysis Page
+=============
+
+
+The analysis page is grouped into some sections:
+
+.. image:: images/nginx_fingerprint_list_colors.png
+
+======= ================================================================================
+Color   Description
+======= ================================================================================
+Orange  User-Agent string (HTTP-Header) - technical description of the client
+Red     Total count of hits in the log of the UA with this ciphers and curves
+Blue    Supported Ciphers and Curves in order of the Client hello - our fingerprint
+Green   If you click this button, you can take the fingerprint over to the configuration
+Gray    Pie chart of the fingerprints count and the User-Agent (visualized)
+======= ================================================================================
+
+
+The pie chart is important to know if a fingerprint is
+intercepted because many intercepting software changes the client hello.
+Let's take a look at this one:
+
+.. image:: images/nginx_fingerprint_list.png
+
+There is one small one, which we probably can ignore,
+so lets look at the other two fingerprints:
+One contains ciphers, hashes etc., browsers should not support anymore (for
+example NULL, MD5, ...) so this is probably intercepted (it actually is OWASP 
+ZAP_ 2.7.0) in this screenshot, which is intercepting a connection from
+Firefox 63.
+In this case there is onle one big segment left, which is very likely the real
+browser fingerprint (or another proxy).
+
+In the following example, take a look at the pie chart
+(especially the segment with the cursor on it):
+
+.. image:: images/nginx_fingerprint_good_sample.png
+
+The segment has a huge share of the requests with this User-Agent.
+In such a case it can be either always the same client requesting a resource
+and probably only few users are using it or, which is more likely if it is a
+browser, it that it is probably the right fingerprint.
+
+
+.. Warning::
+   Some proxies are mirroring the client hello, so they won't be detected.
+   Also be careful because for example if you have a big customer generating
+   a lot of traffic, a big segment of the pie chart (even the biggest one),
+   may be intercepted.
+   
+   For security reasons you should also take the absolute count into account
+   when you are working on a real world sample and that software may be compiled
+   width different which may also replace the crypto library which also means
+   that it will have a different fingerprint.
+
+.. _ZAP: https://github.com/zaproxy/zaproxy
+
+
+If you click on the store button, a dialog will open and you can create a new
+entry in your configuration, which will be visible on the configuration page.
+
+For example, our fingerprint could be imported into the configuration like
+shown in the following screenshot:
+
+.. image:: images/nginx_fingerprint_export.png
+
+
+Configuration Page
+==================
+
+Now in the configuration page under HTTP -> TLS Fingerprints there will be an
+entry for the created fingerprint, so it can be edited:
+
+.. image:: images/nginx_fingerprint_settings.png
+
+Trusted Fingerprints
+====================
+
+A trusted fingerprint is a fingerprint, which will be used to detect man in the
+middle attacks by comparing the client hello of the fingerprint with the data
+sent by the client. If there are additional ciphers or curves, you will get
+this information via an HTTP header into your application.
+Please note that you can have only one fingerprint per User-Agent.

source/manual/howtos.rst

@@ -46,6 +46,7 @@ How-tos
    how-tos/nginx_hosting
    how-tos/nginx_basic_auth
    how-tos/nginx_ip_acl
+   how-tos/nginx_tls_fingerprints
    how-tos/nginx_tls_auth
    how-tos/nginx_waf
    how-tos/nginx_streams