Add a dump of received FP and CERT when in debug mode (#6300)

* Add a dump of received FP and CERT when in debug mode

To simplify BearSSL debugging, print the received FP (when it doesn't
match the expected) and the binary certificate (always), when in debug
mode.

* Add documentation section on FP mismatch in rare instances.

doc/esp8266wifi/bearssl-client-secure-class.rst

@@ -109,7 +109,7 @@ See the `BearSSL_CertStore` example for full details as the `BearSSL::CertStore`
 Supported Crypto
 ~~~~~~~~~~~~~~~~
 
-Please see the `BearSSL website <htps://bearssl.org>`__ for detailed cryptographic information.  In general, TLS 1.2, TLS 1.1, and TLS 1.0 are supported with RSA and Elliptic Curve keys and a very rich set of hashing and symmetric encryption codes.  Please note that Elliptic Curve (EC) key operations take a significant amount of time.
+Please see the `BearSSL website <https://bearssl.org>`__ for detailed cryptographic information.  In general, TLS 1.2, TLS 1.1, and TLS 1.0 are supported with RSA and Elliptic Curve keys and a very rich set of hashing and symmetric encryption codes.  Please note that Elliptic Curve (EC) key operations take a significant amount of time.
 
 
 BearSSL::WiFiClientSecure Class
@@ -139,6 +139,8 @@ setFingerprint(const uint8_t fp[20]) / setFingerprint(const char \*fpStr)
 
 Verify the SHA1 fingerprint of the certificate returned matches this one.  If the server certificate changes, it will fail.  If an array of 20 bytes are sent in, it is assumed they are the binary SHA1 values.  If a `char*` string is passed in, it is parsed as a series of human-readable hex values separated by spaces or colons (e.g. `setFingerprint("00:01:02:03:...:1f");`)
 
+This fingerprint is calcuated on the raw X509 certificate served by the server.  In very rare cases, these certificates have certain encodings which should be normalized before taking a fingerprint (but in order to preserve memory BearSSL does not do this normalization since it would need RAM for an entire copy of the cert), and the fingerprint BearSSL calculates will not match the fingerprint OpenSSL calculates.  In this case, you can enable SSL debugging and get a dump of BearSSL's calculated fingerprint and use that one in your code, or use full certificate validation.  See the `original issue and debug here <https://github.com/esp8266/Arduino/issues/6209>`__.
+
 setTrustAnchors(BearSSL::X509List \*ta)
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 

libraries/ESP8266WiFi/src/WiFiClientSecureBearSSL.cpp

@@ -654,6 +654,13 @@ extern "C" {
     if (!xc->done_cert) {
       br_sha1_update(&xc->sha1_cert, buf, len);
       br_x509_decoder_push(&xc->ctx, (const void*)buf, len);
+#ifdef DEBUG_ESP_SSL
+      DEBUG_BSSL("CERT: ");
+      for (size_t i=0; i<len; i++) {
+        DEBUG_ESP_PORT.printf_P(PSTR("%02x "), buf[i] & 0xff);
+      }
+      DEBUG_ESP_PORT.printf_P(PSTR("\n"));
+#endif
     }
   }
 
@@ -676,7 +683,24 @@ extern "C" {
     char res[20];
     br_sha1_out(&xc->sha1_cert, res);
     if (xc->match_fingerprint && memcmp(res, xc->match_fingerprint, sizeof(res))) {
+#ifdef DEBUG_ESP_SSL
       DEBUG_BSSL("insecure_end_chain: Received cert FP doesn't match\n");
+      char buff[3 * sizeof(res) + 1]; // 3 chars per byte XX_, and null
+      buff[0] = 0;
+      for (size_t i=0; i<sizeof(res); i++) {
+        char hex[4]; // XX_\0
+        snprintf(hex, sizeof(hex), "%02x ", xc->match_fingerprint[i] & 0xff);
+        strlcat(buff, hex, sizeof(buff));
+      }
+      DEBUG_BSSL("insecure_end_chain: expected %s\n", buff);
+      buff[0] =0;
+      for (size_t i=0; i<sizeof(res); i++) {
+        char hex[4]; // XX_\0
+        snprintf(hex, sizeof(hex), "%02x ", res[i] & 0xff);
+        strlcat(buff, hex, sizeof(buff));
+      }
+      DEBUG_BSSL("insecure_end_chain: received %s\n", buff);
+#endif
       return BR_ERR_X509_NOT_TRUSTED;
     }