Add support for CA bundles (#885)

Why:

- Allow CA cert bundles to be used

This change addresses the need by:

- Adding a constructor that takes a pointer to the bundle
- Setting the WiFiClientSecure to use the bundle
- Adding an example

Author: moritz89

README.md

@@ -48,6 +48,16 @@ a WebSocket Server and Client for Arduino based on RFC6455.
    by running the device behind an SSL proxy. See [Nginx](examples/Nginx/esp8266.ssl.reverse.proxy.conf) for a
    sample Nginx server configuration file to enable this.
 
+### Root CA Cert Bundles for SSL/TLS connections ###
+
+Secure connections require the certificate of the server to be verified. One option is to provide a single certificate in the chain of trust. However, for flexibility and robustness, a certificate bundle is recommended. If a server changes the root CA from which it derives its certificates, this will not be a problem. With a single CA cert it will not connect.
+
+ - For [technical details](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/protocols/esp_crt_bundle.html)
+ - For a [PlatformIO setup](https://github.com/Duckle29/esp32-certBundle/)
+ - For an [example](examples/esp32/WebSocketClientSSLBundle/)
+
+Including a bundle with all CA certs will use 77.2 kB but this list can be reduced to 16.5 kB for the 41 most common. This results in 90% absolute usage coverage and 99% market share coverage according to [W3Techs](https://w3techs.com/technologies/overview/ssl_certificate). The bundle is inserted into the compiled firmware. The bundle is not loaded into RAM, only its index.
+
 ### ESP Async TCP ###
 
 This libary can run in Async TCP mode on the ESP.

examples/esp32/WebSocketClientSSLBundle/WebSocketClientSSLBundle.ino

@@ -0,0 +1,129 @@
+/*
+ * main.cpp
+ *
+ *  Created on: 15.06.2024
+ *
+ */
+
+#include <Arduino.h>
+#include <WiFi.h>
+#include <WiFiMulti.h>
+
+#include <WebSocketsClient.h>
+
+// Use the incbin library to embedd the cert binary
+// extern const uint8_t rootca_crt_bundle_start[] asm(
+//     "_binary_data_cert_x509_crt_bundle_bin_start");
+
+WiFiMulti wifiMulti;
+WebSocketsClient webSocket;
+
+#define USE_SERIAL Serial
+
+void setClock() {
+    configTime(0, 0, "pool.ntp.org", "time.nist.gov");
+
+    USE_SERIAL.print(F("Waiting for NTP time sync: "));
+    time_t nowSecs = time(nullptr);
+    while(nowSecs < 8 * 3600 * 2) {
+        delay(500);
+        USE_SERIAL.print(F("."));
+        yield();
+        nowSecs = time(nullptr);
+    }
+
+    USE_SERIAL.println();
+    struct tm timeinfo;
+    gmtime_r(&nowSecs, &timeinfo);
+    USE_SERIAL.print(F("Current time: "));
+    USE_SERIAL.print(asctime(&timeinfo));
+}
+
+void hexdump(const void * mem, uint32_t len, uint8_t cols = 16) {
+    const uint8_t * src = (const uint8_t *)mem;
+    USE_SERIAL.printf("\n[HEXDUMP] Address: 0x%08X len: 0x%X (%d)", (ptrdiff_t)src, len, len);
+    for(uint32_t i = 0; i < len; i++) {
+        if(i % cols == 0) {
+            USE_SERIAL.printf("\n[0x%08X] 0x%08X: ", (ptrdiff_t)src, i);
+        }
+        USE_SERIAL.printf("%02X ", *src);
+        src++;
+    }
+    USE_SERIAL.printf("\n");
+}
+
+void webSocketEvent(WStype_t type, uint8_t * payload, size_t length) {
+    switch(type) {
+        case WStype_DISCONNECTED:
+            USE_SERIAL.printf("[WSc] Disconnected!\n");
+            break;
+        case WStype_CONNECTED:
+            USE_SERIAL.printf("[WSc] Connected to url: %s\n", payload);
+
+            // send message to server when Connected
+            webSocket.sendTXT("Connected");
+            break;
+        case WStype_TEXT:
+            USE_SERIAL.printf("[WSc] get text: %s\n", payload);
+
+            // send message to server
+            // webSocket.sendTXT("message here");
+            break;
+        case WStype_BIN:
+            USE_SERIAL.printf("[WSc] get binary length: %u\n", length);
+            hexdump(payload, length);
+
+            // send data to server
+            // webSocket.sendBIN(payload, length);
+            break;
+        case WStype_ERROR:
+        case WStype_FRAGMENT_TEXT_START:
+        case WStype_FRAGMENT_BIN_START:
+        case WStype_FRAGMENT:
+        case WStype_FRAGMENT_FIN:
+            break;
+    }
+}
+
+void setup() {
+    USE_SERIAL.begin(115200);
+
+    USE_SERIAL.setDebugOutput(true);
+
+    USE_SERIAL.println();
+    USE_SERIAL.println();
+    USE_SERIAL.println();
+
+    for(uint8_t t = 4; t > 0; t--) {
+        USE_SERIAL.printf("[SETUP] BOOT WAIT %d...\n", t);
+        USE_SERIAL.flush();
+        delay(1000);
+    }
+
+    wifiMulti.addAP("SSID", "WIFI_PASSPHRASE");
+
+    // WiFi.disconnect();
+    while(wifiMulti.run() != WL_CONNECTED) {
+        delay(100);
+    }
+
+    setClock();
+
+    // server address, port and URL. This server can be flakey.
+    // Expected response: Request served by 0123456789abcdef
+    // webSocket.beginSslWithBundle("echo.websocket.org", 443, "/", rootca_crt_bundle_start, "");
+    webSocket.beginSslWithBundle("echo.websocket.org", 443, "/", NULL, "");
+
+    // event handler
+    webSocket.onEvent(webSocketEvent);
+
+    // use HTTP Basic Authorization this is optional enable if needed
+    // webSocket.setAuthorization("user", "Password");
+
+    // try ever 5000 again if connection has failed
+    webSocket.setReconnectInterval(5000);
+}
+
+void loop() {
+    webSocket.loop();
+}

examples/esp32_pio/WebSocketClientSSLBundle/.gitignore

@@ -0,0 +1,8 @@
+.pio
+.vscode/.browse.c_cpp.db*
+.vscode/c_cpp_properties.json
+.vscode/launch.json
+.vscode/ipch
+*secret*
+!*secrets.hpp.template
+*x509_crt_bundle.bin