Introduce SSLClient library based on WiFiClientSecure

CMakeLists.txt

@@ -99,6 +99,7 @@ set(ARDUINO_ALL_LIBRARIES
   SimpleBLE
   SPIFFS
   SPI
+  SSLClient
   Ticker
   Update
   USB
@@ -175,6 +176,10 @@ set(ARDUINO_LIBRARY_SPIFFS_SRCS libraries/SPIFFS/src/SPIFFS.cpp)
 
 set(ARDUINO_LIBRARY_SPI_SRCS libraries/SPI/src/SPI.cpp)
 
+set(ARDUINO_LIBRARY_SSLClient_SRCS
+  libraries/SSLClient/src/ssl_client.cpp
+  libraries/SSLClient/src/SSLClient.cpp)
+
 set(ARDUINO_LIBRARY_Ticker_SRCS libraries/Ticker/src/Ticker.cpp)
 
 set(ARDUINO_LIBRARY_Update_SRCS

libraries/SSLClient/README.md

@@ -0,0 +1,83 @@
+SSLClient
+=========
+
+The SSLClient class implements support for secure connections using TLS (SSL).
+It inherits from Client and thus implements a superset of that class' interface.
+There are three ways to establish a secure connection using the SSLClient class:
+using a root certificate authority (CA) cert, using a root CA cert plus a client cert and key,
+and using a pre-shared key (PSK).
+
+Using a root certificate authority cert
+---------------------------------------
+This method authenticates the server and negotiates an encrypted connection.
+It is the same functionality as implemented in your web browser when you connect to HTTPS sites.
+
+If you are accessing your own server:
+- Generate a root certificate for your own certificate authority
+- Generate a cert & private key using your root certificate ("self-signed cert") for your server
+
+If you are accessing a public server:
+- Obtain the cert of the public CA that signed that server's cert
+Then:
+- In SSLClient use setCACert (or the appropriate connect method) to set the root cert of your
+  CA or of the public CA
+- When SSLClient connects to the target server it uses the CA cert to verify the certificate
+  presented by the server, and then negotiates encryption for the connection
+
+Please see the SSLClient example.
+
+Using a root CA cert and client cert/keys
+-----------------------------------------
+This method authenticates the server and additionally also authenticates
+the client to the server, then negotiates an encrypted connection.
+
+- Follow steps above
+- Using your root CA generate cert/key for your client
+- Register the keys with the server you will be accessing so the server can authenticate your client
+- In SSLClient use setCACert (or the appropriate connect method) to set the root cert of your
+  CA or of the public CA, this is used to authenticate the server
+- In SSLClient use setCertificate, and setPrivateKey (or the appropriate connect method) to
+  set your client's cert & key, this will be used to authenticate your client to the server
+- When SSLClient connects to the target server it uses the CA cert to verify the certificate
+  presented by the server, it will use the cert/key to authenticate your client to the server, and
+  it will then negotiate encryption for the connection
+
+Using Pre-Shared Keys (PSK)
+---------------------------
+
+TLS supports authentication and encryption using a pre-shared key (i.e. a key that both client and
+server know) as an alternative to the public key cryptography commonly used on the web for HTTPS.
+PSK is starting to be used for MQTT, e.g. in mosquitto, to simplify the set-up and avoid having to
+go through the whole CA, cert, and private key process.
+
+A pre-shared key is a binary string of up to 32 bytes and is commonly represented in hex form. In
+addition to the key, clients can also present an id and typically the server allows a different key
+to be associated with each client id. In effect this is very similar to username and password pairs,
+except that unlike a password the key is not directly transmitted to the server, thus a connection to a
+malicious server does not divulge the password. Plus the server is also authenticated to the client.
+
+To use PSK:
+- Generate a random hex string (generating an MD5 or SHA for some file is one way to do this)
+- Come up with a string id for your client and configure your server to accept the id/key pair
+- In SSLClient use setPreSharedKey (or the appropriate connect method) to
+  set the id/key combo
+- When SSLClient connects to the target server it uses the id/key combo to authenticate the
+  server (it must prove that it has the key too), authenticate the client and then negotiate
+  encryption for the connection
+
+Please see the SSLClientPSK example.
+
+Specifying the ALPN Protocol
+----------------------------
+
+Application-Layer Protocol Negotiation (ALPN) is a Transport Layer Security (TLS) extension that allows
+the application layer to negotiate which protocol should be performed over a secure connection in a manner
+that avoids additional round trips and which is independent of the application-layer protocols.
+
+For example, this is used with AWS IoT Custom Authorizers where an MQTT client must set the ALPN protocol to ```mqtt```:
+
+```
+const char *aws_protos[] = {"mqtt", NULL};
+...
+sslClient.setAlpnProtocols(aws_protos);
+```

libraries/SSLClient/examples/WiFiClientInsecure/WiFiClientInsecure.ino

@@ -0,0 +1,63 @@
+#include <WiFi.h>
+#include <SSLClient.h>
+
+const char* ssid     = "your-ssid";     // your network SSID (name of wifi network)
+const char* password = "your-password"; // your network password
+
+const char*  server = "www.howsmyssl.com";  // Server URL
+
+WiFiClient wificlient;
+SSLClient  client(wificlient);
+
+void setup() {
+  //Initialize serial and wait for port to open:
+  Serial.begin(115200);
+  delay(100);
+
+  Serial.print("Attempting to connect to SSID: ");
+  Serial.println(ssid);
+  WiFi.begin(ssid, password);
+
+  // attempt to connect to Wifi network:
+  while (WiFi.status() != WL_CONNECTED) {
+    Serial.print(".");
+    // wait 1 second for re-trying
+    delay(1000);
+  }
+
+  Serial.print("Connected to ");
+  Serial.println(ssid);
+
+  Serial.println("\nStarting connection to server...");
+  client.setInsecure();//skip verification
+  if (!client.connect(server, 443))
+    Serial.println("Connection failed!");
+  else {
+    Serial.println("Connected to server!");
+    // Make a HTTP request:
+    client.println("GET https://www.howsmyssl.com/a/check HTTP/1.0");
+    client.println("Host: www.howsmyssl.com");
+    client.println("Connection: close");
+    client.println();
+
+    while (client.connected()) {
+      String line = client.readStringUntil('\n');
+      if (line == "\r") {
+        Serial.println("headers received");
+        break;
+      }
+    }
+    // if there are incoming bytes available
+    // from the server, read them and print them:
+    while (client.available()) {
+      char c = client.read();
+      Serial.write(c);
+    }
+
+    client.stop();
+  }
+}
+
+void loop() {
+  // do nothing
+}

libraries/SSLClient/examples/WiFiClientPSK/WiFiClientPSK.ino

@@ -0,0 +1,87 @@
+/*
+  Wifi secure connection example for ESP32 using a pre-shared key (PSK)
+  This is useful with MQTT servers instead of using a self-signed cert, tested with mosquitto.
+  Running on TLS 1.2 using mbedTLS
+
+  To test run a test server using: openssl s_server -accept 8443 -psk 1a2b3c4d -nocert
+  It will show the http request made, but there's no easy way to send a reply back...
+
+  2017 - Evandro Copercini - Apache 2.0 License.
+  2018 - Adapted for PSK by Thorsten von Eicken
+*/
+
+#include <WiFi.h>
+#include <SSLClient.h>
+
+#if 0
+const char* ssid     = "your-ssid";     // your network SSID (name of wifi network)
+const char* password = "your-password"; // your network password
+#else
+const char* ssid     = "test";     // your network SSID (name of wifi network)
+const char* password = "securetest"; // your network password
+#endif
+
+//const char*  server = "server.local";  // Server hostname
+const IPAddress server = IPAddress(192, 168, 0, 14);  // Server IP address
+const int    port = 8443; // server's port (8883 for MQTT)
+
+const char*  pskIdent = "Client_identity"; // PSK identity (sometimes called key hint)
+const char*  psKey = "1a2b3c4d"; // PSK Key (must be hex string without 0x)
+
+WiFiClient wificlient;
+SSLClient  client(wificlient);
+
+void setup() {
+  //Initialize serial and wait for port to open:
+  Serial.begin(115200);
+  delay(100);
+
+  Serial.print("Attempting to connect to SSID: ");
+  Serial.println(ssid);
+  WiFi.begin(ssid, password);
+
+  // attempt to connect to Wifi network:
+  while (WiFi.status() != WL_CONNECTED) {
+    Serial.print(".");
+    // wait 1 second for re-trying
+    delay(1000);
+  }
+
+  Serial.print("Connected to ");
+  Serial.println(ssid);
+
+  client.setPreSharedKey(pskIdent, psKey);
+
+  Serial.println("\nStarting connection to server...");
+  if (!client.connect(server, port))
+    Serial.println("Connection failed!");
+  else {
+    Serial.println("Connected to server!");
+    // Make a HTTP request:
+    client.println("GET /a/check HTTP/1.0");
+    client.print("Host: ");
+    client.println(server);
+    client.println("Connection: close");
+    client.println();
+
+    while (client.connected()) {
+      String line = client.readStringUntil('\n');
+      if (line == "\r") {
+        Serial.println("headers received");
+        break;
+      }
+    }
+    // if there are incoming bytes available
+    // from the server, read them and print them:
+    while (client.available()) {
+      char c = client.read();
+      Serial.write(c);
+    }
+
+    client.stop();
+  }
+}
+
+void loop() {
+  // do nothing
+}

libraries/SSLClient/examples/WiFiClientSecure/WiFiClientSecure.ino

@@ -0,0 +1,105 @@
+/*
+  Wifi secure connection example for ESP32
+  Running on TLS 1.2 using mbedTLS
+  Suporting the following chipersuites:
+  "TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384","TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384","TLS_DHE_RSA_WITH_AES_256_GCM_SHA384","TLS_ECDHE_ECDSA_WITH_AES_256_CCM","TLS_DHE_RSA_WITH_AES_256_CCM","TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384","TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384","TLS_DHE_RSA_WITH_AES_256_CBC_SHA256","TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA","TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA","TLS_DHE_RSA_WITH_AES_256_CBC_SHA","TLS_ECDHE_ECDSA_WITH_AES_256_CCM_8","TLS_DHE_RSA_WITH_AES_256_CCM_8","TLS_ECDHE_ECDSA_WITH_CAMELLIA_256_GCM_SHA384","TLS_ECDHE_RSA_WITH_CAMELLIA_256_GCM_SHA384","TLS_DHE_RSA_WITH_CAMELLIA_256_GCM_SHA384","TLS_ECDHE_ECDSA_WITH_CAMELLIA_256_CBC_SHA384","TLS_ECDHE_RSA_WITH_CAMELLIA_256_CBC_SHA384","TLS_DHE_RSA_WITH_CAMELLIA_256_CBC_SHA256","TLS_DHE_RSA_WITH_CAMELLIA_256_CBC_SHA","TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256","TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256","TLS_DHE_RSA_WITH_AES_128_GCM_SHA256","TLS_ECDHE_ECDSA_WITH_AES_128_CCM","TLS_DHE_RSA_WITH_AES_128_CCM","TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256","TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256","TLS_DHE_RSA_WITH_AES_128_CBC_SHA256","TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA","TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA","TLS_DHE_RSA_WITH_AES_128_CBC_SHA","TLS_ECDHE_ECDSA_WITH_AES_128_CCM_8","TLS_DHE_RSA_WITH_AES_128_CCM_8","TLS_ECDHE_ECDSA_WITH_CAMELLIA_128_GCM_SHA256","TLS_ECDHE_RSA_WITH_CAMELLIA_128_GCM_SHA256","TLS_DHE_RSA_WITH_CAMELLIA_128_GCM_SHA256","TLS_ECDHE_ECDSA_WITH_CAMELLIA_128_CBC_SHA256","TLS_ECDHE_RSA_WITH_CAMELLIA_128_CBC_SHA256","TLS_DHE_RSA_WITH_CAMELLIA_128_CBC_SHA256","TLS_DHE_RSA_WITH_CAMELLIA_128_CBC_SHA","TLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA","TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA","TLS_DHE_RSA_WITH_3DES_EDE_CBC_SHA","TLS_DHE_PSK_WITH_AES_256_GCM_SHA384","TLS_DHE_PSK_WITH_AES_256_CCM","TLS_ECDHE_PSK_WITH_AES_256_CBC_SHA384","TLS_DHE_PSK_WITH_AES_256_CBC_SHA384","TLS_ECDHE_PSK_WITH_AES_256_CBC_SHA","TLS_DHE_PSK_WITH_AES_256_CBC_SHA","TLS_DHE_PSK_WITH_CAMELLIA_256_GCM_SHA384","TLS_ECDHE_PSK_WITH_CAMELLIA_256_CBC_SHA384","TLS_DHE_PSK_WITH_CAMELLIA_256_CBC_SHA384","TLS_PSK_DHE_WITH_AES_256_CCM_8","TLS_DHE_PSK_WITH_AES_128_GCM_SHA256","TLS_DHE_PSK_WITH_AES_128_CCM","TLS_ECDHE_PSK_WITH_AES_128_CBC_SHA256","TLS_DHE_PSK_WITH_AES_128_CBC_SHA256","TLS_ECDHE_PSK_WITH_AES_128_CBC_SHA","TLS_DHE_PSK_WITH_AES_128_CBC_SHA","TLS_DHE_PSK_WITH_CAMELLIA_128_GCM_SHA256","TLS_DHE_PSK_WITH_CAMELLIA_128_CBC_SHA256","TLS_ECDHE_PSK_WITH_CAMELLIA_128_CBC_SHA256","TLS_PSK_DHE_WITH_AES_128_CCM_8","TLS_ECDHE_PSK_WITH_3DES_EDE_CBC_SHA","TLS_DHE_PSK_WITH_3DES_EDE_CBC_SHA","TLS_RSA_WITH_AES_256_GCM_SHA384","TLS_RSA_WITH_AES_256_CCM","TLS_RSA_WITH_AES_256_CBC_SHA256","TLS_RSA_WITH_AES_256_CBC_SHA","TLS_ECDH_RSA_WITH_AES_256_GCM_SHA384","TLS_ECDH_RSA_WITH_AES_256_CBC_SHA384","TLS_ECDH_RSA_WITH_AES_256_CBC_SHA","TLS_ECDH_ECDSA_WITH_AES_256_GCM_SHA384","TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA384","TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA","TLS_RSA_WITH_AES_256_CCM_8","TLS_RSA_WITH_CAMELLIA_256_GCM_SHA384","TLS_RSA_WITH_CAMELLIA_256_CBC_SHA256","TLS_RSA_WITH_CAMELLIA_256_CBC_SHA","TLS_ECDH_RSA_WITH_CAMELLIA_256_GCM_SHA384","TLS_ECDH_RSA_WITH_CAMELLIA_256_CBC_SHA384","TLS_ECDH_ECDSA_WITH_CAMELLIA_256_GCM_SHA384","TLS_ECDH_ECDSA_WITH_CAMELLIA_256_CBC_SHA384","TLS_RSA_WITH_AES_128_GCM_SHA256","TLS_RSA_WITH_AES_128_CCM","TLS_RSA_WITH_AES_128_CBC_SHA256","TLS_RSA_WITH_AES_128_CBC_SHA","TLS_ECDH_RSA_WITH_AES_128_GCM_SHA256","TLS_ECDH_RSA_WITH_AES_128_CBC_SHA256","TLS_ECDH_RSA_WITH_AES_128_CBC_SHA","TLS_ECDH_ECDSA_WITH_AES_128_GCM_SHA256","TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA256","TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA","TLS_RSA_WITH_AES_128_CCM_8","TLS_RSA_WITH_CAMELLIA_128_GCM_SHA256","TLS_RSA_WITH_CAMELLIA_128_CBC_SHA256","TLS_RSA_WITH_CAMELLIA_128_CBC_SHA","TLS_ECDH_RSA_WITH_CAMELLIA_128_GCM_SHA256","TLS_ECDH_RSA_WITH_CAMELLIA_128_CBC_SHA256","TLS_ECDH_ECDSA_WITH_CAMELLIA_128_GCM_SHA256","TLS_ECDH_ECDSA_WITH_CAMELLIA_128_CBC_SHA256","TLS_RSA_WITH_3DES_EDE_CBC_SHA","TLS_ECDH_RSA_WITH_3DES_EDE_CBC_SHA","TLS_ECDH_ECDSA_WITH_3DES_EDE_CBC_SHA","TLS_RSA_PSK_WITH_AES_256_GCM_SHA384","TLS_RSA_PSK_WITH_AES_256_CBC_SHA384","TLS_RSA_PSK_WITH_AES_256_CBC_SHA","TLS_RSA_PSK_WITH_CAMELLIA_256_GCM_SHA384","TLS_RSA_PSK_WITH_CAMELLIA_256_CBC_SHA384","TLS_RSA_PSK_WITH_AES_128_GCM_SHA256","TLS_RSA_PSK_WITH_AES_128_CBC_SHA256","TLS_RSA_PSK_WITH_AES_128_CBC_SHA","TLS_RSA_PSK_WITH_CAMELLIA_128_GCM_SHA256","TLS_RSA_PSK_WITH_CAMELLIA_128_CBC_SHA256","TLS_RSA_PSK_WITH_3DES_EDE_CBC_SHA","TLS_PSK_WITH_AES_256_GCM_SHA384","TLS_PSK_WITH_AES_256_CCM","TLS_PSK_WITH_AES_256_CBC_SHA384","TLS_PSK_WITH_AES_256_CBC_SHA","TLS_PSK_WITH_CAMELLIA_256_GCM_SHA384","TLS_PSK_WITH_CAMELLIA_256_CBC_SHA384","TLS_PSK_WITH_AES_256_CCM_8","TLS_PSK_WITH_AES_128_GCM_SHA256","TLS_PSK_WITH_AES_128_CCM","TLS_PSK_WITH_AES_128_CBC_SHA256","TLS_PSK_WITH_AES_128_CBC_SHA","TLS_PSK_WITH_CAMELLIA_128_GCM_SHA256","TLS_PSK_WITH_CAMELLIA_128_CBC_SHA256","TLS_PSK_WITH_AES_128_CCM_8","TLS_PSK_WITH_3DES_EDE_CBC_SHA","TLS_EMPTY_RENEGOTIATION_INFO_SCSV"]
+  2017 - Evandro Copercini - Apache 2.0 License.
+*/
+
+#include <WiFi.h>
+#include <SSLClient.h>
+
+const char* ssid     = "your-ssid";     // your network SSID (name of wifi network)
+const char* password = "your-password"; // your network password
+
+const char*  server = "www.howsmyssl.com";  // Server URL
+
+// www.howsmyssl.com root certificate authority, to verify the server
+// change it to your server root CA
+// SHA1 fingerprint is broken now!
+
+const char* test_root_ca= \
+     "-----BEGIN CERTIFICATE-----\n" \
+     "MIIDSjCCAjKgAwIBAgIQRK+wgNajJ7qJMDmGLvhAazANBgkqhkiG9w0BAQUFADA/\n" \
+     "MSQwIgYDVQQKExtEaWdpdGFsIFNpZ25hdHVyZSBUcnVzdCBDby4xFzAVBgNVBAMT\n" \
+     "DkRTVCBSb290IENBIFgzMB4XDTAwMDkzMDIxMTIxOVoXDTIxMDkzMDE0MDExNVow\n" \
+     "PzEkMCIGA1UEChMbRGlnaXRhbCBTaWduYXR1cmUgVHJ1c3QgQ28uMRcwFQYDVQQD\n" \
+     "Ew5EU1QgUm9vdCBDQSBYMzCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEB\n" \
+     "AN+v6ZdQCINXtMxiZfaQguzH0yxrMMpb7NnDfcdAwRgUi+DoM3ZJKuM/IUmTrE4O\n" \
+     "rz5Iy2Xu/NMhD2XSKtkyj4zl93ewEnu1lcCJo6m67XMuegwGMoOifooUMM0RoOEq\n" \
+     "OLl5CjH9UL2AZd+3UWODyOKIYepLYYHsUmu5ouJLGiifSKOeDNoJjj4XLh7dIN9b\n" \
+     "xiqKqy69cK3FCxolkHRyxXtqqzTWMIn/5WgTe1QLyNau7Fqckh49ZLOMxt+/yUFw\n" \
+     "7BZy1SbsOFU5Q9D8/RhcQPGX69Wam40dutolucbY38EVAjqr2m7xPi71XAicPNaD\n" \
+     "aeQQmxkqtilX4+U9m5/wAl0CAwEAAaNCMEAwDwYDVR0TAQH/BAUwAwEB/zAOBgNV\n" \
+     "HQ8BAf8EBAMCAQYwHQYDVR0OBBYEFMSnsaR7LHH62+FLkHX/xBVghYkQMA0GCSqG\n" \
+     "SIb3DQEBBQUAA4IBAQCjGiybFwBcqR7uKGY3Or+Dxz9LwwmglSBd49lZRNI+DT69\n" \
+     "ikugdB/OEIKcdBodfpga3csTS7MgROSR6cz8faXbauX+5v3gTt23ADq1cEmv8uXr\n" \
+     "AvHRAosZy5Q6XkjEGB5YGV8eAlrwDPGxrancWYaLbumR9YbK+rlmM6pZW87ipxZz\n" \
+     "R8srzJmwN0jP41ZL9c8PDHIyh8bwRLtTcm1D9SZImlJnt1ir/md2cXjbDaJWFBM5\n" \
+     "JDGFoqgCWjBH4d1QB7wCCZAA62RjYJsWvIjJEubSfZGL+T0yjWW06XyxV3bqxbYo\n" \
+     "Ob8VZRzI9neWagqNdwvYkQsEjgfbKbYK7p2CNTUQ\n" \
+     "-----END CERTIFICATE-----\n";
+
+// You can use x.509 client certificates if you want
+//const char* test_client_key = "";   //to verify the client
+//const char* test_client_cert = "";  //to verify the client
+
+
+WiFiClient wificlient;
+SSLClient  client(wificlient);
+
+void setup() {
+  //Initialize serial and wait for port to open:
+  Serial.begin(115200);
+  delay(100);
+
+  Serial.print("Attempting to connect to SSID: ");
+  Serial.println(ssid);
+  WiFi.begin(ssid, password);
+
+  // attempt to connect to Wifi network:
+  while (WiFi.status() != WL_CONNECTED) {
+    Serial.print(".");
+    // wait 1 second for re-trying
+    delay(1000);
+  }
+
+  Serial.print("Connected to ");
+  Serial.println(ssid);
+
+  client.setCACert(test_root_ca);
+  //client.setCertificate(test_client_cert); // for client verification
+  //client.setPrivateKey(test_client_key);	// for client verification
+
+  Serial.println("\nStarting connection to server...");
+  if (!client.connect(server, 443))
+    Serial.println("Connection failed!");
+  else {
+    Serial.println("Connected to server!");
+    // Make a HTTP request:
+    client.println("GET https://www.howsmyssl.com/a/check HTTP/1.0");
+    client.println("Host: www.howsmyssl.com");
+    client.println("Connection: close");
+    client.println();
+
+    while (client.connected()) {
+      String line = client.readStringUntil('\n');
+      if (line == "\r") {
+        Serial.println("headers received");
+        break;
+      }
+    }
+    // if there are incoming bytes available
+    // from the server, read them and print them:
+    while (client.available()) {
+      char c = client.read();
+      Serial.write(c);
+    }
+
+    client.stop();
+  }
+}
+
+void loop() {
+  // do nothing
+}