Support for STARTLS/STARTSSL in-band transport upgrades/renegotation

libraries/WiFiClientSecure/examples/WiFIClientSecureProtocolUpgradeSTARTTLS/WiFIClientSecureProtocolUpgradeSTARTTLS.ino

@@ -0,0 +1,179 @@
+/* STARTSSL example
+
+   Inline upgrading from a clear-text connection to an SSL/TLS connection.
+
+   Some protocols such as SMTP, XMPP, Mysql, Postgress and others allow, or require,
+   that you start the connection without encryption; and then send a command to switch
+   over to encryption.
+
+   E.g. a typical SMTP submission would entail a dialogue such as this:
+
+   1. client connects to server in the clear
+   2. server says hello
+   3. client sents a EHLO
+   4. server tells the client that it supports SSL/TLS
+   5. client sends a 'STARTTLS' to make use of this faciltiy
+   6. client/server negiotiate a SSL or TLS connection.
+   7. client sends another EHLO
+   8. server now tells the client what (else) is supported; such as additional authentication options.
+   ... conversation continues encrypted.
+
+   This can be enabled in WiFiClientSecure by telling it to start in plaintext:
+
+          client.setPlainStart();
+
+   and client is than a plain, TCP, connection (just as WiFiClient would be); until the client calls
+   the method:
+
+          client.startTLS(); // returns zero on error; non zero on success.
+
+    After which things switch to TLS/SSL.
+*/
+
+#include <WiFiClientSecure.h>
+
+#ifndef WIFI_NETWORK
+#define WIFI_NETWORK "YOUR Wifi SSID"
+#endif
+
+#ifndef WIFI_PASSWD
+#define WIFI_PASSWD "your-secret-password"
+#endif
+
+#ifndef SMTP_HOST
+#define SMTP_HOST "smtp.gmail.com"
+#endif
+
+#ifndef SMTP_PORT
+#define SMTP_PORT (587) // Standard (plaintext) submission port
+#endif
+
+const char* ssid     = WIFI_NETWORK;     // your network SSID (name of wifi network)
+const char* password = WIFI_PASSWD; // your network password
+const char*  server = SMTP_HOST;  // Server URL
+const int submission_port = SMTP_PORT; // submission port.
+
+WiFiClientSecure client;
+
+static bool readAllSMTPLines();
+
+void setup() {
+  int ret;
+  //Initialize serial and wait for port to open:
+  Serial.begin(115200);
+  delay(100);
+
+  Serial.print("Attempting to connect to SSID: ");
+  Serial.print(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.printf("\nStarting connection to server: %s:%d\n", server, submission_port);
+
+
+  // skip verification for this demo. In production one should at the very least
+  // enable TOFU; or ideally hardcode a (CA) certificate that is trusted.
+  //
+  client.setInsecure();
+
+  // Enable a plain-test start.
+  client.setPlainStart();
+
+  if (!client.connect(server, SMTP_PORT)) {
+    Serial.println("Connection failed!");
+    return;
+  };
+
+  Serial.println("Connected to server (in the clear, in plaintest)");
+
+  if (!readAllSMTPLines()) goto err;
+
+  Serial.println("Sending  : EHLO\t\tin the clear");
+  client.print("EHLO there\r\n");
+
+  if (!readAllSMTPLines()) goto err;
+
+  Serial.println("Sending  : STARTTLS\t\tin the clear");
+  client.print("STARTTLS\r\n");
+
+  if (!readAllSMTPLines()) goto err;
+
+  Serial.println("Upgrading connection to TLS");
+  if ((ret=client.startTLS()) <= 0) {
+    Serial.printf("Upgrade connection failed: err %d\n", ret);
+    goto err;
+  }
+
+  Serial.println("Sending  : EHLO again\t\tover the now encrypted connection");
+  client.print("EHLO again\r\n");
+
+  if (!readAllSMTPLines()) goto err;
+
+  // normally, as this point - we'd be authenticating and then be submitting
+  // an email. This has been left out of this example.
+
+  Serial.println("Sending  : QUIT\t\t\tover the now encrypted connection");
+  client.print("QUIT\r\n");
+
+  if (!readAllSMTPLines()) goto err;
+
+  Serial.println("Completed OK\n");
+err:
+  Serial.println("Closing connection");
+  client.stop();
+}
+
+// SMTP command repsponse start with three digits and a space;
+// or, for continuation, with three digits and a '-'.
+//
+static bool readAllSMTPLines() {
+  String s = "";
+  int i;
+
+  // blocking read; we cannot rely on a timeout
+  // of a WiFiClientSecure read; as it is non
+  // blocking.
+  //
+  const unsigned long timeout = 15 * 1000;
+  unsigned long start = millis(); // the timeout is for the entire CMD block response; not per character/line.
+  while (1) {
+    while ((i = client.available()) == 0 && millis() - start < timeout) {
+      /* .. wait */
+    };
+    if (i == 0) {
+      Serial.println("Timeout reading SMTP response");
+      return false;
+    };
+    if (i < 0)
+      break;
+
+    i = client.read();
+    if (i < 0)
+      break;
+
+    if (i > 31 && i < 128) s += (char)i;
+    if (i == 0x0A) {
+      Serial.print("Receiving: ");
+      Serial.println(s);
+      if (s.charAt(3) == ' ')
+        return true;
+      s = "";
+    }
+  }
+  Serial.printf("Error reading SMTP command response line: %d\n", i);
+  return false;
+}
+
+void loop() {
+  // do nothing
+}
+

libraries/WiFiClientSecure/src/WiFiClientSecure.cpp

@@ -143,16 +143,40 @@ int WiFiClientSecure::connect(const char *host, uint16_t port, const char *CA_ce
 int WiFiClientSecure::connect(IPAddress ip, uint16_t port, const char *host, const char *CA_cert, const char *cert, const char *private_key)
 {
     int ret = start_ssl_client(sslclient, ip, port, host, _timeout, CA_cert, _use_ca_bundle, cert, private_key, NULL, NULL, _use_insecure, _alpn_protos);
+
+    if (ret >=0 && ! _stillinPlainStart)
+        ret = ssl_starttls_handshake(sslclient);
+    else
+        log_i("Actual TLS start posponed.");
+
     _lastError = ret;
+
     if (ret < 0) {
-        log_e("start_ssl_client: %d", ret);
+        log_e("start_ssl_client: connect failed: %d", ret);
         stop();
         return 0;
     }
     _connected = true;
     return 1;
 }
 
+int WiFiClientSecure::startTLS()
+{
+    int ret = 1;
+    if (_stillinPlainStart) {
+        log_i("startTLS: starting TLS/SSL on this dplain connection");
+        ret = ssl_starttls_handshake(sslclient);
+        if (ret < 0) {
+                log_e("startTLS: %d", ret);
+                stop();
+                return 0;
+        };
+        _stillinPlainStart = false;
+    } else 
+        log_e("startTLS: ignoring StartTLS - as we should be secure already");
+    return 1;
+}
+
 int WiFiClientSecure::connect(IPAddress ip, uint16_t port, const char *pskIdent, const char *psKey) {
     return connect(ip.toString().c_str(), port, pskIdent, psKey);
 }
@@ -167,7 +191,7 @@ int WiFiClientSecure::connect(const char *host, uint16_t port, const char *pskId
     int ret = start_ssl_client(sslclient, address, port, host, _timeout, NULL, false, NULL, NULL, pskIdent, psKey, _use_insecure, _alpn_protos);
     _lastError = ret;
     if (ret < 0) {
-        log_e("start_ssl_client: %d", ret);
+        log_e("start_ssl_client: connect failed %d", ret);
         stop();
         return 0;
     }
@@ -192,17 +216,18 @@ int WiFiClientSecure::read()
 {
     uint8_t data = -1;
     int res = read(&data, 1);
-    if (res < 0) {
-        return res;
-    }
-    return data;
+    return res < 0 ? res: data;
 }
 
 size_t WiFiClientSecure::write(const uint8_t *buf, size_t size)
 {
     if (!_connected) {
         return 0;
     }
+
+    if (_stillinPlainStart) 
+        return send_net_data(sslclient, buf, size);
+
     if(_lastWriteTimeout != _timeout){
         struct timeval timeout_tv;
         timeout_tv.tv_sec = _timeout / 1000;
@@ -212,9 +237,9 @@ size_t WiFiClientSecure::write(const uint8_t *buf, size_t size)
             _lastWriteTimeout = _timeout;
         }
     }
-
     int res = send_ssl_data(sslclient, buf, size);
     if (res < 0) {
+        log_e("Closing connection on failed write");
         stop();
         res = 0;
     }
@@ -223,6 +248,9 @@ size_t WiFiClientSecure::write(const uint8_t *buf, size_t size)
 
 int WiFiClientSecure::read(uint8_t *buf, size_t size)
 {
+    if(_stillinPlainStart) 
+        return  get_net_receive(sslclient, buf, size);
+
     if(_lastReadTimeout != _timeout){
         if(fd() >= 0){
             struct timeval timeout_tv;
@@ -235,7 +263,7 @@ int WiFiClientSecure::read(uint8_t *buf, size_t size)
         }
     }
 
-    int peeked = 0;
+    int peeked = 0, res = -1;
     int avail = available();
     if ((!buf && size) || avail <= 0) {
         return -1;
@@ -254,9 +282,10 @@ int WiFiClientSecure::read(uint8_t *buf, size_t size)
         buf++;
         peeked = 1;
     }
-
-    int res = get_ssl_receive(sslclient, buf, size);
+        res = get_ssl_receive(sslclient, buf, size);
+
     if (res < 0) {
+        log_d("Closing connection on failed read");
         stop();
         return peeked?peeked:res;
     }
@@ -265,12 +294,17 @@ int WiFiClientSecure::read(uint8_t *buf, size_t size)
 
 int WiFiClientSecure::available()
 {
-    int peeked = (_peek >= 0);
+    if (_stillinPlainStart) 
+        return peek_net_receive(sslclient,0);
+
+    int peeked = (_peek >= 0), res = -1;
     if (!_connected) {
         return peeked;
     }
-    int res = data_to_read(sslclient);
-    if (res < 0) {
+    res = data_to_read(sslclient);
+
+    if (res < 0 && !_stillinPlainStart) {
+        log_e("Closing connection on failed avail check");
         stop();
         return peeked?peeked:res;
     }
@@ -305,7 +339,7 @@ void WiFiClientSecure::setCACert (const char *rootCA)
  {
     if (bundle != NULL)
     {
-        esp_crt_bundle_set(bundle, sizeof(bundle));
+        esp_crt_bundle_set(bundle,sizeof(bundle));
         _use_ca_bundle = true;
     } else {
         esp_crt_bundle_detach(NULL);
@@ -406,3 +440,4 @@ int WiFiClientSecure::fd() const
 {
     return sslclient->socket;
 }
+

libraries/WiFiClientSecure/src/WiFiClientSecure.h

@@ -34,6 +34,7 @@ class WiFiClientSecure : public WiFiClient
     int _peek = -1;
     int _timeout;
     bool _use_insecure;
+    bool _stillinPlainStart = false;
     const char *_CA_cert;
     const char *_cert;
     const char *_private_key;
@@ -78,6 +79,17 @@ class WiFiClientSecure : public WiFiClient
     bool verify(const char* fingerprint, const char* domain_name);
     void setHandshakeTimeout(unsigned long handshake_timeout);
     void setAlpnProtocols(const char **alpn_protos);
+
+    // Certain protocols start in plain-text; and then have the client
+    // give some STARTSSL command to `upgrade' the connection to TLS
+    // or SSL. setting PlainStart to true (the default is false) enables
+    // this. It is up to the application code to then call 'startTLS()'
+    // at the right point to initialise the SSL or TLS upgrade.
+    //
+    void setPlainStart() { _stillinPlainStart = true; };
+    bool stillInPlainStart() { return _stillinPlainStart; };
+    int startTLS();
+
     const mbedtls_x509_crt* getPeerCertificate() { return mbedtls_ssl_get_peer_cert(&sslclient->ssl_ctx); };
     bool getFingerprintSHA256(uint8_t sha256_result[32]) { return get_peer_fingerprint(sslclient, sha256_result); };
     int fd() const;