diff --git a/source/manual/how-tos/images/nginx_fingerprint_export.png b/source/manual/how-tos/images/nginx_fingerprint_export.png new file mode 100644 index 00000000..dcd517ce Binary files /dev/null and b/source/manual/how-tos/images/nginx_fingerprint_export.png differ diff --git a/source/manual/how-tos/images/nginx_fingerprint_good_sample.png b/source/manual/how-tos/images/nginx_fingerprint_good_sample.png new file mode 100644 index 00000000..5ef0af66 Binary files /dev/null and b/source/manual/how-tos/images/nginx_fingerprint_good_sample.png differ diff --git a/source/manual/how-tos/images/nginx_fingerprint_list.png b/source/manual/how-tos/images/nginx_fingerprint_list.png new file mode 100644 index 00000000..758ddb21 Binary files /dev/null and b/source/manual/how-tos/images/nginx_fingerprint_list.png differ diff --git a/source/manual/how-tos/images/nginx_fingerprint_list_colors.png b/source/manual/how-tos/images/nginx_fingerprint_list_colors.png new file mode 100644 index 00000000..db4520db Binary files /dev/null and b/source/manual/how-tos/images/nginx_fingerprint_list_colors.png differ diff --git a/source/manual/how-tos/images/nginx_fingerprint_settings.png b/source/manual/how-tos/images/nginx_fingerprint_settings.png new file mode 100644 index 00000000..027485b6 Binary files /dev/null and b/source/manual/how-tos/images/nginx_fingerprint_settings.png differ diff --git a/source/manual/how-tos/nginx_tls_fingerprints.rst b/source/manual/how-tos/nginx_tls_fingerprints.rst new file mode 100644 index 00000000..30a223d7 --- /dev/null +++ b/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. diff --git a/source/manual/howtos.rst b/source/manual/howtos.rst index ecba6aea..526dda54 100644 --- a/source/manual/howtos.rst +++ b/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